Custom events

The collector auto-captures vitals, navigation, errors, and page views. Custom events add your own signal: conversions, clicks, feature usage, A/B variants. One call records a named event with optional value, dimensions, metrics, and tags.

Emit a custom event #

Call amb('event', name, props). The name is a short, stable string you choose. The props object is optional and every field in it is optional.

custom event js

// Emit a custom_action event: conversions, clicks, A/B variants.
amb('event', 'add_to_cart', {
  value: 49.99,                                  // -> metric_value
  unit: 'eur',                                   // -> metric_unit
  dims: { sku: 'WIDGET-1', variant: 'green' },   // -> dimensions
  metrics: { qty: 2 },                           // -> metrics
  tags: ['promo']                                // -> tags
});

The call queues before the loader resolves and replays in order, so you can fire events from anywhere in your code without guarding for readiness.

Field reference #

Each prop maps to a column on the stored event:

Prop	Type	Column	Use it for
`value`	number	`metric_value`	The single headline number: a price, a duration, a score.
`unit`	string	`metric_unit`	The unit of `value`, for example `eur`, `ms`, `count`.
`dims`	object of string	`dimensions`	Categorical attributes to group and filter by. Must be declared first.
`metrics`	object of number	`metrics`	Extra numeric measures beyond `value`, for example a quantity or a count.
`tags`	array of string	`tags`	Free-form labels for ad-hoc slicing.

A conversion example #

For a SaaS checkout, record the completed purchase with its value and the plan dimensions:

checkout.js js

// Track a completed checkout in a SaaS or storefront flow.
amb('event', 'checkout_completed', {
  value: 129.0,
  unit: 'usd',
  dims: { plan: 'pro', coupon: 'SPRING' },
  metrics: { seats: 5 },
  tags: ['conversion']
});

Declare your dimensions #

Custom dimensions must be declared on the app before they are stored. An undeclared key in dims is ignored. Define the schema, including type, whether it is required, and the PII flag, under the app's dimension settings. See Custom dimensions.