Quick Start

The minimum setup is one load() call plus the first page view. The Time on Page plugin auto-registers with sensible defaults — you don’t wire anything by hand.

analytics.ts

import { AnalyticsBrowser } from "@adpharm/silo-analytics";

// The minimum setup — one call, the Time on Page plugin auto-registers with
// sensible defaults (Silo CDN, event gateway, writeKey-namespaced storage).
export const analytics = AnalyticsBrowser.load({ writeKey: "your-write-key" });

// The first page view waits for ready() (see "The initial page view" below).
analytics.ready(() => analytics.page());

Pass `env` on a shared apex domain

If your environments share an apex domain (e.g. app.example.com and staging.example.com), pass env. Without it, every env reads the same cookie key and you’ll see anonymousIds bleed across deployments. Single-env or different-apex setups don’t need it. See Configuration.

Defaults applied internally

With just writeKey (+ optional env), the library fills in:

• cdnURL → https://cdn.silo.adpharm.digital
• timeOnPage.apiHost → https://event-gateway.silo.adpharm.digital/v1/t
• timeOnPage.writeKey → inherits from the top-level writeKey
• Storage keys → ajs_user_id_${writeKey}_${env} and ajs_user_traits_${writeKey}_${env} (no suffix if env is omitted)

Customizing

Pass anything you want to override. timeOnPage is Partial<> — only the fields you set change; the rest keep their defaults.

analytics.ts

import { AnalyticsBrowser } from "@adpharm/silo-analytics";

// Override anything you want to customize. `timeOnPage` is `Partial<>` — only
// the fields you set are overridden; apiHost + writeKey still default.
export const analytics = AnalyticsBrowser.load({
  writeKey: "your-write-key",
  env: "production",
  cdnURL: "https://your-cdn.example.com", // override the Silo CDN default
  timeOnPage: {
    minSeconds: 10, // partial override; apiHost + writeKey still default
    maxSeconds: 1800, // cap events at 30m instead of the 900s default
    idleSeconds: 60, // pause engagement after 60s of no input (0 disables)
    eventName: "Engagement", // beacon event name (default "Page Time Spent")
    heartbeatSchedule: [60, 120, 240], // custom backoff (false disables)
    scrollTracking: false, // opt out of scroll-depth fields
  },
  user: { cookie: { key: "custom_cookie_key" } }, // full override
});

See Configuration for every option, its type, and default.

SPA route changes

In a single-page app, fire analytics.page() on every client-side route change (the standard Segment integration pattern). The plugin listens for those page events — plus browser back/forward via popstate — to roll the page_view_id and reset the engagement window per view. Without it, a whole SPA session looks like one long page-view.

The initial page view

AnalyticsBrowser.load() returns immediately and buffers any call you make before it finishes booting. That buffering is normally invisible — but on a cold load (first visit, nothing cached) where the writeKey has device-mode destinations configured, AJS can take a second or more to finish wiring its delivery pipeline, and a page view buffered in that window may not be delivered. The symptom is unmistakable: the very first page view of a fresh visit never reaches the gateway, yet a refresh (everything now cached) sends it fine.

Dispatch the initial page view once analytics is ready, so it runs against the fully-wired pipeline instead of the pre-init buffer:

// Initial load: wait for the pipeline before the first page view.
// Subsequent SPA navigations: ready() resolves immediately — no penalty.
analytics.ready(() => analytics.page());

Tip

This only matters for the first page view of a session. Once ready() has resolved, analytics.page() dispatches directly and you can call it normally on every route change (above).

Checking it works

Open the source’s debugger in the Silo console, or check your browser’s Network tab if you don’t have console access. See Checking Your Events for what to expect, and why an event might not show up yet.