SDK reference
Everything @pageflock/analytics exports: <Analytics />, inject(), track() and their options.
Entry points
| Import | Exports |
|---|---|
@pageflock/analytics | inject, track, and the types AnalyticsOptions, AnalyticsEvent, Props |
@pageflock/analytics/react | Analytics, track, AnalyticsProps |
@pageflock/analytics/next | Same as react, as a client component for the App Router |
@pageflock/analytics/vue | Analytics, 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
| Option | Type | Default | What it does |
|---|---|---|---|
site | string | required | The site ID from the Pageflock dashboard. |
endpoint | string | https://e.pageflock.com/api/e | The collect endpoint. Optional: only set it when you self-host. |
autoEvents | boolean | false | Also track outbound link clicks, file downloads and 404 pages, like s.auto.js. |
hashRouting | boolean | false | Count #hash changes as page views, for hash-routed apps. |
beforeSend | (event: AnalyticsEvent) => AnalyticsEvent | null | none | Change an event before it is sent, or return null to drop it. |
debug | boolean | false | Log 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 });| Parameter | Type | |
|---|---|---|
name | string | The event's name, as it shows in the dashboard. |
props | Record<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.