Widget

JavaScript API

Once the script is on the page it exposes a global window.clickbase you can call from your own code — to send custom events, report revenue, identify visitors, drive pageviews manually, report errors, and control session replay.

The queue: safe to call before load

The snippet installs a tiny stub synchronously, then loads the real widget asynchronously. The stub queues any call you make and the widget drains the queue once it finishes loading, so you never have to wait — call clickbase.* as soon as the snippet tag is in the page.

Two methods are synchronous getters that must return a value immediately, so before the widget has loaded they return a safe default:

getVisitorId() returns null until loaded.
getSessionId() returns null until loaded.
isSessionReplayActive() returns false until loaded.

Every other method is queued and runs in order once the widget is ready.

Methods

`event(name, options?)`

Record a custom event.

clickbase.event('signup', { props: { plan: 'pro' } });

Argument	Type	Description
`name`	`string`	The event name.
`options`	`EventOptions`	Optional properties, callback, url, revenue.

Reserved names are refused (see Reserved names).

`sale(name, revenue, options?)`

Report a one-off, client-reported sale. Revenue is a required positional argument.

clickbase.sale('purchase', { amount: 4990, currency: 'USD' });

Argument	Type	Description
`name`	`string`	The goal name to attribute to.
`revenue`	`RevenuePayload`	Required. Integer minor units + ISO 4217 currency.
`options`	`RevenueEventOptions`	Optional `props` / `callback`.

`subscription(name, revenue, options?)`

Report a recurring-flavored client-reported revenue event. Same mechanics as sale(); the name is for readability — it cannot represent a real subscription lifecycle (only Stripe can). Revenue is required.

clickbase.subscription('pro-plan', { amount: 2900, currency: 'USD' });

Reported revenue from sale() / subscription() / event({ revenue }) attaches to goals for attribution — it is never treated as verified money and never reaches the Revenue page or MRR. See Track revenue and Revenue.

`identify(payload, callback?)`

Associate the current visitor with a known identity (a "site user"). See People.

clickbase.identify({
  identifier: 'user_123',
  name: 'Ada Lovelace',
  avatar: 'https://example.com/ada.png',
  custom: { plan: 'pro' },
});

Argument	Type	Description
`payload`	`IdentifyPayload`	The visitor's identity.
`callback`	`DeliveryCallback`	Optional delivery-result callback.

`pageview(options?)`

Record a pageview manually. Useful with data-manual="true", which turns off all automatic pageviews (see Pageviews & SPAs).

clickbase.pageview();
clickbase.pageview({ url: '/virtual/checkout-step-2' });

options is an EventOptions; the url field overrides the recorded path.

`error(error, context?)`

Report an error manually. No-op unless error tracking is enabled for the site (track_errors).

try {
  doRisky();
} catch (e) {
  clickbase.error(e, { where: 'checkout' });
}

Argument	Type	Description
`error`	`unknown`	An `Error` instance, string, or any value.
`context`	`PropertyMap`	Optional extra properties.

Unhandled errors and promise rejections are captured automatically when track_errors is on — see Error tracking.

`startSessionReplay()` / `stopSessionReplay()`

Manually start or stop recording the current session for replay.

clickbase.startSessionReplay();
clickbase.stopSessionReplay();

startSessionReplay() is a no-op unless session replay is enabled for the site (track_session_replay) and the current session is within the configured sample rate.

`isSessionReplayActive()`

Returns boolean — whether replay is currently recording. Synchronous; returns false before the widget has loaded.

if (clickbase.isSessionReplayActive()) { /* ... */ }

`getVisitorId()`

Returns string | null — the current visitor id, or null before the widget has loaded and in cookieless mode where no id is stored. Synchronous.

const visitorId = window.clickbase.getVisitorId();

The main use is bridging a server-side Stripe checkout back to the visit that earned it — see Track revenue → Attribute a Stripe checkout.

`getSessionId()`

Returns string | null — the current analytics session id (_cb_sid), or null before the widget has loaded and in cookieless mode. Synchronous. Sliding inactivity window matches the product-wide session duration (config('clickbase.session_duration_minutes'), default 30 minutes).

const sessionId = window.clickbase.getSessionId();

Optional companion to getVisitorId() on Stripe Checkout / PaymentIntent metadata as clickbase_session_id. Visitor remains the primary attribution join key.

Types

`PropertyMap`

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

`RevenuePayload`

Integer minor units (cents), not dollars — $49.90 is 4990.

interface RevenuePayload {
  amount: number;   // integer minor units
  currency: string; // ISO 4217, e.g. "USD"
}

`EventOptions`

interface EventOptions {
  props?: PropertyMap;        // custom properties
  callback?: DeliveryCallback; // delivery result
  url?: string;               // override the recorded path (pageview)
  revenue?: RevenuePayload;   // attach reported revenue to a goal
}

`RevenueEventOptions`

Options for sale() / subscription() — revenue is a required positional argument on those methods, so it is not part of these options.

interface RevenueEventOptions {
  props?: PropertyMap;
  callback?: DeliveryCallback;
}

`IdentifyPayload`

interface IdentifyPayload {
  identifier: string;   // your stable id for the visitor
  name?: string;
  avatar?: string;
  custom?: PropertyMap;
}

`DeliveryCallback`

Called with the outcome of the network delivery.

type DeliveryCallback = (result: DeliveryResult) => void;

interface DeliveryResult {
  status?: number | 'ignored'; // HTTP status, or 'ignored' when the hit was filtered
  error?: unknown;
}

Reserved names

event(), sale(), and subscription() all refuse the event names Clickbase writes only from trusted server sources, so a browser can never forge verified revenue. A refused call sends no beacon, logs a console.warn, and fires the delivery callback with status: 'ignored'. The reserved names (case-insensitive) are:

payment, free_trial, trial_started, trial_converted, subscription_started, subscription_renewed, subscription_upgraded, subscription_downgraded, subscription_cancel_scheduled, subscription_reactivated, subscription_ended.

See Track revenue for why these are locked, and Goals for the matching server-side rule.

JavaScript API

The queue: safe to call before load

Methods

event(name, options?)

sale(name, revenue, options?)

subscription(name, revenue, options?)

identify(payload, callback?)

pageview(options?)

error(error, context?)

startSessionReplay() / stopSessionReplay()

isSessionReplayActive()

getVisitorId()

getSessionId()