sdk

Web SDK Reference

draft

Audience: developerUpdated 2026-07-26

Getting Started

Use the Binoban.js QuickStart Guide to learn how to add Binoban.js to your site. Once you’ve installed the library, read on for the detailed API reference.

Basic tracking methods

The basic tracking methods below serve as the building blocks of your Binoban tracking. They include Identify, Track, Page.

For any of the methods described in this page, you can replace the properties in the code samples with variables that represent the data collected.

Identify

Use the identify method to link your users and their actions, to a recognizable userId and traits.

Identify calls and anonymous visitors

Binoban recommends against using identify for anonymous visitors to your site. Binoban.js automatically retrieves an anonymousId from localStorage or assigns one for new visitors, and then attaches it to all page and track events both before and after an identify.

The Identify method follows the format below:

Binoban.identify([userId], [traits], [options], [callback]);

The Identify call has the following fields:

Field		Type	Description
`userId`	optional	String	The database ID for the user. If you don't know who the user is yet, you can omit the `userId` and just record `traits`.
`traits`	optional	Object	A dictionary of traits you know about the user, like `email` or `name`.
`options`	optional	Object	A dictionary of options. for the call. Note: If you do not pass a `traits` object, pass an empty object (as an {}) before `options`.
`callback`	optional	Function	A function executed after a timeout of 300 ms, giving the browser time to make outbound requests first.

By default, Binoban.js caches traits in the browser's localStorage and attaches them to each Identify call.

For example, you might call Identify when someone signs up for a newsletter but hasn't yet created an account on your site. The example below shows an Identify call (using hard-coded traits) that you might send in this case.

Binoban.identify({
  nickname: "Amazing Denis",
  favoriteCompiler: "C",
  industry: "Computer Science",
});

Then, when the user completes the sign up process, you might see the following:

Binoban.identify("1234-xyz", {
  name: "Dennis Ritchie",
  email: "denis@c-language.org",
});

The traits object for the second call also includes nickname, favoriteCompiler, and industry.

You may omit both traits and options, and pass the callback as the second argument.

Binoban.identify("1234-xyz", function () {
  // Do something after the identify request has been sent
});

Track

The Track method lets you record actions your users perform. ou can see a track example in the Quickstart guide

The Track method follows the format below:

Binoban.track(event, [properties], [options], [callback]);

The track call has the following fields:

Field	Type	Description
`event`	String	The name of the event you're tracking.
`properties`	Object	Optional. A dictionary of properties for the event. If the event was `'added_to_cart'`, it might have properties like `price` and `productType`.
`options`	Object	Optional. A dictionary of options. Note: If you do not pass a `properties` object, pass an empty object (like {}) before `options`.
`callback`	Function	Optional. A function that runs after a timeout of 300 ms, giving the browser time to make outbound requests first.

The only required argument in Binoban.js is an event name string.

Example Track call:

Binoban.track("article_completed", {
  title: "How to Create a Tracking Plan",
  course: "Intro to binoban",
});

The only required argument on Track calls in Binoban.js is an event name string.

Track link

trackLink is a helper method that attaches a Track call as a handler to a link. When a user clicks the link, trackLink delays the navigation event by 300ms before proceeding, ensuring the Track request has enough time to send before the page starts unloading.

This is useful when a page redirects too quickly, preventing the Track method from completing all requests. By momentarily holding off navigation, trackLink increases the likelihood that tracking data reaches Binoban and destinations successfully.

The trackLink method follows the format below:

Binoban.trackLink(element, event, [properties]);

Field		Type	Description
`element(s)`		Element or Array	DOM element to bind with `track` method. You may pass an array of elements or jQuery objects. Note: This must be an element, not* a CSS selector.*
`event`		String or Function	The name of the event, passed to the `track` method. Or a function that returns a string to use as the name of the `track` event.
`properties`	optional	Object or Function	A dictionary of properties to pass with the track method or a function that returns an object to use as the `properties` of the event.

Example:

var link = document.getElementById("free-trial-link");

Binoban.trackLink(link, "clicked_free_trial_link", {
  plan: "Enterprise",
});

Track form

trackForm is a helper method that binds a track call to a form submission. The trackForm method inserts a timeout of 300 ms to give the track call more time to complete. This is useful to prevent a page from redirecting before the track method could complete all requests.

The trackForm method follows the format below.

Binoban.trackForm(form, event, [properties]);

Field		Type	Description
`form(s)`		Element or Array	The form element to track or an array of form elements or jQuery objects. Note: trackForm takes an element, not a CSS selector. Binoban recommends that you wait until the DOM loads before passing the form element.
`event`		String or Function	The name of the event, passed to the `track` method. Or a function that returns a string to use as the name of the `track` event.
`properties`	optional	Object or Function	A dictionary of properties to pass with the track method. Or a function that returns an object to use as the `properties` of the event.

Example:

var form = document.getElementById("signup-form");

Binoban.trackForm(form, "signed_up", {
  plan: "Premium",
  revenue: 99.0,
});

Page

The Page method lets you record page views on your website, along with optional extra information about the page viewed by the user.

Because some Destinations require a page call to instantiate their libraries, you must call page at least once per page load. You can call it more than once if needed, for example, on virtual page changes in a single page app.

Binoban.js includes a Page call by default as the final line in the Binoban.js snippet. You can update this page call within the guidelines below.

The page method follows the format below.

Binoban.page([category], [name], [properties], [options], [callback]);

The page call has the following fields:

Field		Type	Description
`category`	optional	String	The category of the page. Useful for cases like ecommerce where many pages might live under a single category. Note: if you pass only one string to `page` it is assumed to be `name`. You must* include a `name` to send a `category`.*
`name`	optional	String	The name of the page.
`properties`	optional	Object	A dictionary of properties of the page. Note: Binoban.js collects `url`, `title`, `referrer` and `path` are automatically. This defaults to a `canonical url`, if available, and falls back to `document.location.href`.
`options`	optional	Object	A dictionary of options. Note: If you do not pass a `properties` object, pass an empty object (like {}) before `options`.
`callback`	optional	Function	A function that runs after a timeout of 300 ms, giving the browser time to make outbound requests first. However, this function might not execute if one of the device-mode libraries has been blocked from loading.

Default page properties

Binoban.js adds properties to each page call.

Binoban.page("Pricing");

Binoban adds the following information:

Binoban.page("Pricing", {
  title: "example Pricing",
  url: "https://example.com/pricing",
  path: "/pricing",
  referrer: "https://example.com/warehouses",
});

You can override these values by explicitly setting them in your calls. For example:

Binoban.page("Pricing", {
  title: "My Overridden Title",
  path: "/pricing/view",
});

Translates to:

Binoban.page("Pricing", {
  title: "My Overridden Title",
  url: "https://example.com/pricing",
  path: "/pricing/view",
  referrer: "https://example.com/warehouses",
});

Binoban sets the path and url property to the value of the canonical element on your page. If a canonical element is not set, the values will be set from the browser.

Utility methods

The Binoban.js utility methods help you change how Binoban loads on your page. They include:

Ready
Debug
On (Emitter)
Timeout
Reset (Logout)

Ready

The ready method lets you pass in a method that gets called after Binoban.js finishes initializing and after all internal settings load. It's like jQuery's ready method

Note: window.Binoban.initialized is a simple boolean, not an event or a pub/sub system. This means you can't subscribe to changes in its value. If you need to detect when it changes from false to true, you must set up a polling mechanism to monitor the value.

The code in the ready function only executes after ready is emitted.

Binoban.ready(() => {
  console.log("Binoban is ready!");
});

The ready method uses the following format:

Binoban.ready(callback);

The ready method has the following fields:

Field	Type	Description
`callback`	Function	A function to be executed after all enabled destinations have loaded.

Debug

Calling the debug method turns on debug mode, which logs helpful messages to the console. Subsequent Binoban events generate messages in the developer console after you invoke debug.

Enable:

Binoban.debug(true);

Disable:

Binoban.debug(false);

Emitter

The global binoban object emits events whenever you call identify, track, or page.

Use the on method to set listeners for these events and run your own custom code. This can be useful if you want to send data to a service for which Binoban doesn't have a destination.

Binoban.on(method, callback);

Field	Type	Description
`method`	String	Name of the method to listen for.
`callback`	Function	A function to execute after each emitted method, taking three arguments: `event`, `properties`, `options`.

Example:

Binoban.on("track", (event, properties, options) => {
  bigdataTool.push(["recordEvent", event]);
});

This method emits events before they are processed by the Binoban integration, and may not include some of the normalization Binoban performs on the client before sending the data to the Binoban servers.

info

Page event properties are stored in the options object.

Extending timeout

The timeout method sets the length (in milliseconds) of callbacks and helper functions. This is useful if you have multiple scripts that need to fire in your callback or trackLink, trackForm helper function.

The example below sets the timeout to 500 ms.

Binoban.timeout(500);

success "Tip" If you're triggering ad network conversion pixels, Binoban recommends extending timeout to 500 ms to account for slow load times.

Reset or log out

Calling reset resets the id, including anonymousId, and clears traits for the currently identified user and group.

Binoban.reset();

The reset method only clears the cookies and localStorage created by Binoban. It doesn't clear data from other integrated tools, as those native libraries might set their own cookies to manage user tracking, sessions, and manage state. To completely clear out the user session, see the documentation provided by those tools.

Binoban doesn't share localStorage across subdomains. If you use Binoban tracking on multiple subdomains, you must call Binoban.reset() for each subdomain to completely clear out the user session.

Retries

Binoban.js automatically retries sending events when there are network or server errors. This helps reduce data loss in cases where the user is offline or the Binoban API is temporarily unavailable.

When retries are enabled, Binoban.js can:

Track users offline. Events get stored locally and sent once the user comes back online.
Handle intermittent network issues. Events are queued and retried until they’re successfully delivered.

Here's how retries work:

Events are stored in localStorage when available, with an in-memory fallback.
Binoban.js retries up to 10 times, with increasing backoff intervals between attempts.
A maximum of 100 events can be queued to avoid using too much local storage.

UTM Tracking

UTM parameters are only used when linking to your site from outside your domain. When a visitor arrives using a link containing UTM parameters, Binoban's WebSDK library will parse the URL query string and add the information to the event payload.

UTM parameters contain three essential components (utm_source, utm_medium, utm_campaign) and two optional (utm_content, utm_term). For example, if you include the following three parameters in your URL: ?utm_source=mysource&utm_medium=email&utm_campaign=mytestcampaign, once a visitor arrives using a link containing the above, Binoban automatically grabs the UTM parameters and subsequent events will contain these parameters within the 'context' object (visible in the raw view of your Source Debugger.)

So, for example, if somebody follows the link with above query string to your site, the subsequent 'page' call in your Debugger should contain the below and will be passed to any enabled destinations:

"context": {
 "campaign": {
 "medium": "email",
 "name": "mytestcampaign",
 "source": "mysource",
 },

Whenever the UTM parameters are no longer a part of the URL, Binoban no longer includes them. For example, if the user goes to a new page within your website which does not contain these parameters, they will not be included in subsequent events. UTM parameters are non-persistent by default as they could potentially cause data accuracy problems. Here's an example of why: Say a user clicks on an ad and lands on your site. He navigates around and bookmarks an internal page - or maybe shares a link with a friend, who shares it with another friend. All those links would then point back to the same test utm_source as the initial referrer for any purchase.

Binoban doesn't validate UTM parameter names. This design supports the flexibility to track both standard parameters (for example, utm_source, utm_medium) and custom parameters defined by users. As a result, all parameters present in the URL collected as is, and are added to the context field without checks for naming conventions or validity.

If you want to ensure that only standard UTM parameters (such as, utm_source, utm_medium, utm_campaign, utm_content, utm_term) are included in the context.campaign object, you can implement Source middleware in your Binoban.js setup.

For example:

window.Binoban.addSourceMiddleware(({ payload, next }) => {
  if (payload.obj.context?.campaign) {
    const allowedFields = ["source", "medium", "term", "campaign", "content"];
    const campaign = payload.obj.context.campaign;
    Object.keys(campaign).forEach((key) => {
      if (!allowedFields.includes(key)) {
        delete campaign[key];
      }
    });
  }
  next(payload);
});

This middleware filters out any non-standard parameters from the context.campaign object before they're sent to Binoban or forwarded to your enabled destinations.

Binoban.js performance

The Binoban.js library is loaded with the HTML script async tag. This also means that Binoban fires methods asynchronously, so you should adjust your code accordingly if you require that events be sent from the browser in a specific order.

info

Binoban.js doesn't set third-party cookies and only sets first-party cookies.

Cookies set by Binoban.js

Binoban sets three cookies in general:

Cookie	Description
`bob_anonymous_id`	An anonymous ID generated by Binoban.js, used for Binoban calls.
`bob_user_id`	A user ID that can be specified by making an `identify()` call with Binoban.js.

For Google Chrome, these cookies expire by default one year after the date created. Other supported browsers might have a different expiration time.

Some user/group traits are also stored in localStorage:

Cookie	Description
`bob_user_traits`	The traits that are passed in an `identify()` call.

Note that localStorage variables don't expire because the browser defines that functionality.

Local storage cookies used by Binoban.js

Binoban.js uses localstorage cookies if you have retries enabled, to keep track of retry timing.

The ack cookie is a timer used to see if another tab should claim the retry queue.
The reclaimStart and reclaimEnd cookies determine if a tab takes over the queue from another tab.
The inProgress and queue cookies track events in progress, and events queued for retry.

You can set the debug cookie to Binoban.js to log debug messages from Binoban.js to the console.

Tracking Blockers and Browser Privacy Settings

Binoban does not endorse bypassing tracking blockers or browser privacy settings for client-side tracking. Your users have control over what gets loaded on their pages and can use plugins or browser settings to block third-party scripts, including Binoban. To minimize client-side data loss, Binoban recommends you choose from the following routes:

Respect the user's decision to implement tracking blockers or use privacy settings, knowing that, unfortunately, some data will be lost.
Ask the customer to disable the tracking blockers or adjust their privacy settings (for example, in the case of large, corporate customers).
Move as many events and tracking actions as possible to a server-side library, which won't encounter the same limitations.

Global namespace

When loaded via the snippet, the SDK is installed on the global key window.__GLOBAL_CDXP_SDK_KEY. Reference it by that name if you need to reach the instance directly outside your snippet.

Identity

This section explains how Binoban.js identifies users, and passes userID and anonymousID data, and how to override and change this information.

Binoban ID Persistence

To ensure high fidelity, first-party customer data, Binoban writes the user's IDs to the user's local storage, and uses that as the Binoban ID on the cookie whenever possible. Local Storage is meant for storing this type of first-party customer information.

If a user returns to your site after the cookie expires, Binoban.js looks for an old ID in the user's localStorage, and if one is found, sets it as the user's ID again in the new cookie. If a user clears their cookies and localstorage, all of the IDs are removed, and the user gets a completely new anonymousID when they next visit the page.

Anonymous IDs

Binoban.js generates a universally unique ID (UUID) for the viewer during the library's initialization phase, and sets this as anonymousId for each new visitor to your site.

Example:

bob_anonymous_id=%2239ee7ea5-b6d8-4174-b612-04e1ef3fa952

You can override the default-generated anonymousID in code using the methods described below:

Set anonymousId from the Binoban snippet (before the ready method returns)
Use a call to override the anonymousID
Set anonymousId in the options object of a call

Retrieve the Anonymous ID

You can get the user's current anonymousId using the following call:

Binoban.user().anonymousId();

If the user's anonymousId is null (meaning not set) when you call this function, Binoban.js automatically generated and sets a new anonymousId for the user.

Refreshing the Anonymous ID

A user's anonymousId changes when any of the following conditions are met.

The user clears their cookies and localstorage.
Your site or app calls Binoban.reset() during in the user's browser session.
Your site or app calls Binoban.identify() with a userId that is different from the current userId.
Your site or app is setting bob_user_id to an empty string or calling Binoban.user().id('') before calling Binoban.identify(). This sequence of events will result in a new anonymousId being set when Binoban.identify() is called.

Override the Anonymous ID from the Binoban snippet

You can also set the anonymousId immediately inside your Binoban snippet, even before the ready method returns.

Binoban.setAnonymousId("ABC-123-XYZ");

Use this method if you are queueing calls before ready returns and they require a custom anonymousId. Keep in mind that setting the anonymousId in Binoban.js does not overwrite the anonymous tracking IDs for any destinations you're using.

Override the default Anonymous ID with a call

If the default generated UUID does not meet your needs, you can override it anonymousId for the current user using either of the following methods.

Binoban.user().anonymousId("ABC-123-XYZ");

Binoban.setAnonymousId("ABC-123-XYZ");

These methods behave exactly the same.

Override the Anonymous ID using the options object

Or in the options object of identify, page, or track calls, like this:

Set the anonymousId in the Options object using the format in the following examples.

The custom anonymousId persists when you use these methods, even if you do not explicitly specify the anonymousId in the calls.

For example, after the Track call below sets the anonId, any later track calls from this user will have the anonymousId of ABC-123-XYZ, even if it is not explicitly specified in the track call.

Override anonymousId in an Identify call

Binoban.identify(
  "user_123",
  {
    name: "Jane Doe",
  },
  {
    anonymousId: "ABC-123-XYZ",
  }
);

Override anonymousId on a Page call

Binoban.page({}, { anonymousId: "ABC-123-XYZ" });

Override anonymousId on a Track call

Binoban.track(
  "email_clicked",
  {
    callToAction: "Signup",
  },
  {
    anonymousId: "ABC-123-XYZ",
  }
);

Saving traits to the context object

Traits are individual pieces of information that you know about a user, and which can change over time.

The options dictionary contains a sub-dictionary called context which automatically captures data depending on the event- and source-type.

The context object contains an optional traits dictionary that contains traits about the current user. You can use this to store information about a user that you got from previous Identify calls, and that you want to add to Track or Page events.

success

The traits object in options.context.traits does not cause anonymousId to persist across different calls.

Consider this Identify event:

Binoban.identify("12091906-01011992", {
  plan_id: "Paid, Tier 2",
  email: "grace@example.com",
});

The "trait" on this event is plan_id. You can pass these traits into context.traits, so you can use them in Track or Page events that the user triggers later.

The example below shows how you could pass the plan_id as a trait so you can use it later.

Binoban.track(
  "clicked_email",
  {
    emailCampaign: "First Touch",
  },
  {
    traits: {
      plan_id: "Paid, Tier 2",
    },
  }
);

This appends the plan_id trait to this Track event. This does not add the name or email, since those traits were not added to the context object. You must do this for every following event you want these traits to appear on, as the traits object does not persist between calls.

By default, non-Identify events (like Track or Page) don't automatically collect user traits from previous Identify calls. To include traits from an identify() event in later events, you'll need to add them manually to the context.traits object within the options parameter.

Each Binoban.js method has an options parameter where you can pass the context.traits object, but each method has a specific format.

Clearing Traits

You can pass an empty object to the traits object to clear all cached traits for a User or Group.

Traits are cached by default when you call the Identify method. You can clear the traits object for the user by passing traits an empty object:

Binoban.user().traits({});

Using Binoban.user()

You can use the user method as soon as the Binoban.js library loads, to return information about the currently identified user or group. This information is retrieved from the user's cookie.

success

Tip: You can wrap any reference to user() in a ready function block to ensure that Binoban.js has fully loaded so these methods are available.

Examples:

Binoban.ready(function () {
  var user = Binoban.user();
  var id = user.id();
  var traits = user.traits();
});

Binoban.ready(function () {
  var group = Binoban.group();
  var id = group.id();
  var traits = group.traits();
});

Push notifications

Web push is delivered through Firebase Cloud Messaging and rendered by Binoban's service worker, binoban-messaging.js. For the step-by-step integration see Web push.

Registering a browser

There is no dedicated method. Track the token Firebase gives you:

Binoban.track('notification_registered', { key: token })

The SDK's push plugin rewrites this event to bb_notification_registered and adds sdk: "WEB" and the current device_id before it is sent. That renamed event is what marks the browser reachable. See Push events.

Call it again on every token refresh.

What the service worker handles

binoban-messaging.js is deployed by Binoban to your infrastructure; you load it from your own service worker with importScripts. Once registered it:

displays the notification using the payload's title, body, icon, image, and badge, honouring requireInteraction;
reports delivered on display, and failed if the browser refuses to display;
renders up to two action buttons — browsers without notification-action support ignore them;
reports clicked with the button index and resolved target URL, then focuses an already-open tab for that URL or opens a new window;
reports closed on dismissal;
falls back to your site when a payload carries no target.

It ignores any payload whose source is not "binoban", so it coexists with your own push handling.

Limits

No subscribe() helper. Requesting permission and registering the worker are your app's — they are ordinary browser APIs, and consent UX is a site decision.
customData is not read on the web. It is available on the native SDKs only; carry context in the target URL instead.
Two action buttons on the web, against three on native.

Advanced

Tracking in Webview

if you have an Android or iOS App that load your web site in web view, and want to track app users with our web sdk, you should provide android and ios specific credential during initialization

// Load SDK with your key, which will automatically
// load the tools you've enabled for your account. Boosh!
_SDK.load({
  credentials: {
    apiKey: "PROJECT_WEB_API_KEY",
    sourceIdentifier: "PROJECT_WEB_SOURCE_IDENTIFIER",
  },
  host: {
    rtbPath: "YOUR_BINOBAN_SERVER_RTB_URL",
    sdkPath: "YOUR_BINOBAN_SERVER_SDK_URL",
    apiPath: "YOUR_BINOBAN_SERVER_API_URL",
  },
  //<--------------- HERE --------------->
  mobileApp: {
    loadedInWebview: true,
    androidCredentials: {
      apiKey: "PROJECT_ANDROID_API_KEY",
      sourceIdentifier: "PROJECT_ANDROID_SOURCE_IDENTIFIER",
    },
    iosCredentials: {
      apiKey: "PROJECTE_IOS_API_KEY",
      sourceIdentifier: "PROJECT_IOS_SOURCE_IDENTIFIER",
    },
  },
});

info

please note that you should loadedInWebview to true if your web app is in mobile view and set it to false if not.

if you want to enable Binoban Cookie Syncing mechanism with Ad Networks like mediaAd and Yekta Neet, you should pass these options to sdk (during initialization)

// Load SDK with your key, which will automatically
// load the tools you've enabled for your account. Boosh!
_SDK.load({
  credentials: {
    apiKey: "PROJECT_API_KEY",
    sourceIdentifier: "PROJECT_SOURCE_IDENTIFIER",
  },
  host: {
    rtbPath: "YOUR_BINOBAN_SERVER_RTB_URL",
    sdkPath: "YOUR_BINOBAN_SERVER_SDK_URL",
    apiPath: "YOUR_BINOBAN_SERVER_API_URL",
  },
  //<--------------- HERE --------------->
  cookieSync: {
    mediaAd: true,
    yektanet: true,
    yektanetId: "YOUR_YEKTANET_ID",
  },
});

info

you should replace YOUR_YEKTANET_ID with your project specific ID that will provided for you by our support team.

Getting Started​

Basic tracking methods​

Identify​

Track​

Track link​

Track form​

Page​

Default page properties​

Utility methods​

Ready​

Debug​

Emitter​

Extending timeout​

Reset or log out​

Retries​

UTM Tracking​

Binoban.js performance​

Cookies set by Binoban.js​

Local storage cookies used by Binoban.js​

Tracking Blockers and Browser Privacy Settings​

Global namespace​

Identity​

Binoban ID Persistence​

Anonymous IDs​

Retrieve the Anonymous ID​

Refreshing the Anonymous ID​

Override the Anonymous ID from the Binoban snippet​

Override the default Anonymous ID with a call​

Override the Anonymous ID using the options object​

Override anonymousId in an Identify call​

Override anonymousId on a Page call​

Override anonymousId on a Track call​

Saving traits to the context object​

Clearing Traits​

Using Binoban.user()​

Push notifications​

Registering a browser​

What the service worker handles​

Limits​

Advanced​

Tracking in Webview​

Cookie Sync​

Getting Started

Basic tracking methods

Identify

Track

Track link

Track form

Page

Default page properties

Utility methods

Ready

Debug

Emitter

Extending timeout

Reset or log out

Retries

UTM Tracking

Binoban.js performance

Cookies set by Binoban.js

Local storage cookies used by Binoban.js

Tracking Blockers and Browser Privacy Settings

Global namespace

Identity

Binoban ID Persistence

Anonymous IDs

Retrieve the Anonymous ID

Refreshing the Anonymous ID

Override the Anonymous ID from the Binoban snippet

Override the default Anonymous ID with a call

Override the Anonymous ID using the options object

Override anonymousId in an Identify call

Override anonymousId on a Page call

Override anonymousId on a Track call

Saving traits to the context object

Clearing Traits

Using Binoban.user()

Push notifications

Registering a browser

What the service worker handles

Limits

Advanced

Tracking in Webview

Cookie Sync