Tracker

The browser tracker is what captures on your site: it sends pageviews, events, goals and sales to every filled capture slot, behind the gate your consent manager drives. Capture is the guide; this page is its API.

Booting it

A page holds one tracker. Every way to boot it below takes a hold on that same tracker, so rendering two of them together never counts twice: whichever boots first creates it, and its options stick.

Server render

import { AnalyticsScripts, getTrackerConfig } from '@10x-media/analytics/site'
import config from '@payload-config'
import { headers } from 'next/headers'
import { getPayload } from 'payload'

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const payload = await getPayload({ config })
  const tracker = await getTrackerConfig(payload, { headers: await headers() })
  return (
    <html lang="en">
      <body>
        {children}
        <AnalyticsScripts config={tracker} />
      </body>
    </html>
  )
}

getTrackerConfig(payload, { headers?, draft? }) resolves the request's TrackerConfig. Pass the incoming headers so a scoped install resolves the request's scope; draft says the page renders in Next's draft mode, and left out it is read from Next's draft mode cookie among the headers (Next.js).

<AnalyticsScripts> renders each ungated slot's vendor snippet and boots the tracker:

It takes no loadScript: a function cannot cross from a server component.

React

<AnalyticsProvider> takes the same props as <AnalyticsScripts>, plus loadScript and children. Render it from a client component of your own to boot the tracker from React, or to load the vendor scripts through your framework's own loader.

useAnalytics() answers an AnalyticsApi from any client component, with or without a provider above it, as long as a tracker was booted on the page:

The tracker is resolved per call, not per render, so a component that renders before the boot effect runs still works. A call to track, trackGoal, purchase, refund or setExcluded that finds neither a provider nor a booted tracker throws; setGate never does.

initTracker

import { initTracker } from '@10x-media/analytics/tracker'

export const tracker = await initTracker()

initTracker({ endpoint?, ...TrackerOptions }) fetches the config from endpoint, DEFAULT_TRACKER_ENDPOINT (/api/_x/config) by default: pass your own when the app moved Payload's routes.api or the plugin's routes.base, or serves under a Next basePath. A failed fetch or a non-ok answer resolves to a tracker whose calls do nothing, so a missing config never breaks the page that awaited it. Its destroy() gives this call's hold back, and the tracker ends once nothing holds it.

createTracker(config, options?) builds a tracker from a TrackerConfig you already have. It is a tracker of its own rather than the page's shared one, so useAnalytics does not reach it; prefer the three above.

Tracker options

TrackerOptions, taken by initTracker, createTracker and the props above:

The tracker

Server code records through other functions of the same names, from @10x-media/analytics: trackServerEvent, purchase and refund.

Types

The config

TrackerConfig is what the server resolves for one request and the tracker boots from. It carries only what a browser may see:

EXCLUSION_STORAGE_KEY (analytics:exclude) and DEFAULT_EXCLUSION_PARAM (analytics_exclude) are exported beside it.

Attributes

The tracker reads these attributes on click, and on a form that carries them on its submit alone, and @10x-media/analytics/attributes exports their names and helpers that spread them into your markup (Attach goals to your own components):

The events the tracker sends by itself are named OUTBOUND_EVENT (outbound_link), DOWNLOAD_EVENT (file_download), SCROLL_EVENT (scroll_depth) and ITEM_CLICK_EVENT (item_click).

What the tracker posts to the native engine, field by field, is on Capture; what it keeps in the browser is on Privacy.