Track

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 userId, anonymousId, or both:

Field	Required?	Max length	Allowed characters
userId	At least one of userId / anonymousId	64	a–z A–Z 0–9 _ - . @ :
anonymousId	At least one of userId / anonymousId	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. Omitting both rejects the call with error.sdk.missing.id. 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.

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.

Track has no reserved-property list. Unlike Identify's traits (where a handful of names like email get special length limits), every Track property is validated the same way regardless of its name — there's no backend concept of a property Binoban treats specially just because it's called revenue or currency. What you will 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:

Field	Type	Description
context.active	Boolean	Whether the underlying session/device is currently active.
context.app.name	String	Application name.
context.app.packageName	String	Application package/bundle identifier.
context.app.version	String	Application version.
context.app.build	String	Application build number.
context.campaign.name	String	Marketing campaign name.
context.campaign.source	String	Campaign source.
context.campaign.medium	String	Campaign medium.
context.campaign.term	String	Campaign term.
context.campaign.content	String	Campaign content.
context.device.id	String	Device identifier.
context.device.sdk	String	Push delivery platform for this device: WEB, ANDROID, or IOS.
context.device.advertisingId	String	Advertising identifier.
context.device.token	String	Push token.
context.device.manufacturer	String	Device manufacturer.
context.device.model	String	Device model.
context.device.name	String	Device name.
context.device.type	String	Device type.
context.device.version	String	Device OS/hardware version.
context.device.webViewId	String	Identifier for a webview instance, used to align Native and Web SDK identity in a webview — see Webview behavior.
context.ip	String	IP address the event was sent from.
context.library.name	String	Name of the SDK that sent the event.
context.library.version	String	Version of the SDK that sent the event.
context.locale	String	Locale, e.g. en-US.
context.network.bluetooth	String	Bluetooth connectivity state.
context.network.carrier	String	Mobile carrier.
context.network.cellular	String	Cellular connectivity state.
context.network.wifi	String	Wi-Fi connectivity state.
context.os.name	String	Operating system name.
context.os.version	String	Operating system version.
context.page.name	String	Page name.
context.page.path	String	Page path.
context.page.referrer	String	Page referrer.
context.page.search	String	Page query string.
context.page.title	String	Page title.
context.page.url	String	Page URL.
context.page.keywords	String	Page keywords.
context.referrer.type	String	Referrer type.
context.referrer.name	String	Referrer name.
context.referrer.url	String	Referrer URL.
context.referrer.link	String	Referrer link.
context.userAgent	String	Browser/device user agent string.
context.timezone	String	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.

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.