@jmp-technologies/analytics

v0.1.34

Published

2 days ago

JMP Analytics tracking plus blog, FAQ, trust content, and site contact profile for client websites

0High
0Medium
0Low

1237jwells

jmp analytics tracking jmp-analytics

`@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)

Deploy JMP Analytics (jmp-dashboard) to a stable HTTPS URL.
Create a website row (domain + tracking_key) and assign it to the client user.
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).
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)

Install peers: react, react-dom, next (already present in a Next app).
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).
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.

Astro (≥ 0.1.20)

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

jmp.config.ts — defineJmpSite({ ... }) from @jmp-technologies/analytics
astro.config.mjs — integrations: [jmpAnalytics()] from @jmp-technologies/analytics/astro/integration
src/middleware.ts — export { onRequest } from "@jmp-technologies/analytics/astro/middleware"
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. The policy uses robots.txt Disallow rules for known AI crawler user agents; crawlers that ignore robots.txt or use undisclosed names may still access public pages.

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

Admin saves ga_measurement_id in jmp-dashboard (Content → Contact).
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`)

From this directory:

npm run build
npm publish

Package sets publishConfig.access to public. Requires npm login with publish access to @jmp-technologies.

After publish, on client sites:

npm install @jmp-technologies/analytics@latest

Use ≥ 0.1.8 for getJmpSiteProfile / extras. Use ≥ 0.1.10 for email_click tracking and JmpTrackedMailtoLink.

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