API

Public functions and configuration types of @casoon/trackr. The type declarations shipped in the package are the authoritative source.

Client

functioninitsince 0.1

import { init } from "@casoon/trackr/client";

function init(options: TrackrConfig): void;

interface TrackrConfig {
endpoint: string;
debug?: boolean;
}

Sends a pageview and, from 0.2, a pageview after every pushState, replaceState, popstate and hashchange. Call it once per page load.

Parameters

endpoint: string; URL the events are posted to, usually a route on the same site.
debug: boolean; Log every sent event to the console.

functiontracksince 0.1

import { track } from "@casoon/trackr/client";

function track(name: string, props?: Record<string, string | number | boolean>): void;

Sends a custom event for the current path. Before init() it only logs a warning.

Server

functioncreateHandlersince 0.1

import { createHandler } from "@casoon/trackr/server";

function createHandler(config: HandlerConfig): (request: Request) => Promise<Response>;

interface HandlerConfig {
storage: StorageAdapter;
privacy?: PrivacyConfig;
botFilter?: boolean;
}

interface PrivacyConfig {
anonymizeIp?: boolean;     // default true
stripPii?: boolean;        // default true
stripQueryParams?: string[];
}

Accepts POST with a JSON event. Status codes are listed in the Quickstart.

Parameters

storage: StorageAdapter; Receives every accepted event.
privacy: PrivacyConfig; Merged with the defaults; see the Privacy guide.
botFilter: boolean; Drop requests that look like bots. Off unless set.

functioncreatePixelHandlersince 0.2

import { createPixelHandler } from "@casoon/trackr/server/pixel";

function createPixelHandler(config: HandlerConfig): (request: Request) => Promise<Response>;

Records a pageview from the url and ref query parameters and returns a transparent GIF. See Tracking pixel.

@casoon/trackr/server also exports the building blocks the handler uses: isBot(request), anonymizeIp(ip), stripPii(url), sanitizeProps(props), applyPrivacy(event, config) and resolvePrivacyConfig(config).

Storage

functionpostgressince 0.1

postgres(connectionStringOrClient: string | { query(text: string, values?: unknown[]): Promise<{ rows: unknown[] }> }): StorageAdapter

functionapisince 0.1

api(config: { url: string; headers?: Record<string, string>; transform?: (event: TrackrEvent) => unknown }): StorageAdapter

functionwebhooksince 0.2

webhook(config: WebhookConfig): StorageAdapter

interface WebhookConfig {
url: string;
headers?: Record<string, string>;
secret?: string;
transform?: (event: TrackrEvent) => unknown;
retry?: { attempts?: number; baseDelay?: number };
}

functionga4since 0.2

ga4(config: Ga4Config): StorageAdapter

interface Ga4Config {
measurementId: string;
apiSecret: string;
debug?: boolean;               // default false
nonPersonalizedAds?: boolean;  // default true
stripQueryParams?: string[];
}

functionmultisince 0.2

multi(...adapters: StorageAdapter[]): StorageAdapter

functionbatchsince 0.2

batch(adapter: StorageAdapter, options?: BatchOptions): BatchedAdapter

interface BatchOptions {
maxSize?: number;  // default 10
maxWait?: number;  // ms, default 5000
onError?: (error: unknown, events: TrackrEvent[]) => void;
}

interface BatchedAdapter extends StorageAdapter {
flush(): Promise<void>;
readonly pending: number;
}

Behaviour and examples for every adapter: Storage adapters. The full type declarations are in the package (dist/**/*.d.ts) and on npm.

Edit this page on GitHub · Docs for v0.3.0