Custom events reference

The tracking script exposes two methods for recording events:

rbly.convert() records actions you want to measure as conversions — purchases, signups, form submissions. These appear in Event Breakdown and Path Analysis reports and can include revenue data.

rbly.track() records custom behavioral events that aren't conversions — clicks, interactions, engagement signals. These are tracked separately from conversion data.

rbly.convert()

rbly.convert() is the dedicated method for recording conversion events. Use it instead of the deprecated rbly.track('conversion', ...).

rbly.convert(label, value?, currency?, properties?)

Returns a Promise that resolves to a response object.

Parameter	Type	Required	Description
`label`	string	Yes	A name for the conversion, e.g., `"purchase"`. Categorizes the conversion in Event Breakdown and Path Analysis reports.
`value`	number \| null	No	The monetary value of the conversion.
`currency`	string \| null	No	An ISO 4217 currency code, for example, `"USD"` or `"EUR"`. Required when `value` is provided.
`properties`	object	No	A flat JSON object of additional metadata. Merged with stored UTM parameters at send time.

Events sent via rbly.convert() go to /v1/track/conversion.

rbly.track()

rbly.track() records custom behavioral events that are not conversions — clicks, interactions, engagement signals. Use it for actions you want to capture but that shouldn't appear in conversion reports.

rbly.track(event, properties?)

Returns a Promise that resolves to a response object.

Parameter	Type	Required	Description
`event`	string	Yes	A name for the event, e.g., `"newsletter_click"`. Must be a non-empty string and cannot use the reserved `rb:` prefix.
`properties`	object	No	A flat JSON object of additional metadata. Merged with stored UTM parameters at send time.

Events sent via rbly.track() go to /v1/track and are tracked separately from conversion data.

Response

rbly.convert()

`success`	`error`	When it occurs
`true`	—	The event was recorded.
`false`	`"no_click_id"`	`localStorage` is blocked, or the visitor did not arrive via a Rebrandly branded link.
`false`	`"duplicate_event"`	The event was suppressed by deduplication. The response also includes `deduplicated: true`, `reason`, `key`, `lastTracked`, and `timeSinceLastTracked`.
`false`	`"not_initialized"`	`rbly.init()` was not called. This only applies to the manual initialization path.
`false`	`"invalid_label"`	The `label` argument is missing or not a non-empty string.
`false`	`"invalid_properties"`	The `properties` argument is not an object.
`false`	`"invalid_currency"`	A `value` was provided without a valid 3-letter ISO currency code.
`false`	`"tracking_error"`	A network error or unexpected failure occurred.

rbly.track()

`success`	`error`	When it occurs
`true`	—	The event was recorded.
`false`	`"no_click_id"`	`localStorage` is blocked, or the visitor did not arrive via a Rebrandly branded link.
`false`	`"duplicate_event"`	The event was suppressed by deduplication. The response also includes `deduplicated: true`, `reason`, `key`, `lastTracked`, and `timeSinceLastTracked`.
`false`	`"not_initialized"`	`rbly.init()` was not called. This only applies to the manual initialization path.
`false`	`"invalid_event"`	The `event` argument is missing or not a non-empty string.
`false`	`"invalid_properties"`	The `properties` argument is not an object.
`false`	`"reserved_event_name"`	The `event` argument uses the reserved `rb:` prefix.
`false`	`"tracking_error"`	A network error or unexpected failure occurred.

All failure responses include a message field with a human-readable description.

Event naming

The tracking script validates that label (rbly.convert()) and event (rbly.track()) are non-empty strings. Event names passed to rbly.track() starting with rb: are reserved and blocked — it returns { success: false, error: 'reserved_event_name' } if this prefix is used. Use a consistent naming convention across both methods — for example snake_case — so events are easy to filter and compare in the analytics dashboard.

📘
Deprecated event names
rbly.track('conversion', ...) is deprecated — use rbly.convert() instead. rbly.track('page_view', ...) is deprecated — page view events are now fired automatically by the tracking script on every route change and do not require a manual call. Both deprecated patterns still function but log a console.warn.

UTM parameters

The SDK automatically captures and stores the five standard UTM parameters — utm_source, utm_medium, utm_campaign, utm_term, and utm_content — plus any custom parameter names configured via data-custom-utm-params. On every rbly.convert() and rbly.track() call, these stored values are merged into properties before the event is sent. If a key in your properties object collides with a stored UTM key, your value takes precedence.

Examples

Simple conversion

rbly.convert('signup');

Purchase with revenue

rbly.convert('purchase', 99.99, 'USD', { product_id: 'prod_123', quantity: 2 });

Non-monetary conversion with metadata

rbly.convert('lead', null, null, { source: 'newsletter', plan: 'professional' });

Custom behavioral event

rbly.track('newsletter_click', {
  source: 'homepage',
  placement: 'footer_cta'
});

Handling the response

const result = await rbly.convert('purchase', 49.00, 'USD');
if (!result.success) {
  console.warn('Conversion not recorded:', result.error);
}

Deduplication

The SDK suppresses duplicate events fired within a configurable time window (default 10 seconds). A suppressed event resolves with success: false and error: "duplicate_event". Deduplication is controlled by the data-dedup-enabled and data-dedup-time-window attributes on the script tag — see Script configuration for details.

Verifying events

Each rbly.convert() and rbly.track() call writes a [Rebrandly SDK]-prefixed line to the browser console confirming whether the event was recorded or suppressed. Recorded conversion events appear in the Analytics dashboard within a few minutes.

There is no event inspector or test mode. See the testing caveat in the quickstart for guidance on keeping test events out of production data.

Next steps

Script configuration — Configure deduplication, custom UTM params, and SPA behavior via data-* attributes
API reference — Query conversion data and pull it into your own dashboards using the reporting API