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.