Skip to Content
Pageflock

SDK reference

Everything @pageflock/analytics exports: <Analytics />, inject(), track() and their options.

Entry points

ImportExports
@pageflock/analyticsinject, track, and the types AnalyticsOptions, AnalyticsEvent, Props
@pageflock/analytics/reactAnalytics, track, AnalyticsProps
@pageflock/analytics/nextSame as react, as a client component for the App Router
@pageflock/analytics/vueAnalytics, track

Every entry bundles one copy of the tracker core, so mixing them (say <Analytics /> in the layout and track() from the root import elsewhere) still shares one queue and one configuration.

<Analytics />

Starts tracking when it mounts. Render it once, near the root. It renders nothing.

<Analytics site="SITE_ID" autoEvents />

In Vue, the props are kebab-cased: <Analytics site="SITE_ID" auto-events />.

inject(options)

The same, without a framework. Call it once, in the browser; on the server it does nothing.

import { inject } from "@pageflock/analytics";

inject({ site: "SITE_ID", hashRouting: true });

Options

OptionTypeDefaultWhat it does
sitestringrequiredThe site ID from the Pageflock dashboard.
endpointstringhttps://e.pageflock.com/api/eThe collect endpoint. Optional: only set it when you self-host.
autoEventsbooleanfalseAlso track outbound link clicks, file downloads and 404 pages, like s.auto.js.
hashRoutingbooleanfalseCount #hash changes as page views, for hash-routed apps.
beforeSend(event: AnalyticsEvent) => AnalyticsEvent | nullnoneChange an event before it is sent, or return null to drop it.
debugbooleanfalseLog every event to the console, including on localhost.

site, endpoint, autoEvents and hashRouting are read when tracking starts. beforeSend and debug can change on later renders.

track(name, props?)

import { track } from "@pageflock/analytics";

track("Checkout started", { items: 3, total: 49.5, coupon: false });
ParameterType
namestringThe event's name, as it shows in the dashboard.
propsRecord<string, string | number | boolean>Optional properties.

track() is safe to call anywhere: before tracking starts (events are queued), during server rendering (it does nothing), and when Pageflock was installed with the script tag instead (it forwards to window.pageflock).

Types

type Props = Record<string, string | number | boolean>;

/** What beforeSend receives. name is "pageview" for page views. */
interface AnalyticsEvent {
  name: string;
  url: string;
  props?: Props;
}

Time on page and scroll depth are sent as an engagement event when the visitor leaves the page, and pass through beforeSend too.

When nothing is sent

The SDK sends nothing on localhost, from file: pages, in automated browsers (navigator.webdriver), or while a page is prerendered (it waits until the page is shown). Set debug to see in the console what would have been sent.

On this page