Skip to main content
sdk

Track

active
Audience: developerUpdated 2026-10-05

The Track call records an action a customer performed — an event with a name and a set of properties describing it. Together with Identify, it is the whole tracking contract, and the same shape applies whether the call comes from the Web SDK, the Native SDK, or a direct Tracking REST request.

Example​

A minimal Track call needs only an event name and an identity:

{
"type": "track",
"event": "product_viewed",
"userId": "user_8421",
"properties": {
"product_id": "507f1f77bcf86cd799439011"
}
}

The matching Web SDK call:

Binoban.track("product_viewed", {
product_id: "507f1f77bcf86cd799439011",
});

A fuller payload, showing the fields you'll see on most real events:

{
"type": "track",
"event": "order_completed",
"userId": "user_8421",
"anonymousId": "b7e1c9f0-6b2a-4e9a-9c3d-2f6a1d9e4b71",
"timestamp": "2026-07-26T14:32:00.000Z",
"properties": {
"order_id": "50314b8e9bcf000000000000",
"revenue": 84.5,
"currency": "USD"
},
"context": {
"page": {
"url": "https://shop.example.com/checkout/confirmation",
"path": "/checkout/confirmation"
},
"traits": {
"email": "customer@example.com"
}
}
}
Binoban.track("order_completed", {
order_id: "50314b8e9bcf000000000000",
revenue: 84.5,
currency: "USD",
});

Identities​

Every Track call carries at least one identifier from your workspace's identity strategy: userId, anonymousId, a device id in context.device, or (when enabled) phone, email or a custom identifier trait in context.traits:

FieldRequired?Max lengthAllowed characters
userIdOptional; one identifier required64a–z A–Z 0–9 _ - . @ :
anonymousIdOptional; one identifier required64a–z A–Z 0–9 _ - . @ :

Send both when you have them — an anonymous visitor who later signs in should carry the same anonymousId it always had, plus the new userId. A call with no identifier is rejected with error.sdk.missing.identifier. A value using disallowed characters rejects it with error.sdk.user.id.pattern / error.sdk.anonymous.id.pattern; a value over 64 characters also rejects the call, but the exact code that response carries isn't confirmed — the length check runs through generic validation, not the pattern check that's wired to those codes. See Limits & validation for the full rejection table.

This is a wire-level rule, not the whole identity model — read Identity strategy for how Binoban decides two events belong to the same person, and when to call identify instead of just carrying an id on track.

Event​

event is a required string naming what happened. Name it in human-readable, past tense — product_viewed, order_completed — not a generic label like Event 12 or a present-tense verb. The event name is a contract: audiences, Engage journeys, and Insights reports all key off the exact string you send, so an inconsistent name (orderCompleted on one page, order_completed on another) silently splits one event into two.

Binoban maintains a catalog of standard ecommerce event names — use one of those where your action fits, so your data lines up with the built-in reports and journeys without extra mapping. See the Ecommerce event catalogue.

The name itself is validated like any other name in the system:

RuleValue
RequiredYes
Max length64 characters
Allowed charactersa–z A–Z 0–9 _ - .

A name using disallowed characters (spaces, for example) rejects the call with error.sdk.event.name.pattern. A missing or over-length name also rejects the call — event is @Required, so an empty string doesn't satisfy it — but the exact code isn't confirmed for either case: only the character-pattern check is wired to error.sdk.event.name.pattern; the required/length checks fall back to generic validation.

The bb_ prefix is reserved​

bb_ is Binoban's system-event namespace. Binoban's own events live there — bb_identify, bb_merge, bb_app_opened, and the bb_notification_* family the SDKs emit for push — and downstream tooling keys off the prefix to tell a Binoban event from one of yours.

Never send a track event whose name starts with bb_. It is not a name you can claim, and an event you send under it won't behave like your own event even where it is accepted. Name your events for what happened in your product (order_completed, subscription_renewed) and leave the prefix to Binoban.

Properties​

properties is an optional, free-form dictionary describing the event — price, quantity, product_id, or anything else specific to what you're tracking. Send properties whenever you have them; an event with no properties still records that the action happened, but the properties are what make it useful downstream (segmenting an audience on revenue, for instance).

Property names (keys) follow the same rule as event names:

RuleValue
Max length64 characters
Allowed charactersa–z A–Z 0–9 _ - .

A property name over the limit or with disallowed characters rejects the whole call (error.sdk.attribute.name.length / error.sdk.attribute.name.pattern). Property values have their own type-based ranges — see Limits & validation — and a value that breaks its range is silently dropped rather than rejecting the call.

Reserved property names​

A small set of names belongs to Binoban's own event attributes. A property sent under one of them is dropped from the call:

ReservedWhy
Any name starting with cx_The prefix belongs to the flattened context block — cx_locale, cx_pageUrl, and so on.
eventNameThe event's own name, taken from the event field of the call.
eventTimeThe event's timestamp, taken from timestamp.
receiveTimeThe time Binoban received the call.

Only the reserved property is removed — the rest of the call is processed as usual, so you keep every other property in the payload. Binoban logs the drop rather than rejecting the whole event, because a reserved name is nearly always a client echoing a field it already sent elsewhere.

Nothing else is reserved. Every other property name is validated the same way regardless of what it's called — there's no backend concept of a property Binoban treats specially just because it's called revenue or currency. That includes the plain context names (locale, appName, pageUrl, …): the context block is stored under the cx_ prefix, so those names are yours to use as ordinary properties.

Beyond that list, what you'll find is per-event convention: the Ecommerce event catalogue defines which property names carry meaning on each standard event (for example, price and currency on product_viewed). Use those exact names on standard events so downstream tooling can rely on them — but that's a documentation convention scoped to those events, not a platform-wide reserved list enforced at ingestion.

Context​

context is an optional object carrying environment and identity-adjacent information about where the event came from. These are the fields the tracker actually accepts.

You send context nested, exactly as shown in the examples above — but each field is also stored as a queryable attribute on the event under a flat name in the reserved cx_ namespace. That stored name is what you pick in the segment builder, in Insights, and in exports, and it's why cx_-prefixed property names are reserved. The Stored as column below gives it for every field:

FieldTypeStored asDescription
context.activeBooleancx_activeWhether the underlying session/device is currently active.
context.app.nameStringcx_appNameApplication name.
context.app.packageNameStringcx_appPackageNameApplication package/bundle identifier.
context.app.versionStringcx_appVersionApplication version.
context.app.buildStringcx_appBuildApplication build number.
context.campaign.nameStringcx_campaignNameMarketing campaign name.
context.campaign.sourceStringcx_campaignSourceCampaign source.
context.campaign.mediumStringcx_campaignMediumCampaign medium.
context.campaign.termStringcx_campaignTermCampaign term.
context.campaign.contentStringcx_campaignContentCampaign content.
context.device.idStringcx_deviceIdDevice identifier.
context.device.sdkStringcx_deviceSdkPush delivery platform for this device: WEB, ANDROID, or IOS.
context.device.advertisingIdStringcx_deviceAdvertisingIdAdvertising identifier.
context.device.tokenStringcx_deviceTokenPush token.
context.device.manufacturerStringcx_deviceManufacturerDevice manufacturer.
context.device.modelStringcx_deviceModelDevice model.
context.device.nameStringcx_deviceNameDevice name.
context.device.typeStringcx_deviceTypeDevice type.
context.device.versionStringcx_deviceVersionDevice OS/hardware version.
context.device.webViewIdStringcx_deviceWebViewIdIdentifier for a webview instance, used to align Native and Web SDK identity in a webview — see Webview behavior.
context.ipStringcx_ipIP address the event was sent from.
context.library.nameStringcx_libraryNameName of the SDK that sent the event.
context.library.versionStringcx_libraryVersionVersion of the SDK that sent the event.
context.localeStringcx_localeLocale, e.g. en-US.
context.network.bluetoothStringcx_networkBluetoothBluetooth connectivity state.
context.network.carrierStringcx_networkCarrierMobile carrier.
context.network.cellularStringcx_networkCellularCellular connectivity state.
context.network.wifiStringcx_networkWifiWi-Fi connectivity state.
context.os.nameStringcx_osNameOperating system name.
context.os.versionStringcx_osVersionOperating system version.
context.page.nameStringcx_pageNamePage name.
context.page.pathStringcx_pagePathPage path.
context.page.referrerStringcx_pageReferrerPage referrer.
context.page.searchStringcx_pageSearchPage query string.
context.page.titleStringcx_pageTitlePage title.
context.page.urlStringcx_pageUrlPage URL.
context.page.keywordsStringcx_pageKeywordsPage keywords.
context.referrer.typeStringcx_referrerTypeReferrer type.
context.referrer.nameStringcx_referrerNameReferrer name.
context.referrer.urlStringcx_referrerUrlReferrer URL.
context.referrer.linkStringcx_referrerLinkReferrer link.
context.userAgentStringcx_userAgentBrowser/device user agent string.
context.timezoneStringcx_timezoneTimezone.
context.traitsObject—Free-form dictionary — see below.

context.traits deserves special attention. It's how a Track call carries traits collected on an earlier Identify call along with the event, and — on any non-Identify call — it's also the field Binoban's identity resolution reads for phone, email, or custom-trait matching, if your workspace has one of those enabled. See Identity strategy for how that matching works and how to turn it on.

Some device identifiers are intentionally omitted

context.device carries two more fields tied to specific ad-network integrations. They aren't documented here because they haven't been confirmed as general, publicly-supported SDK concepts — ask your Binoban team if you believe you need them.