@jmp-technologies/analytics

Browser client for POST {baseUrl}/api/events plus published blog, FAQ, and site contact profile (GET /api/content/site) helpers for client websites.

New client website (full process)

1. Deploy JMP Analytics (jmp-dashboard) to a stable HTTPS URL.
2. Create a website row (domain + tracking_key) and assign it to the client user.
3. On the client site: npm install @jmp-technologies/analytics, set NEXT_PUBLIC_JMP_ANALYTICS_URL and NEXT_PUBLIC_JMP_TRACKING_KEY (same key for browser and server in Next.js), wire trackPageView (and optional events).
4. Verify POST /api/events returns 201 and data appears in the dashboard.

Step-by-step checklist: Client onboarding

Standard pattern for every client site (files, server fetch, contact, Astro/Next): jmp-client-site-pattern.md

API, CORS, examples: Tracking integration

Privacy policy, terms, retention, copyright (client sites): Legal & privacy guide — feature checklist and outline copy for only what JMP analytics/content actually uses.

If your GitHub org/repo name differs, replace jmp-technologies/jmp-dashboard in those URLs.

Monorepo / local docs

From this repo, the same files are at docs/jmp-client-site-pattern.md, docs/client-onboarding.md, docs/tracking-integration.md, and packages/jmp-technologies-analytics/docs/legal-and-privacy.md.

Quick setup (env helpers)

Set NEXT_PUBLIC_JMP_ANALYTICS_URL and NEXT_PUBLIC_JMP_TRACKING_KEY (used for browser tracking, server content fetches, and getJmpServerContentConfigFromEnv).

Next.js App Router (least client code)

1. Install peers: react, react-dom, next (already present in a Next app).
2. Set NEXT_PUBLIC_JMP_ANALYTICS_URL and NEXT_PUBLIC_JMP_TRACKING_KEY in Vercel / .env.local (both are inlined into the client bundle at build time).
3. In app/layout.tsx, wrap the app once:

import type { ReactNode } from "react"
import { JmpSiteRoot } from "@jmp-technologies/analytics/next"

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <JmpSiteRoot>{children}</JmpSiteRoot>
      </body>
    </html>
  )
}

JmpSiteRoot enables automatic page_view, landing referrer capture, and delegated tel: / mailto: tracking (on by default for Next; set NEXT_PUBLIC_JMP_AUTO_CONTACT_LINKS=false to disable). No custom useEffect or env shim files in the client repo.

Optional: explicit tracked links (same events as auto-track, useful for styling) — JmpTrackedTelLink and JmpTrackedMailtoLink:

import {
  JmpNextAnalytics,
  JmpTrackedMailtoLink,
  JmpTrackedTelLink,
} from "@jmp-technologies/analytics/next"

<JmpTrackedTelLink href="tel:+15551234567" className="...">
  Call us
</JmpTrackedTelLink>

<JmpTrackedMailtoLink href="mailto:[email protected]" className="...">
  Email us
</JmpTrackedMailtoLink>

Or call trackEmailClick(path) / trackCallClick(path) from useJmpAnalytics().

For SMS / WhatsApp / maps / scheduling link taps, call trackContactClick(path, { channel, linkHost }) — or rely on the Next.js default delegated listener (same as NEXT_PUBLIC_JMP_AUTO_CONTACT_LINKS=true). Per-link opt-out: data-jmp-no-track on the <a> (or any ancestor).

Hooks: useJmpAnalytics() from @jmp-technologies/analytics/next or @jmp-technologies/analytics/react for forms and custom events.

Site key events (not contacts)

Mark any control with a slug. The tracker sends a key_event (counts toward engaged visits). It does not go to the Contacts inbox.

<button data-jmp-event="your_slug" data-jmp-label="Optional label">
  Continue
</button>

Or send a sanitized object of details (same bounds as contact-form metadata):

jmp.trackKeyEvent("estimate_complete", {
  label: "Estimate finished",
  props: { tierId: "landing", minUsd: 4000, maxUsd: 9000 },
})

The event name stays the chart row. props is extra context (numbers, strings, nested objects). Do not put emails or other contact fields here. Names: start with a letter, then letters, numbers, or underscores.

Astro (≥ 0.1.20)

Set PUBLIC_JMP_ANALYTICS_URL and PUBLIC_JMP_TRACKING_KEY (or the NEXT_PUBLIC_* names — both work).

1. jmp.config.ts — defineJmpSite({ ... }) from @jmp-technologies/analytics
2. astro.config.mjs — integrations: [jmpAnalytics()] from @jmp-technologies/analytics/astro/integration
3. src/middleware.ts — export { onRequest } from "@jmp-technologies/analytics/astro/middleware"
4. Content — loadBlogPosts, getResolvedSiteContact from @jmp-technologies/analytics/astro/content

Full checklist: docs/astro-integration.md

Optional server-side page views for crawler visibility

Browser analytics may miss bots/crawlers that do not execute JavaScript. To capture AI crawler user agents more reliably, forward server requests from Next.js proxy.ts or route code:

import {
  getJmpServerContentConfigFromEnv,
  trackJmpServerPageView,
} from "@jmp-technologies/analytics"

export async function proxy(request: Request) {
  const config = getJmpServerContentConfigFromEnv()
  if (config) {
    void trackJmpServerPageView(config, { request }).catch(() => {})
  }
}

Use this only on page routes you want counted. Avoid static assets, health checks, API routes, and duplicate tracking if a page already has browser tracking and you do not want both server and browser page views.

Optional AI crawler robots.txt policy

Clients can switch AI crawler blocking on or off in JMP dashboard settings. To make that setting visible to crawlers, serve the generated policy from the client site's robots.txt route:

import {
  getJmpRobotsTxt,
  getJmpServerContentConfigFromEnv,
} from "@jmp-technologies/analytics"

export async function GET() {
  const config = getJmpServerContentConfigFromEnv()
  const body = config
    ? await getJmpRobotsTxt(config)
    : "# JMP Analytics is not configured.\n"

  return new Response(body, {
    headers: {
      "Content-Type": "text/plain; charset=utf-8",
    },
  })
}

Place that in app/robots.txt/route.ts for Next.js App Router sites. Use mergeJmpRobotsTxt() if the site also needs private-path disallows and a sitemap line. Pass ensureAiCrawlerDisallows: true only when this site should always list AI Disallow rules even if the JMP dashboard toggle is off. The policy uses robots.txt Disallow rules for known AI crawler user agents.

Enforcement: robots.txt is advisory. When this JMP setting is on, also add a vercel.json WAF deny (jmpAiCrawlerVercelWafRoute() or create-jmp-client --block-ai-crawlers) and set Vercel AI Bots to deny. Crawlers that spoof a normal browser or use undisclosed names may still access public pages. Generic Applebot is not WAF-denied so Apple Search can still crawl; Applebot-Extended is denied.

Use ≥ 0.1.41 for the shared crawler list, mergeJmpRobotsTxt, and WAF route helper (0.1.40 source had them; the published types did not).

Manual browser (any framework)

Browser (client components) — one module-level singleton per tab, default pageViewDedupeMs (800):

import { getOrCreateJmpAnalyticsFromBrowserEnv } from "@jmp-technologies/analytics"

const analytics = getOrCreateJmpAnalyticsFromBrowserEnv()
void analytics?.trackPageView()

Server — blog / FAQ / content API:

import { getJmpBlogPosts, getJmpServerContentConfigFromEnv } from "@jmp-technologies/analytics"

export default async function BlogPage() {
  const config = getJmpServerContentConfigFromEnv()
  if (!config) return null
  const posts = await getJmpBlogPosts(config)
  // ...
}

Or createJmpContentClientFromServerEnv() for getBlogPosts() / getBlogPost() / getFaqs() / getSiteProfile() in one object.

Configured? isJmpBrowserAnalyticsEnvConfigured() and isJmpServerContentEnvConfigured().

Site contact profile (footer / contact page)

Manage contact details in the JMP dashboard at /content?tab=contact. The live site reads them from GET {baseUrl}/api/content/site (same tracking key + CORS as blog/FAQ).

import {
  getJmpSiteProfile,
  getJmpServerContentConfigFromEnv,
} from "@jmp-technologies/analytics"

export default async function Footer() {
  const config = getJmpServerContentConfigFromEnv()
  if (!config) return null
  const site = await getJmpSiteProfile(config)

  return (
    <footer>
      {site.phone ? <a href={`tel:${site.phone}`}>{site.phone}</a> : null}
      {site.email ? <a href={`mailto:${site.email}`}>{site.email}</a> : null}
      {site.cta.label && site.cta.url ? (
        <a href={site.cta.url}>{site.cta.label}</a>
      ) : null}
      {/* Developer-defined keys from dashboard (admin configures keys, client fills values): */}
      {site.extras["license-number"] ? (
        <p>License: {site.extras["license-number"]}</p>
      ) : null}
    </footer>
  )
}

JmpSiteProfile includes name, display_name, email, phone, address, hours, service_area, google_maps_url, social (linkedin, instagram, …), cta, legal, extras (record of string keys → values), and optional ga_measurement_id (G-… from dashboard admin).

Optional Google Analytics 4

1. Admin saves ga_measurement_id in jmp-dashboard (Content → Contact).
2. Use JmpSiteRootServer in app/layout.tsx (≥ 0.1.25) — it loads JmpGoogleTag when the dashboard ID is set (or use NEXT_PUBLIC_GA_MEASUREMENT_ID to override).

import { JmpSiteRootServer } from "@jmp-technologies/analytics/next/site-root-server"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <JmpSiteRootServer>{children}</JmpSiteRootServer>
      </body>
    </html>
  )
}

See docs/google-analytics-setup.md in the jmp-dashboard repo.

Blog and FAQ content

Manage content in the JMP dashboard at /content, then render it on the client website from the client site's own routes:

import { getJmpBlogPosts, getJmpServerContentConfigFromEnv } from "@jmp-technologies/analytics"

export default async function BlogPage() {
  const config = getJmpServerContentConfigFromEnv()
  if (!config) return null
  const posts = await getJmpBlogPosts(config)

  return (
    <main>
      <h1>Blog</h1>
      {posts.map((post) => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>{post.excerpt}</p>
        </article>
      ))}
    </main>
  )
}

Service & location landing pages (≥ 0.1.27)

CMS-managed pages at /areas/{slug} and /services/{slug} (plus optional /[locale]/…).

Thin route files — import from @jmp-technologies/analytics/next/landing-pages:

// app/services/[slug]/page.tsx
import {
  JmpLandingDetailPage,
  buildJmpLandingMetadata,
  generateJmpLandingStaticParams,
} from "@jmp-technologies/analytics/next/landing-pages"

export function generateStaticParams() {
  return generateJmpLandingStaticParams("service")
}

export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
  return buildJmpLandingMetadata({ kind: "service", slug })
}

export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
  return <JmpLandingDetailPage kind="service" slug={slug} />
}

Optional components prop for site Markdown, breadcrumbs, and JSON-LD. buildJmpLandingSitemapRoutes merges landing URLs into app/sitemap.ts.

Data loaders remain on @jmp-technologies/analytics/next/content: loadLandingPages, loadLandingPageDetail, loadLandingPageSitemap.

Available helpers:

FAQ items include a stable slug field. Use that slug, rather than the id, when building FAQ URLs so tracked page views are stored as readable paths. When present, category is an optional section label you can use to group FAQs in your UI.

Config from env

• getJmpBrowserAnalyticsConfigFromEnv() / getJmpServerContentConfigFromEnv()
• getOrCreateJmpAnalyticsFromBrowserEnv() (browser singleton)
• createJmpContentClientFromServerEnv()
• isJmpBrowserAnalyticsEnvConfigured() / isJmpServerContentEnvConfigured()

Next.js (@jmp-technologies/analytics/next)

• JmpNextAnalytics / JmpNextPageViewTracker — App Router page views
• Re-exports: JmpTrackedTelLink, JmpTrackedMailtoLink, useJmpAnalytics

Next.js landing routes (@jmp-technologies/analytics/next/landing-pages, ≥ 0.1.27)

• generateJmpLandingStaticParams, generateJmpLocalizedLandingStaticParams
• buildJmpLandingMetadata, buildJmpLandingIndexMetadata
• JmpLandingDetailPage, JmpLandingIndexPage
• buildJmpLandingSitemapRoutes

React (@jmp-technologies/analytics/react)

• JmpTrackedTelLink, JmpTrackedMailtoLink (since 0.1.10), useJmpAnalytics — Vite, CRA, etc. (no automatic route tracking; call trackPageView yourself or use your router)

Tracking events

• trackPageView, trackFormSubmit, trackCallClick, trackEmailClick (since 0.1.10), trackContactClick (since 0.1.18 — SMS, WhatsApp, maps, scheduling), trackLead

Content

• getJmpBlogPosts(config)
• getJmpBlogPost(config, slug)
• getJmpFaqs(config)
• getJmpLandingPages, getJmpLandingPageDetail, getJmpLandingPageSitemap (since 0.1.26; route helpers 0.1.27)
• getJmpSiteProfile(config) — contact + extras (since 0.1.8)
• getJmpRobotsTxt(config)
• createJmpContentClient(config) — includes getSiteProfile()

For SEO, call these helpers from server-rendered pages whenever the client site framework supports it.

Build

npm run build in this package (or root prepare after npm install).

Publish to npm (org jmp-technologies)

Preferred (CI): after the version in package.json is bumped and merged to master, run GitHub Actions → Publish analytics (workflow_dispatch). Requires repo secret NPM_TOKEN with publish access to @jmp-technologies. Use the workflow’s dry-run input to pack without publishing.

Local:

npm run build
npm publish

Package sets publishConfig.access to public. Local publish requires npm login with publish access to @jmp-technologies. There is no changesets / tag-driven release; version bumps live in package.json on master.

After publish, on client sites:

npm install @jmp-technologies/analytics@latest

create-jmp-client scaffolds pin @>=0.1.46 (batched ingest + JMP_CONTENT_REVALIDATE_SECONDS = 86400 safety-net TTL). Use ≥ 0.1.8 for getJmpSiteProfile / extras. Use ≥ 0.1.10 for email_click tracking and JmpTrackedMailtoLink. Use ≥ 0.1.37 so server content fetches and server page views send Origin from siteUrl / NEXT_PUBLIC_SITE_URL (required for capabilities writes after the matching dashboard deploy). Use ≥ 0.1.38 so contentManifest.routes with wrapper legal or pages reports page URLs to the dashboard Pages tab. Use ≥ 0.1.39 so JMP content fetch uses the jmp-content cache tag (client webhooks revalidate it). Use ≥ 0.1.41 so npm types export mergeJmpRobotsTxt, buildAiCrawlerRobotsTxt, and the Vercel WAF route helper.

Ensure the dashboard is deployed with migrations 020 and 021 and /api/content/site is live before relying on getJmpSiteProfile in production.