Skip to content

JavaScript SDK API

The JavaScript SDK provides a comprehensive interface for working with the browser to track, personalize, and automate what you need on the web. Whether you want to track an event, monitor viewable content, or personalize visitor experiences, the JavaScript SDK provides a robust foundation for all of these capabilities.

The main way to interact with the JavaScript SDK is to call commands on it directly.

Overview

Below are the commands available on the JavaScript SDK:

configure

The configure function lets you initialize the SDK with an API key and some optional information. USER_TOKEN is not used at this time.

OPT_CONFIG is used to override default configuration of the SDK. If you want or need to know when the SDK is finally configured, you can use the OPT_CALLBACK parameter to provide a callback, with the signature (scope) => {...}.

isNewVisit

The isNewVisit returns a boolean whether the current pageview has initiated a new visit or not.

setOptOut

The setOptOut function allows you to opt a user in or out of the SDK.

track

The track function lets you send data to Orbee's back end. This function only requires an event string to be provided, but you can optionally tie key/value pairs to the event as well. If you want to know when the event was received by Orbee's back end, you can use the OPT_CALLBACK parameter with the signature (status, response_body) => {...}.

subscribe

The subscribe function lets you provide a callback that is called on each event fired to the track method. It returns the ID denoting the subscription.

unsubscribe

The unsubscribe method lets you unsubscribe your callback from a subscribe call.

associate

The associate call is a special version of the track command. This command will associate key/val properties with the device and/or user specifically, rather than just an event in their timeline. You can also subscribe a callback to know when Orbee's back end has received the association.

clearStorage

The method clears all caches and cookies the SDK is currently managing in that scope.

cache

The cache method lets you create a cache that is fetchable by its key. You can also provide a DEFAULT_VALUE which will be stored as the value if the cache doesn't already store a value.

getVisitId

This method returns the current ID of the current visit.

getDeviceId

This method returns the current ID of the device.

enableDebug

This method allows you to enable the SDK's debugger.

__VERSION__

This returns the version of the SDK loaded on your website.

Scopes

Scopes are localized versions of the SDK. Where the SDK exists as a global tag manager that manages the entire SDK, scopes exist at a level underneath, where all SDK functionality is isolated to the scope itself and its API Tokens that are configured for it.

getScope

The getScope function allows you to specifically get a scoped version of the SDK. All commands called directly on oa proxy their calls to the default scope.

If you provide a string value to the getScope function, then it will return a scoped version of the SDK specifically retrieveable by the string value you provided to the function.

Scope-Specific Functions

There are some functions only available to scopes:

datalayer

This returns the SDK's datalayer object. This object keeps track of the list of events tracked by the SDK on the current page, as well as the "state" aggregated over all those events.

extend

This extends the SDK with additional functionality. The class is instantiated with the scope itself as the only parameter, and is made available at:

// if you do this
oa.getScope().extend('test', myExtension);

// you can see it here:
oa.getScope().extensions.test;

require

This method waits for the list of requirements to be added to the SDK before calling the callback method. This makes it easy to wait for specific extensions to be loaded before you apply your functionality.

A common pattern is for extensions themselves to require other extensions. The JavaScript pattern looks like this:

// require extA on extB
oa.getScope().require(['extA'], (scope) => {
    scope.extend('extB', extB);
});

oa.getScope().extensions;
// {}

// later extA is added
oa.getScope().extend('extA', extA);

// you'll now see that both extA and extB have been added.
oa.getScope().extensions;
// {extA: ..., extB: ...}

Events

The SDK generates the following events:

$attribution

oa.track('$attribution', {
    referrer: '',
    referring_domain: '',
    gclid: '',
    fbclid: '',
    utm_source: '',
    utm_medium: '',
    utm_campaign: '',
    utm_term: '',
    utm_content: '',    
});

This event only fires on new visit. All properties of the event are optional and only present if they have a value.