Track
activeThe 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:
| Field | Required? | Max length | Allowed characters |
|---|---|---|---|
userId | Optional; one identifier required | 64 | a–z A–Z 0–9 _ - . @ : |
anonymousId | Optional; one identifier required | 64 | a–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:
| Rule | Value |
|---|---|
| Required | Yes |
| Max length | 64 characters |
| Allowed characters | a–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:
| Rule | Value |
|---|---|
| Max length | 64 characters |
| Allowed characters | a–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:
| Reserved | Why |
|---|---|
Any name starting with cx_ | The prefix belongs to the flattened context block — cx_locale, cx_pageUrl, and so on. |
eventName | The event's own name, taken from the event field of the call. |
eventTime | The event's timestamp, taken from timestamp. |
receiveTime | The 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:
| Field | Type | Stored as | Description |
|---|---|---|---|
context.active | Boolean | cx_active | Whether the underlying session/device is currently active. |
context.app.name | String | cx_appName | Application name. |
context.app.packageName | String | cx_appPackageName | Application package/bundle identifier. |
context.app.version | String | cx_appVersion | Application version. |
context.app.build | String | cx_appBuild | Application build number. |
context.campaign.name | String | cx_campaignName | Marketing campaign name. |
context.campaign.source | String | cx_campaignSource | Campaign source. |
context.campaign.medium | String | cx_campaignMedium | Campaign medium. |
context.campaign.term | String | cx_campaignTerm | Campaign term. |
context.campaign.content | String | cx_campaignContent | Campaign content. |
context.device.id | String | cx_deviceId | Device identifier. |
context.device.sdk | String | cx_deviceSdk | Push delivery platform for this device: WEB, ANDROID, or IOS. |
context.device.advertisingId | String | cx_deviceAdvertisingId | Advertising identifier. |
context.device.token | String | cx_deviceToken | Push token. |
context.device.manufacturer | String | cx_deviceManufacturer | Device manufacturer. |
context.device.model | String | cx_deviceModel | Device model. |
context.device.name | String | cx_deviceName | Device name. |
context.device.type | String | cx_deviceType | Device type. |
context.device.version | String | cx_deviceVersion | Device OS/hardware version. |
context.device.webViewId | String | cx_deviceWebViewId | Identifier for a webview instance, used to align Native and Web SDK identity in a webview — see Webview behavior. |
context.ip | String | cx_ip | IP address the event was sent from. |
context.library.name | String | cx_libraryName | Name of the SDK that sent the event. |
context.library.version | String | cx_libraryVersion | Version of the SDK that sent the event. |
context.locale | String | cx_locale | Locale, e.g. en-US. |
context.network.bluetooth | String | cx_networkBluetooth | Bluetooth connectivity state. |
context.network.carrier | String | cx_networkCarrier | Mobile carrier. |
context.network.cellular | String | cx_networkCellular | Cellular connectivity state. |
context.network.wifi | String | cx_networkWifi | Wi-Fi connectivity state. |
context.os.name | String | cx_osName | Operating system name. |
context.os.version | String | cx_osVersion | Operating system version. |
context.page.name | String | cx_pageName | Page name. |
context.page.path | String | cx_pagePath | Page path. |
context.page.referrer | String | cx_pageReferrer | Page referrer. |
context.page.search | String | cx_pageSearch | Page query string. |
context.page.title | String | cx_pageTitle | Page title. |
context.page.url | String | cx_pageUrl | Page URL. |
context.page.keywords | String | cx_pageKeywords | Page keywords. |
context.referrer.type | String | cx_referrerType | Referrer type. |
context.referrer.name | String | cx_referrerName | Referrer name. |
context.referrer.url | String | cx_referrerUrl | Referrer URL. |
context.referrer.link | String | cx_referrerLink | Referrer link. |
context.userAgent | String | cx_userAgent | Browser/device user agent string. |
context.timezone | String | cx_timezone | Timezone. |
context.traits | Object | — | 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.
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.