Smartizy
Get started
Reference

SDK API

The complete reference for the browser collector's command interface. Every interaction goes through one global function, amb(), called with a command name and its arguments.

The amb() global #

The install snippet defines window.amb. You call it as amb(command, ...args). The supported commands are init, setUser, setRoute, event, and consent. The automatic collectors (page views, navigation timing, Core Web Vitals, resource timing, and unhandled errors) need no calls; the commands here are for the data only your app knows.

The call queue #

The first script in the install snippet is a tiny inline stub that defines amb() synchronously, before the collector bundle is fetched. Any call you make before the loader resolves is pushed onto a queue; when the bundle loads, it drains the queue and replays the calls in order. This means you never have to wait for an onload or guard against a race. Call amb() from anywhere, as early as you like.

calls before load are queued js 
// The inline stub defines amb() synchronously, so these are safe
// even though the collector bundle has not loaded yet. They queue
// and replay in order once the loader resolves.
amb('init', { appId: 'storefront', environment: 'production', endpoint: '…', defaultConsent: 'granted' });
amb('setUser', 'user-123');
amb('event', 'app_booted');

init #

amb('init', options) configures the collector. Call it once. The loader reads its configuration only from this object, never from data-* attributes.

Option Type What it does
appId string, required The app slug. Every event is attributed to it (rum.events.app_id). The immutable ID you chose when you created the app.
environment production | staging | development | preview The deployment tier. Keeps data separated and selects the per-environment ingest policy.
endpoint string, required The beacon URL, your ingest receiver's /v1/events. The collector derives the GET /v1/config URL from it.
release string, optional A build, commit, or version tag. Stored on rum.events.release to attribute regressions to a deploy.
token string, optional An ingest token secret. Required when the app enforces authentication. From the Ingest tokens tab.
defaultConsent granted | denied | pending The fallback consent state before any explicit decision. granted collects immediately; pending buffers; denied holds everything back.
amb('init', options) js 
amb('init', {
  appId: 'storefront',                              // the app slug
  environment: 'production',                        // production | staging | development | preview
  endpoint: 'https://rum-ingest.example.com/v1/events',
  release: '2026.05.0',                            // optional build / commit tag
  token: 'rum_live_…',                            // optional ingest token secret
  defaultConsent: 'granted'                         // granted | denied | pending
});

setUser #

amb('setUser', id) ties the current session to a known user. The id is stored on rum.events.user_id for every subsequent event in the session. Call it once a user signs in. Pass an empty string on logout to anonymise the session again.

amb('setUser', id) js 
// Identify the signed-in user. Stored on rum.events.user_id.
amb('setUser', 'user-123');

// Pass an empty string on logout to anonymise the session again.
amb('setUser', '');

setRoute #

amb('setRoute', path) tells the collector the current logical route, stored on rum.events.route_name. In a single-page app the URL alone is noisy (ids, query strings), so call this from your router on each navigation to get clean, groupable route names in the dashboards.

amb('setRoute', path) js 
// Call from your SPA router on every route change so events
// are tagged with the logical route, not just the raw URL.
amb('setRoute', '/checkout/payment');

See Track SPA routes for router-specific wiring.

event #

amb('event', name, options?) emits a custom action: a conversion, a click, an A/B exposure, anything your app wants to measure. The name is stored on event_name; the optional options object maps onto typed columns.

Field Type Maps to
value number metric_value. The event's primary numeric value (a price, a count, a duration).
unit string metric_unit. The unit of value, e.g. eur, ms, count.
dims object of string dimensions (a string map). Categorical attributes you filter and group by.
metrics object of number metrics (a number map). Extra numeric measures beyond value.
tags array of string tags (a string array). Flat labels for the event.
amb('event', name, options) js 
amb('event', 'add_to_cart', {
  value: 49.99,                                  // -> metric_value
  unit: 'eur',                                   // -> metric_unit
  dims: { sku: 'WIDGET-1', variant: 'green' },    // -> dimensions (Map<string,string>)
  metrics: { qty: 2 },                           // -> metrics (Map<string,number>)
  tags: ['promo']                                // -> tags (Array<string>)
});

// The name alone is enough; the options object is optional.
amb('event', 'newsletter_signup');

amb('consent', state) relays a runtime consent decision, overriding the defaultConsent set at init. granted starts or resumes collection and flushes any buffered events; denied stops collection; pending returns to buffering.

amb('consent', state) js 
amb('consent', 'granted');   // start or resume collection, flush the buffer
amb('consent', 'denied');    // stop collection
amb('consent', 'pending');   // return to buffering until a choice

Wire it into your cookie banner. The full behavior, including how the pending buffer flushes and how consent-platform signals are picked up, is on Consent & privacy and Privacy & compliance.