@jmp-technologies/analytics

v0.1.7

Published

12 days ago

Browser client for JMP Analytics event ingestion

0High
0Medium
0Low

1237jwells

jmp analytics tracking jmp-analytics

`@jmp-technologies/analytics`

Browser client for POST {baseUrl}/api/events plus published blog/FAQ content 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

API, CORS, examples: Tracking integration

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/client-onboarding.md and docs/tracking-integration.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).
In app/layout.tsx (or the root layout that wraps all pages), add one client line:

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

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

That enables automatic page_view on first load and on client-side navigations (includes query string). No jmp-analytics-client.ts, no useEffect + usePathname boilerplate.

Optional: track phone clicks without custom handlers — use JmpTrackedTelLink from the same module:

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

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

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

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() in one object.

Configured? isJmpBrowserAnalyticsEnvConfigured() and isJmpServerContentEnvConfigured().

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>
  )
}

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.

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, useJmpAnalytics

React (@jmp-technologies/analytics/react)

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

Content

getJmpBlogPosts(config)
getJmpBlogPost(config, slug)
getJmpFaqs(config)
getJmpRobotsTxt(config)
createJmpContentClient(config)

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

npm publish from this directory after npm run build (package sets publishConfig.access to public).

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme