JS SDK¶

JS SDK vs. Web SDK

Orbee recommends the JS SDK over the Web SDK for two reasons:

The Web SDK is in maintenance mode an will not receive new features
The JS SDK offers many more capabilities while also providing a significantly smaller bundle size

Getting started¶

Use this quickstart guide to get started with Orbee JS SDK.

Usage¶

Initialize the SDK¶

You must initialize the SDK before you can send any events. Your installation should include a SCRIPT_TOKEN in the script that will auto-configure the SDK for you.

If you should choose to configure the SDK yourself, you can do so by calling the config command:

orb('config', 'SCRIPT_TOKEN', optional_configuration);

You likely don't need to do this!

If you manage your script, tags, and triggers using the Orbee Platform, your script will auto-configure itself for you. In that case, you don't need to run the above command.

Tracking an event¶

Events represent how users interact with your website. The JS SDK automatically tracks standard web events, like pageviews, clicks, and form submits. It's also aware of automotive-specific features, like vehicles, VINs, and specials.

To track custom events, use the track command:

// track a basic event
orb('track', 'Vehicle Viewed');

// track an event with optional properties
const eventProperties = {
    vin: 'abc123efg456tigya'
};
orb('track', 'Vehicle Viewed', eventProperties);

Tracking default events¶

The JS SDK tracks default events. The SDK can be configured to track the following events automatically:

initialization
page views
visits
form interactions
clicks

Plugins¶

Plugins allow you to extend Orbee JS SDK's behavior by extending its functionality.

All plugins are available via the callback of a require command, or directly on the SDK by calling orb.sdk.<pluginName>.

`extend`¶

The extend method adds a plugin to the JS SDK.

orb('extend', 'pluginName', Plugin);

`require`¶

The require method can be used to request a plugin to be added to the JS SDK.

orb('require', 'pluginName', {callback: optional_callback})

When calling require, the JS SDK will fetch the plugin and call the associated extend command with the results.

If you want to fetch the plugin code yourself (e.g. you write and host that code yourself), you have two options:

You can add the script yourself:

<script src="https://mydomain.com/my-orbee-plugin.min.js">

2. You can provide the URL to the require call's configuration options:

orb('require', 'pluginName', {
     url: "https://mydomain.com/my-orbee-plugin.min.js"
});

`command`¶

To call a plugin, you have two options:

You can hope its already loaded, and access any command via orb.sdk.{plugin_name}.command(parameters)
You can queue up the command asyncronously: orb('command', 'plugin', 'method', parameters);

Commands have the following arguments:

plugin: The name of the plugin the command should be sent to
method: The method of the plugin that should be called
parameters: The arguments that should be passed to the plugin's method call

Example Plugin¶

class MyPlugin {
    constructor(sdk) {
        this.sdk = sdk;
    }

    myFunction() {
        this.sdk.track('myFuncCalled');
    }

    types() {
        return {
            "orb.plugin.type:command": true
        };
    }

    version() {
        return "1.0.0";
    }
}

orb('extend', 'MyPlugin', MyPlugin);

// then call your new function:
orb((orb) => {
    orb.sdk.MyPlugin.myFunction();
});

Caches¶

The SDK also supports providing you with ways to cache data.

To create a cache, you can call it like this:

orb((sdk) => {
    const cache = sdk.cache('MyCache');

    let value = {a: 2};
    cache.set(value);
})

You can get the value of the cache, set the value of the cache, or clear the value of the cache. All caches are stored in LocalStorage.

Manipulating DOM¶

You have three methods available to you in order to manipulate the DOM of the webpage: install, style, and render.

`install`¶

The install method lets you install a script on the page. If the script is already installed, it will be skipped. Optionally, you can pass a callback to be called once the script has been loaded.

orb('install', '/myscript.js', () => {
    console.log('script loaded!');
});

`style`¶

The style method lets you install some CSS on the webpage.

orb('style', '/mystylesheet.css');

`render`¶

The render command lets you append HTML as a child to an existing DOM element.

orb('render', document.body, '<div>My Cool Rendered Content</div>');

Generating unique identifiers¶

The uuid method lets you generate a UUID. Since many aspects of working with the SDK require identifying unique DOM elements and website interactions, this method is a helpful way to generate a unique indentifier.

orb((sdk) => {
    const myIdentifier = sdk.uuid();
});

Advanced topics¶

Customizing the `orb` instance¶

If you need multiple of the SDK loaded, or need to rename the orb instance to something else, you can do so via the instance parameter when installing the JS SDK:

<script async src="https://scripts.orb.ee/sdk/tms.js?sid=SCRIPT_TOKEN&instance=analytics"></script>
<script>;(function(w,d,n){if(!w[n]){w[n]=function(){return (w[n].q=w[n].q||[]).push(arguments)};w[n].q=w[n].q||[];}}(window,document,"analytics"));</script>

Let's break that down:

You add &instance=analytics to the script URI
You change orb to analytics at the end of the SDK shim script

With the above script, you'd be using an analytics instance, and call it using the following:

analytics('track', 'MyEvent');

Routing events and data¶

Before understanding how the JS SDK supports routing events, we need to define a few terms.

Target¶

A target is a destination an event is being sent to.

There are two types of targets: namespaces and tokens.

Token¶

A token is your script identifier or API Key you use in conjunction with the JS SDK. If you want to collect and track events, or configure the script to perform triggers and tags on your behalf, you do so via your token.

Namespace¶

A namespace is a simple fan-out router of events. Events sent to a namespace can be routed to a variety of targets that have joined the namespace.

How it works¶

You can create a namespace by calling join without a token:

orb('join', null, ['MyNamespace']);

You can have your token join and/or create as many namespaces as you want:

orb('join', 'MyToken', ['namespace1', 'namespace2', ...]);

Any events fired before and after a target joins a namespace will be sent after joining.

Some plugins use namespaces¶

Some plugins are generative, meaning that they generate new events for you to subscribe to. For example, a vendor-based plugin for "Orbee" might create a namespace "Orbee" that it fires events to.

Plugins that are generative should be tagged as such via its types method -- e.g.:

// this prints `{"orb.plugin.type:generative": true}`
console.log(orb.sdk.Orbee.types());

A plugin's generated namespace name should match the name of the plugin.

Last update: 2023-04-20