Analytics · JavaScript Reference

Onesecondbefore's Analytics JavaScript library lets you collect information about visitors on your website. It consists of a set of commands (e.g. send or set) and a set of (configuration) options that set certain values or change the library's behaviour.

• Commands
• (Data & Configuration) Options

Commands

Onesecondbefore's Analytics Javascript library is used with the following snippet:

osb(command, ...options)

Where command is a constant string that tells the command queue what it should do and options supply additional information to that command. The following commands are supported:

• add
• config
• consent · banner
• consent · wall
• debug
• get
• profile
• remove
• reset
• send
• set
• show
• uid

They are described in more detail below.

osb('set', ...) and osb('add', ...)

Sets or adds additional properties in the payload. The payload will not be sent after a 'set' or 'add'command. Only a subsequent 'send' will send the hit. Use 'add' if you want to add the { data ... } to any pre-existing data rather than overwriting the value.

Usage

osb('set', name, { data... }); // Sets an object e.g. page
osb('add', name, { data... }); // Adds an object to an array e.g. ids
osb('set', name, [{ data... }, ...]); // Sets an array of objects, e.g. items

Parameters

Common use-cases

Adds the Google Analytics client id to the payload (that will be sent with the next 'sent' command)

osb('add', 'ids', {
    key: '_ga',
    value: 'cookie:_ga' // 'GA1.2.123456789.1612345678'
});

Add a product item and add two custom product variables: color and size.

osb('add', 'items', { 
    id: 'abc123',
    category: 'clothing/dresses',
    name: 'BlackButterfly',
    color: 'green',
    size: 'm'
});

Set multiple products in a single command.

osb('set', 'items', [{
    id: 'sku123',
    name: 'Apple iPhone 14 Pro',
    category: 'mobile',
    price: 1234.56,
    quantity: 1
}, {
    id: 'sku234',
    name: 'Samsung Galaxy S22',
    category: 'mobile',
    price: 1034.56,
    quantity: 1
}]);

Set and hash an email address. Hashing happens in-memory on the Analytics server.

osb('set', 'ids', [{
    key: 'email',
    value: 'john.doe@example.com',
    hash: true
}]);

If the page has a <meta> tag like this:

<meta name="article-id" content="12345"/>

Retrieve this information with:

osb('set', 'page', {
    'id': 'meta:article-id' // '12345'
});

Retrieve information from an external URL and parse the JSON response to retrieve its value.

osb('set', 'page', {
    /* This URL should return a JSON response with a key 'user_id' */
    'user_id': 'url:https://api.example.com/getid'
});

Set consent information

//All purposes
osb('set', 'consent', 'all');

//Multiple purposes
osb('set', 'consent', 'necessary,analytics');

//Send the TC string (IAB Europe)
osb('set', 'consent', 'CPUP3OWPUP3OWFjAOBENChCsAP_-AH_-ABpaxK...');

osb('config', ...)

Allows reconfiguration of an existing tracker. This is e.g. required if before cookie consent you're not allowed to store the entire IP address ({ ipSettings: 1 }), whereas after you're allowed to do so ({ ipSettings: 0 }).

Usage

osb('config', { options... });

Parameters

Common use-cases

Change the siteId for the tracker. It is recommended to label all activity from the same app or website with the same siteId.

osb('config', {
    siteId: 'my.web'
});

Change the IP address and cookie settings default behaviour.

osb('config', {
    ipSettings: 3
    cookieSettings: 2
});

osb('consent', ...) · Consent Banner

Below documentation describes the consent possibilities in the regular tracker library loaded as osb.min.mjs. For the CMP version, look here.

Verify whether user has given cookie consent. There are two different implementations possible:

Using an external / central cookie domain

If the user has given consent, continue on the same page, otherwise, redirect the browser to a specified cookie consent page where the user can give their consent. If consent has already been given (if there are multiple sites under the same consent page), or the user has given consent, the user is redirected back to the current page with an additional querystring parameter which indicates that the user has given consent or not. If the user gave consent, a first-party cookie will be set.

Contact us to setup the cookie consent template, domain name, DNS and SSL certificate(s).

See here for more information.

Using a cookie bar on every page

If you would like to show a (simple / sticky) cookie bar on every page with buttons to either allow or deny consent. A cookie bar is made visible if no consent has been given on the current website. Two buttons can be added to the cookie bar to allow / deny consent. If (no) consent is given, a first-party cookie will be set and the cookie bar will be hidden. Additionally, a third button can be added with a number of checkboxes to specify which purposes have been consented. These purposes have no relation with the TCF version.

See here for more information.

Usage

Load the osb.min.mjs version of the tracker library.

<script type="module" crossorigin="use-credentials">
import osb from 'https://storage.googleapis.com/onesecondbefore/js/osb.min.mjs';
// --------------------------------------------------------------- ^^^^^^^^^^^
osb('config', accountId, { config options } );
osb('consent', { consent options });
osb('send', 'pageview');
</script>

Parameters

Consent options for external cookie domain

Example

osb('config', ACCOUNT_ID, {
    // Strip of last octet of IP address
    ipSettings: 1,
    trackerUrl: 'https://privacy.example.com'
});
osb('consent', {
    // Add a ?locale=XY parameter to the consentUrl if you want to localize this page
    consentUrl: 'https://privacy.example.com/consent',
    callback: function(consent, cduid) {
        // When consent has been given, update the IP settings to allow entire IP address
        // to be analyticsd
        if (consent !== 'none') {
            osb('config', ACCOUNT_ID, {
                ipSettings: 0
            });
        }
    });
});
osb('send', 'pageview');

If consent needs to be given by the visitor they might see a flash of content of the current page if it takes some time to execute all the javascript and redirect the user to the consent page. To eliminate this, the following can be used:

• Add an osb-cloak attribute to the body of the HTML document:

  <body osb-cloak>

• Add the following CSS style:

  [osb-cloak] > * { display: none; }
  /* Optional */
  [osb-cloak]::before { content: "Please wait..."; }

• If consent has (already) been given (or not) the osb-cloak attribute will be removed automatically from the <body> by osb('consent', ...) and hence the page is visible.

Cookie bar

Use this version if your website implements a cookie bar or similar on every page, as demonstrated in the videos below.

The cookie bar has the following requirements:

• The cookie bar has an HTML id as specified by the consentId, e.g. 'cookiebar'.
• The cookie bar has at least the following CSS (by default it is hidden, if class show is added, the cookie bar becomes visible).

  #cookiebar { display: none; }
  #cookiebar.show { display: block; }

• The cookie bar contains an <a class="allow"> or <button class="allow"> element the user can click to allow consent.
• Optionally, the cookie bar also contains a <a class="deny"> or <button class="deny"> the user can click to deny all consent.
• Optionally, the cookie bar also contains a <a class="save"> or <button class="save"> the user can click to save all consents that were selected using <input type="checkbox" name="purpose">.

When the above conditions are met, the script will verify whether consent has been given, if not the cookie bar will be shown and event listeners will be added to the allow and optionally to the deny and save buttons. When a button is clicked a first-party cookie is set with the given consent, the cookie bar is hidden again and the optional callback function is executed.

Consent options for cookie bar

Example

As an example, use the following HTML on every page:

<style>
#cookiebar {
  display: none;
  color: #fff;
  background-color: #000;
  padding: 15px;
  position: fixed;
  bottom: 0;
  width: 100%;
  z-index: 20;
}
#cookiebar.show {
  display: block;
}
</style>
<div id="cookiebar">
    <p>
        Lorem ipsum dolor sit amet
        <a href="/link/to/privacy">privacy statement</a>.
    </p>
    <button class="btn btn-primary allow">OK, give consent</button>
</div>

And the following javascript:

osb('consent', { consentId: 'cookiebar' } );

The cookie bar is then shown if no consent is given.

Advanced example

Below example shows allow, deny and save buttons and various purposes which will be saved. The values and labels for these purposes are arbitrary, but obvious choices are "necessary" or "functional", "analytics", "marketing" or "advertising", and "social". Note that the <input type="checkbox"> should have name="purpose". It would render as in below screenshot:

<style>
/* Same as example above */
</style>
<div id="cookiebar">
    <p>
        Lorem ipsum dolor sit amet.
        <a href="/link/to/privacy">Privacy policy</a>.
    </p>
    <p>
        <label><input type="checkbox" name="purpose" value="necessary">Necessary</label>
        <label><input type="checkbox" name="purpose" value="analytics">Analytics</label>
        <label><input type="checkbox" name="purpose" value="marketing">Marketing</label>
        <label><input type="checkbox" name="purpose" value="social">Social Media</label>
    </p>
    <p>
        <button class="btn btn-secondary save">Save preferences</button>
        <button class="btn btn-secondary deny">Deny all</button>
        <button class="btn btn-primary allow">Allow all</button>
    </p>
</div>

And the following javascript:

osb('consent', {
    consentId: 'cookiebar',
    callback: function(consent, cduid) {
        if (consent === 'none') {
            alert('No consent given');
        } else if (consent === 'all') {
            alert('All consent given');
        } else if (consent?.includes('marketing')) {
            alert('Marketing consented');
            // ... etc.
        }
    }
});

osb('consent', ...) · Consent Wall (IAB TCF 2.0) version

Below documentation describes the consent possibilities in the IAB TCF v2.0 tracker library loaded as osb-cmp.min.mjs. For the regular version, look here.

Verify whether user has given cookie consent using the IAB TCF v2.0 standard.

Usage

Load the osb-cmp.min.mjs version of the tracker library to include IAB TCF 2.0 compatibility.

<script type="module" crossorigin="use-credentials">
import osb from 'https://storage.googleapis.com/onesecondbefore/js/osb-cmp.min.mjs';
// --------------------------------------------------------------- ^^^^^^^^^^^^^^^
osb('config', accountId, { config options } );
osb('consent', { consent options });
osb('send', 'pageview');
</script>

Parameters

Consent options for external cookie domain

Examples

If visitor consented to purpose 1, update the ipSettings configuration parameter.

// Script loaded from "osb-cmp.min.mjs"
osb('config', ACCOUNT_ID, {
    ipSettings: 1
});
osb('consent', {
    configUrl: 'https://privacy.example.com/osb-config.json',
    callback: function(consent, cduid) {
        // Now consent is given, update the IP settings to allow entire IP address
        // to be captured
        if (consent.purposes && consent.purposes.includes(1)) {
            // Consent should include purpose 1 (Store and/or access information on a device)
            osb('config', ACCOUNT_ID, {
                ipSettings: 0
            });
        }
    });
});
osb('send', 'pageview');

Add a LinkedIn pixel if purposes 1, 8 and 15 have been consented.

const LINKEDIN_PARTNER_ID = '1234567';

function linkedin(partnerId) {
    window._linkedin_data_partner_ids = window._linkedin_data_partner_ids || [];
    window._linkedin_data_partner_ids.push(partnerId);
    const s = document.getElementsByTagName("script")[0];
    const b = document.createElement("script");
    b.async = true;
    b.src = "https://snap.licdn.com/li.lms-analytics/insight.min.js";
    s.parentNode.insertBefore(b, s);
}

// Script loaded from "osb-cmp.min.mjs"
osb('config', ACCOUNT_ID);
osb('consent', {
    configUrl: 'https://privacy.example.com/osb-config.json',
    callback: function(consent, cduid) {
        if (consent && consent.purposes && consent.purposes.includes(1) &&
            consent.purposes.includes(8) && consent.purposes.includes(15)) {
            linkedin(LINKEDIN_PARTNER_ID);
        }
    }
});
osb('send', 'pageview');

// Similar with more ES2016 features:
osb('config', ACCOUNT_ID);
osb('consent', {
    configUrl: 'https://privacy.example.com/osb-config.json',
    callback: (consent, cduid) => {
        if ([1,8,15].every((p) => { return consent?.purposes?.includes(p) }) {
            linkedin(LINKEDIN_PARTNER_ID);
        }
    }
});
osb('send', 'pageview');

// Or a function determining whether the CMP should be shown:
osb('config', ACCOUNT_ID);
osb('consent', {
    configUrl: 'https://privacy.example.com/osb-config.json',
    show: function() {
        return confirm('Click Yes if you want to show the CMP');
    }
});

// Or check whether a Bot is visiting the site and then don't show CMP:
osb('config', ACCOUNT_ID);
osb('consent', {
configUrl: 'https://privacy.example.com/osb-config.json',
    show: () => {
        if (navigator.userAgent.indexOf('Bot') >= 0) {
            // Don't show if it's a Bot
            return false;
        } else {
            // Default behaviour; show if no consent given, hide if already given
            return null;
        }
    }
});

Open CMP at a particular "page" or "tab":

<!-- Assume that osb object has already been loaded previously -->
<a href="#" onclick="osb('consent', { show: 1 })">Show cookie settings</a>
<a href="#" onclick="osb('consent', { show: 3 })">Show vendors</a>

osb('debug', ...)

Enables / disables additional debug logging in the console.

Usage

// Additional debugging information will be displayed in the JavaScript developer console.
osb('debug', enabled);

Parameters

Common use-cases

Switch on debug information in JavaScript Console.

osb('debug');

Switch off debug information in JavaScript Console.

osb('debug', false);

osb('get', ...)

Returns the content of the payload of a particular tracker.

Usage

osb('get', callback);
osb('get', name, callback);

Parameters

Common use-cases

Get consent

// Return consent
osb('get', 'consent', (purposes) => {
    // ['marketing', 'social', ... ]
    console.log(JSON.stringify(purposes));
});

Get the payload only of the event object.

// Return payload only for "event"
osb('get', 'event', (payload) => {
    console.log(JSON.stringify(payload));
});

osb('profile', ...)

Retrieve a profile based upon the current (cross-domain) user id cookie. A profile is a list of strings which translate into aspects known about the visitor, like viewer preference, location, age group, etc.

Usage

osb('profile', callback);

Parameters

Common use-cases

Get the user profile and log it in the JavaScript console of the browser. Handy for development purposes.

osb('profile', function(cduid, profile) {
    /* Profile is a list of strings which translate into various aspects */
    console.log(`Profile for ${cduid} = ${JSON.stringify(profile)}`);
});

Get the user profile and change the HTML accordingly. Typical use-case for onsite targeting.

osb('profile', function(cduid, profile) {
    /* Change the HTML of the current page, based on various aspects of the profile */
    if (profile && profile.indexOf('youth') >= 0) {
        changeHTML(profile);
    }
});

osb('remove', ...)

Removes additional payload data. It will no longer be sent along with requests.

Usage

osb('remove', name);

Parameters

Common use-cases

Sets and then removes the ids object. Use this if you only want the ids to be sent in a single hit.

osb('set', 'ids', { ... });
osb('send', 'ids');
osb('remove', 'ids');

osb('reset')

Resets all payloads.

Usage

osb('reset');

Parameters

Common use-cases

Resets all payloads.

osb('set', 'ids', { ... });
osb('set', 'page', { ... });
osb('reset');

osb('send', ...)

Sends a hit to the analytics server, like a pageview or an event.

Usage

osb('send', 'pageview', { options });
osb('send', 'event', { options });
//- osb('send', 'action', subtype, { options });
osb('send', 'ids', { options });
osb('send', 'viewable_impression', { options });

// In beta contact Onesecondbefore first
osb('send', 'aggregate', name, aggregate, value, scope);

Parameters

Common use-cases

Set additional payload from a <meta> tag on the page. If the page contains:

<meta name="article-id" content="12345">

You can get the information with:

osb('send', 'pageview', {
    'id': 'meta:article-id' // '12345'
});

Add the Google Analytics client id to the ids array and sends it immediately. Will show up with hit_type='ids' in hits table.

osb('send', 'ids', {
    key: '_ga',
    value: 'cookie:_ga' // 'GA1.2.123456789.1612345678'
});

Set multiple products in a single command and send those items together with the action. Typically on a thank-you page during e-commerce checkout. The value affiliation will be added to the data array of objects.

osb('set', 'items', [{
    id: 'sku123',
    name: 'Apple iPhone 14 Pro',
    category: 'mobile',
    price: 1234.56,
    quantity: 1
}, {
    id: 'sku234',
    name: 'Samsung Galaxy S22',
    category: 'mobile',
    price: 1034.56,
    quantity: 1
}]);
osb('set', 'action', {
    id: 'abcd1234',
    revenue: 2269.12,
    tax: (2269.12 * 0.21),
    shipping: 100,
    affiliation: 'partner_funnel'
});
//All information should be send with the pageview
osb('send', 'pageview');

(In beta, contact Onesecondbefore before use) Aggregate command to track scrolldepth on a page.

osb('send', 'aggregate', 'scrolldepth', 'max', 0.80, 'pageview')

(In beta, contact Onesecondbefore before use) Aggregate command to track the duration of a video.

osb('send', 'aggregate', 'video_duration', 'max', 34, 'event',
    {
        category: 'videos', // Must be same as corresponding event
        action: 'start', // Must be same as corresponding event
        label: 'funny cat movie' // Must be same as corresponding event
    })

osb('show', ...)

Returns the payload and config the tracker as a JSON object. Useful for debugging.

Usage

osb('show', function (response) {
    console.log(JSON.stringify(response));
});

Parameters

Common use-cases

Shows the meta information of the current tracker.

// Display everything in JavaScript developer console
osb('show');

// Display only the version
osb('show', function(response) {
    console.log(`Version = ${response.version}`);
});

osb('uid', ...)

Retrieves the cross-domain user-id (or domain user-id if not available) and calls a function with this UID as a parameter.

Usage

osb('uid', callback);

Parameters

Common use-cases

Retrieves the user_id.

osb('uid', function(uid) {
    console.log('UID = ' + uid);
}):

Options

There are two categories of options:

• configuration options
• data options

Configuration options

Configuration options can only be set with the config command. They are meant to configure the tracker and are not stored in your database.

Example usage

osb('config', {
    accountId: 'act123',
    cookieDomain: 'mydomain.com',
    cookieNamePrefix: '_osb_',
    cookiePath: '/',
    cookieSettings: 1,
    siteId: 'mygreatsite',
    forceGET: false,
    ipSettings: 0,
    userCookieTimeout: 31536000
    googleConsentMode: function(purposes) {
        return {
            ad_storage: purposes.includes('all') || purposes.includes('advertising') ? 'granted' : 'denied’,
            // ...
        }
    }
});

Properties

Cookie settings

IP settings

Data options

Data options can be set along its corresponding command (event, ids, items or pageview) or set with the set or add commands. With set, no hit is sent to the server, whereas with send a hit is sent to the server.

• action
• consent
• event
• ids
• items
• page

Dynamic options

By prefixing a data value it is possible to substitute certain values before they are being set in the respective payload. The following prefixes are supported:

Examples

// Retrieve Google Analytics cookie
osb('add', 'ids', {
    key: '_ga',
    value: 'cookie:_ga' // 'GA1.2.123456789.1612345678'
});

// Given a <meta name="article-id" content="12345"> tag, retrieve its value
osb('send', 'pageview', {
    'id': 'meta:article-id' // '12345'
});

// local/session storage
sessionStorage.setItem('username', 'john.doe@example.com');
localStorage.setItem('name', 'John Doe');
osb('add', 'ids', {
    name: 'local:name',
    email: 'session:email'
});

// Given a URL /search?q=iPhone
osb('send', 'pageview', {
    search_term: 'query:q' // iPhone
});

// Given a response {"some_id":1234567890}
osb('set', 'ids', {
    some_id: 'url:https://api.example.com/get_some_id'
});

// Given a JS function
osb('set', 'page', {
    random: function() { return Math.random(); }
});

Data options: action

Contains the options of an action. Actions are typically used to track ecommerce actions like purchase or checkout. It will populate the action object (Snowflake) or struct (BigQuery) in the Analytics hits table.

Supported commands

The following commands support the parameters:

• set · Sets the action object (Snowflake) or Struct (BigQuery) in the current payload, but doesn't send the information to the server.

Parameters

Data options: consent

Contains the consent value.

Supported commands

The following commands support the parameters:

• set · Sets the consent value in the current payload, but doesn't send it to the server.
• add · Adds a consent value to the existing consent array.

Parameter

The value can be sent as a string or an array, not as a JavaScript object as with other payload data.

Data options: event

Contains the options of an event. Will populate the event object (Snowflake) or struct (BigQuery) in the Analytics tables.

Supported commands

The following commands support the parameters:

• set · Sets the event object (Snowflake) or Struct (BigQuery) in the current payload, but doesn't send the information to the server.
• send 'event' · Sets the event object and sends the information. Will show up in the destination table with hit_type=event.

Parameters

Data options: ids

Contains the options of ids. Will populate the ids array in the Analytics tables.

Supported commands

The following commands support the parameters:

• add · Adds a single ids object to the ids array
• set · Sets the ids array in a single statement
• send 'ids' · Sets the ids array in a single statement and sends the information. Will show up in the destination table with hit_type=ids.

Parameters

Data options: items

Contains the options of items. Will populate the items array in the Analytics tables.

Supported commands

The following commands support the parameters:

• add · Adds a single item object to the items array
• set · Sets the items array with a single statement

Parameters

Data options: page

Contains the options of a page. Will populate the page object (Snowflake) or struct (BigQuery) in the Analytics tables.

Supported commands

The following commands support the parameters:

• set · Sets the page object (Snowflake) or Struct (BigQuery) in the current payload, but doesn't send the information to the server.
• send 'pageview' · Sets the page object and sends the information. Will show up in the destination table with hit_type=pageview.

Important note on On-Site Search

On-site search tracks all KPI's needed for deep insights in how users interact with your on-site search engine. As an extra feature we recommend to add a query parameter to each result link that tracks the number of the search result. The first search result should get number 1, the second result number 2, etc., etc. The query parameter is oss_result. Onesecondbefore picks up the parameter and this enables you to see which search result was clicked in combination with keyword and search filters. Below is a simple example that contains oss_result.

<h1>Your results for "Reggae":</h1>
<a href="/product/steel-pulse?oss_result=1">Bob Marley</a><br/>
<a href="/product/steel-pulse?oss_result=2">Steel Pulse</a><br/>
<a href="/product/steel-pulse?oss_result=3">Bunny Wailer</a><br/>
<a href="/product/steel-pulse?oss_result=4">The Gladiators</a><br/>

Parameters