Capture · Reference

The Onesecondbefore Javascript tracker library consists of a number of queued calls using the following syntax:

osb(command, ...parameters)

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

They are described in more detail below.

osb('create', ...)

Creates an instance of a tracker. When you create a tracker you also specify the configuration like the URL of the tracker or the account ID.

Multiple trackers can be created with different configurations as long as the tracker names are different.

Usage

osb('create', accountId, trackerName, { options... });
OSB.create(accountId: String, trackerName: String, dataObject: OSBCreateOptions)
OSB.create(String accountId, String trackerName, OSBCreateOptions dataObject);
osb.create(accountId, trackerName, dataObject);

Parameters

parameter nametyperequireddescription
'create'stringyesName of command.
accountIdstringyesAccount id which specifies where your hits will be stored.
trackerNamestringnoNamespace of the tracker. If no namespace is given 'default' is used. If a new tracker is created without a name, the first one will be overwritten.
optionsJS objectnoOptional tracker configuration options, see below.

Optional tracker configuration options

configuration option nametypedefault valuedescription
cookieDomainstringDepends on domain name / host HTTP request headerFirst party cookie domain. Default is final two '.' separated parts of the requesting domain name.
cookieNamePrefixstring'_osb_'Prefix of all OSB Capture cookies.
cookiePathstring'/'Cookie path.
cookieSettingsnumeric1Which cookie settings to use, see below for an overview.
forceGETbooleanfalseTrue forces the tracker to use an HTTP GET rather than POST method.
ipSettingsnumeric0Which IP settings to use, see below for an overview.
siteIdstringNoneSite ID, to distinguish which site sends the hit. Especially useful if your site spans multiple domain anmes or you want to categorize hits of the same domain.
trackerUrlstring'https://g.ab21.xyz'Tracker URL endpoint.
userCookieTimeoutnumeric31536000Timeout of the user cookie in seconds. Default is 1 year.
cookie settingsdescription
0Saves cross domain user id first party with the help of an external JavaScript file if necessary (in ancient browsers).
1Saves cross domain user id first party with XmlHttpRequest (default).
2Doesn’t save cross domain user id first party using JavaScript.
3Doesn’t save any cookies, either first or third party.

IP settings

IP settingsdescription
0Entire IP address will be saved.
1Last octet of the IPv4 address will be removed before storing (but used for country, city matching). E.g. 12.34.56.78 will be stored as 12.34.56.0.
2Entire IP address will be saved in a hashed format.
3IP address will be saved as 'hidden'.

If you specify a custom trackerUrl, make sure you've contacted Onesecondbefore Support to make sure DNS and SSL certificates are properly configured.

The default cookieDomain will be example.com for requests from subdomain.example.com. You need to specify this setting for any domain that's part of the Public Suffic List which when split on '.' has more than one part, e.g. example.co.uk or example.co.jp.

Examples

// Minimal configuration for account exampleAccount. The namespace will be default
osb('create', 'exampleAccount');

// Creates a tracker for exampleAccount in the namespace secondTracker:
osb('create', 'exampleAccount', 'secondTracker');

// Creates a tracker with extra configuration options:
osb('create', 'exampleAccount', 'default', {
    siteId: 'mysite.web',
    forceGET: true,
    cookieDomain: 'mydomain.co.jp'
});
// Minimal configuration for account exampleAccount. The namespace will be default
OSB.create(accountId: "exampleAccount", trackerName: null, dataObject: null)

// Creates a tracker for exampleAccount in the namespace secondTracker:
OSB.create(accountId: "exampleAccount", trackerName: "secondTracker", dataObject: null)

// Creates a tracker with extra configuration options:
let dataObject = OSBCreateOptions()
dataObject.siteId = "mysite.app"
dataObject.forceGET = true
dataObject.cookieDomain = "mydomain.co.jp"
OSB.create(accountId: "exampleAccount", trackerName: "", dataObject: dataObject)
// Minimal configuration for account exampleAccount. The namespace will be default
OSB.create("exampleAccount", null, null);

// Creates a 2nd tracker secondTracker
OSB.create("exampleAccount", "secondTracker");

// Creates a tracker with extra configuration options:
OSBCreateOptions dataObject = new OSBCreateOptions("siteId", true, "mydomain.co.jp");
OSB.create(accountId: "exampleAccount", "mysite.web", dataObject);
OSB.create("exampleAccount", "secondTracker", null)
// Minimal configuration for account exampleAccount. The namespace will be default
osb('create', 'exampleAccount')

// Creates a tracker for exampleAccount in the namespace secondTracker:
osb('create', 'exampleAccount', 'secondTracker')

// Creates a tracker with extra configuration options:
osb('create', 'exampleAccount', {
    siteId: 'mysite.app'
});

osb('send', ...)

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

Usage

osb('send', 'pageview', { options }, [trackerNames]);
osb('send', 'event', { options }, [trackerNames]);
osb('send', 'action', subtype, { options }, [trackerNames]);
osb('send', 'ids', { options }, [trackerNames]);
OSB.send(type: OSBEventType, subtype: String, dataObject: OSBSendOptions, trackerNames: String[])
OSB.send(OSBEventType type, String subtype, OSBSendOptions dataObject, String[] trackerNames)
osb('send', type, subtype, dataObject)

Parameters

parameter nametyperequireddescription
'send'stringyesName of command.
typestringyesSpecifies the type to send. The type will be written in column hit_type, except for 'action', where sub_type will be used. See below for the supported types
subtypestringyes if type equals 'action'You can choose an action from the ga() command queue (detail, add, remove, checkout, checkout_option, purchase, refund or promo_click), or use your own action as long as they only contain letters, numbers and/or underscores. The chosen subtype will be placed in the hit_type column.
{ options }JS objectnoContains type specific data. Please refer to the set command to see which data can be sent with what type of action.
[trackerNames]array of stringnoNamespaces of the trackers that will be sent. If no namespaces are given, all trackers will be sent.

Type overview

typedescription
'action'tracks an action. If you choose action, you must define a subtype, column hit_type will contain the value of the subtype.
'event'tracks an event, column hit_type will contain 'event'.
'ids'tracks ids.
'pageview'tracks a pageview, column hit_type will contain 'pageview'.
'screen'tracks a screenview. Only available in mobile app trackers.

Pageview additional parameters

For hit_type pageview the following querystring parameters or additional data payload can be used for *on-site campaigns* or *on-site search*.

On-Site Campaign

The following query string or pageview payload properties can be used to identify on-site campaigns.

nametyperequireddescription
'osc_id'stringyesOn-site campaign identifier
'osc_label'stringyesOn-site campaign label

On-Site Search

The following query string or pageview payload properties can be used to identify on-site search.

nametyperequireddescription
'oss_keyword'stringyesOn-site search query / keyword.
'oss_category'stringnoOn-site search category.
'oss_total_results'integernoOn-site search total number of search results.
'oss_results_per_page'integernoOn-site search number of search results per result page.
'oss_page'integernoOn-site search page number.

Additionally, it is possible to substitute certain values before they are being submitted along with the 'pageview'. This can be done by prefixing the value with one of the following strings:

prefixdescription
'cookie:'Retrieve the value of the cookie with the given name. If the cookie is not set, the entire key/value pair is removed from the payload.
'meta:'Retrieve the content attribute of the <meta> element with the given name. If not found, the entire key/value pair is removed from the payload.
'url:'If the URL returns an HTTP 200 OK status and a JSON response, the value of the key in this response.

Examples

Sends a pageview:

// Plain pageview
osb('send', 'pageview');

// Pageview with additional information, e.g. provided by your content-management system
osb('send', 'pageview', {
    id: 12345,
    title: 'My updated title'
});

// On-site campaign using querystring parameters to current page
// ?osc_id=homepage-hero-image&osc_campaign=blackfriday2020
osb('send', 'pageview');

// Or, on-site campaign using payload
osb('send', 'pageview', {
    osc_id: 'homepage-hero-image',
    osc_label: 'blackfriday2020'
});

// On-site search
osb('send', 'pageview', {
    oss_keyword: 'nike',
    oss_category: 'sneakers',
    oss_total_results: 187,
    oss_results_per_page: 30,
    oss_page: 1
});

// Cookie payload
osb('send', 'pageview', {
    // Retrieves the value of the _ga cookie
    // Would result in ga: 'GA1.2.1234567890.1612345678'
    // If no _ga cookie is set, no payload will be sent
    ga: 'cookie:_ga'
});

// <meta> payload
osb('send', 'pageview', {
    // Retrieves the content of the <meta name="author" content="John Doe"> element
    // Would result in author: 'John Doe'
    author: 'meta:author'
});

// URL payload
osb('send', 'pageview', {
    // If some.json contains (at least) {"field":"value"}, would result in field: 'value'
    // If JSON response does not contain this key or HTTP status is not 200 OK, no payload
    // will be sent
    field: 'url:https://www.example.com/some.json'
});

// Multiple fields in payload
osb('send', 'pageview', {
    id: 123456,
    ga: 'cookie:_ga',
    author: 'meta:author'
});
// Would result in payload:
// { id: 123456, ga: 'GA1.2.1234567890.1612345678', author: 'John Doe' }
OSB.send(type: .pageview, subtype: "", dataObject: null, trackerNames: null)
OSB.send(OSBEventType.pageview, "", null, null);
osb('send', 'pageview');

Sends an event:

osb('send', 'event', {
    category: 'Video',
    action: 'start',
    label: 'Funny cat movie'
});
let dataObject = OSBSendOptions()
dataObject.category = "Video"
dataObject.action = "start"
dataObject.label = "Funny cat movie"
OSB.send(type: .event, subtype: "", dataObject: dataObject, trackerNames: null)
OSBSendOptions dataObject = new OSBSendOptions();
dataObject.category = "Video";
dataObject.action = "start";
dataObject.label = "Funny cat movie";
OSB.send(OSBEventType.event, "", dataObject, null);
osb('send', 'event', { category: 'Video', action: 'start', label: 'Funny cat movie' });

Sends the login id of the single sign-on system. The label is convenient if you want to distinguish between multiple systems.

// Single id
osb('send', 'ids', {
    key: 'login',
    value: 'abc123',
    label: 'single sign-on'
});

// Multiple ids
osb('send', 'ids', [{
    key: 'login1',
    value: 'abc123',
    label: 'single sign-on'
}, {
    key: 'login2',
    value: 'def456',
    label: 'second_system'
}]);
let dataObject = OSBSendOptions()
dataObject.key = "login"
dataObject.value = "abc123"
OSB.send(type: .ids, subtype: "", dataObject: dataObject, trackerNames: null);
OSBSendOptions dataObject = new OSBSendOptions();
dataObject.category = "login";
dataObject.action = "abc123";
dataObject.label = "single sign-on";
OSB.send(OSBEventType.ids, "", dataObject, null);
osb('send', 'ids', {
    key: 'login',
    value: 'abc123',
    label: 'single sign-on'
});

Sends a purchase (action subtype is purchase) with one product:

osb('add', 'items', {
    id: '1',
    name: 'productname1',
    category: 'productcategory1',
    price: 1.11,
    quantity: 1,
    brand: 'productbrand1',
    variant: 'produtvariant1',
    coupon: 'productcoupon1',
    position: 1
});
osb('send', 'action', 'purchase', {
    id: 'ink001',
    revenue: 29.20,
    tax: 5.07,
    shipping: 3.50,
    coupon: 'ABC123',
    affiliation: 'business shop'
});
let dataObject = OSBSendOptions()
dataObject.id = "ink001"
dataObject.revenue = 29.20
dataObject.tax = 1.21
dataObject.shipping = 3.50
dataObject.coupon = "ABC123"
dataObject.affiliation = "business shop"
OSB.send(type: .action, subtype: "purchase", dataObject: dataObject, trackerNames: null)
OSBSendOptions dataObject = new OSBSendOptions();
dataObject.id = "ink001";
dataObject.revenue = 29.20;
dataObject.tax = 1.21;
dataObject.shipping = 3.50;
dataObject.coupon = "ABC123";
dataObject.affiliation = "business shop";
OSB.send(OSBEventType.action, "purchase", dataObject, null);
osb('send', 'action', 'purchase', { id: 'ink001',
    revenue: 29.20,
    tax: (29.20/1.21),
    shipping: 3.50,
    coupon: 'ABC123',
    affiliation: 'business shop'
});

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

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

Supported in trackers: JavaScript

Usage

osb('set', name, { data... });
osb('set', name, [{ data... }, ...]);
// todo
// todo
osb('set', name, { data... });
osb('set', name, [{ data... }, ...]);

Parameters

nametyperequireddescription
'set' or 'add'stringyesName of command. 'set' to overwrite any existing value; 'add' to append to an already existing value.
namestringyesWhich record of the payload would you like to update, supported values are 'action', 'event', 'ids', 'items', 'pageview'.
{data... }JS object or JS arrayyesA plain Javascript object (or a Javascript array with plain objects) with the properties you would like to set, see below for additional notes.

Note that for 'ids' and 'items' you should always use osb('set', 'ids', [array of objects]) / osb('set', 'items', [array of objects]) and osb('add', 'ids', { single object }) / osb('add', 'items', { single object }): use 'set' to set an initial list of values, and use 'add' to add one single item to a previously existing value.

Sets one or more e-commerce items. Used when using osb('send', 'action'). The following data properties are supported for items:

item propertytyperequireddescription
categorystringnoItem or product category.
idstringyesItem id or product sku.
namestringnoItem or product name.
pricenumericnoItem or product price of single product.
quantitynumericnoItem or product quantity, default 1.
any otherstringnoany other keys (up to 50 per item) will be added as custom data key/value pairs to each item. Both key and value are assumed to be of type string.

Examples

// Single item
osb('set', 'items', [{
    id: 'sku123',
    name: 'Apple iPhone 11 Pro',
    category: 'mobile',
    price: 1234.56,
    quantity: 1
}]);

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

// Or, add an item with all the default parameters and four custom data fields
// (brand, variant, color, coupon, position) to the list of items.
// The custom data items will end up in the data key/value record of the item.
// You can add maximum 50 custom data fields for every item.
osb('set', 'items', [{
    id: 'sku123',
    name: 'Apple iPhone 11 Pro',
    category: 'mobile',
    price: 1234.56,
    quantity: 1,
    brand: 'Apple',
    variant: '256 GB',
    color: 'midnight grey'
    coupon: 'BLACKFRIDAY',
    position: 1
}]);

// Or, set two items
osb('set', 'items', [{
    id: 'sku123',
    name: 'Apple iPhone 11 Pro',
    category: 'mobile',
    price: 1234.56,
    quantity: 1,
    brand: 'Apple',
    variant: '256 GB',
    color: 'midnight grey'
    coupon: 'BLACKFRIDAY',
    position: 1
}, {
    id: 'sku345',
    name: 'Apple iPhone 11 Pro clear case',
    category: 'accessory',
    price: 12.34,
    quantity: 1,
    brand: 'No name',
    color: 'transparent'
    coupon: 'BLACKFRIDAY',
    position: 2
}]);
// todo
// todo
// See JavaScript

Sets one or multiple ID. Useful in id / profile tracking. Add this line for every ID you want to add to the list of IDs. Values can optionally be hashed (server-side).

Use these IDs only for customer / visitor related identifiers, not for page or content identifiers as these identifiers will be used to create a profile of the visitor. The id or ids given will overwrite any previously specified ids. If you want to add ids without overwriting the existing ones, use osb('add', 'ids', ...).

Supported in trackers: JavaScript, iOS, Android, ReactNative

The following data properties are supported for ids:

id propertytyperequireddescription
hashbooleannoIf true, the plain value will be hashed server-side before it will be processed further, default false.
keystringyesKey of the id, e.g. '_ga' for Google Analytics.
labelstringnoLabel if the key is not unique, e.g. the domain name: 'example.com'.
valuestringyesValue of the id, e.g. 'GA1.2.688420146.1550227175' (the Google Analytics client ID).

If the value is prefixed with cookie: then the value of the cookie is retrieved. If the value is prefixed with meta:, the content attribute of the <meta name="name" content="..."> is used. See also special payload values.

Examples

Sets one or multiple ids.

// Google Analytics
osb('set', 'ids', [{
    key: 'ga',
    value: 'GA1.2.123456789.1612345678',
    label: 'example.com'
}]);

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

// Set multiple ids in one call
osb('set', 'ids', [{
    key: '_ga',
    value: 'GA1.2.688420146.1550227175',
    label: 'example.com'
}, {
    key: 'email',
    value: 'john.doe@example.com',
    hash: true
}]);

// GA with cookie
osb('set', 'ids', [{
    key: 'ga',
    value: 'cookie:_ga'  // 'GA1.2.123456789.1612345678'
}]);

// Given <meta name="meta_name" content="meta_content">
osb('set', 'ids', [{
    key: 'meta',
    value: 'meta:meta_name'  // 'meta_content'
}]);
// todo
// todo
// See JavaScript

osb('set', 'event', ...)

Sets properties of an event. Recommended is to set these fields in the `osb('send', 'event', { event properties })' command instead. If you call this more than once, any previous values will be overwritten. Custom event data fields will be added to the hit custom data record.

Supported in trackers: JavaScript, iOS, Android, ReactNative

The following data properties are supported for events:

id propertytyperequireddescription
actionstringnoEvent category (e.g. 'click').
categorystringnoEvent category (e.g. 'Exit link').
interactionbooleannoIf true (the default) event will be used in sessionization. Also referred to as non-interaction = false. Use this to prevent prolonging the session duration with insignificant events or messing up bounce rates.
labelstringnoEvent label (e.g. 'https://www.externalsite.com').
valuenumericnoEvent value
any otherstringnocustom data key/value pairs (up to 50 per event)

Examples

// Simple event
osb('set', 'event', {
    category: 'Video',
    action: 'play',
    label: 'Funny cat video'
});

// With custom event data
osb('send', 'event', {
    category: 'YouTube winners',
    // action is merged from command above
    label: 'Grumpy cat',
    value: 30.0,
    interaction: true,
    extra_item: true,
    video_finished: false
});
// todo
// todo
// todo

osb('set', 'action', ...)

Sets properties of an action. Recommended is to set these fields in the send action command. If you call this more than once, the previous values will be overwritten. Custom data fields will be added to the hit custom data record.

The following data properties are supported for actions:

action propertytyperequireddescription
currencyCodestringnoISO 4217 currency code
discountnumericnoDiscount amount.
idstringnoOrder or transaction id.
revenuenumericnoTotal revenue amount
shippingnumericnoShipping amount.
taxnumericnoTax amount.
any otherstringnocustom data key/value pairs (up to 50 per action)

Examples

It's recommended to do this with osb('send', 'action', { action data }) instead.

// Default properties
osb('set', 'action', {
    id: 'tx1234567',
    revenue: 29.20,
    tax: 5.07,
    shipping: 3.50,
    currencyCode: 'EUR'
});

// With custom data fields coupon and affiliation
osb('set', 'action', {
    id: 'tx2345678',
    revenue: 29.20,
    tax: 5.07,
    shipping: 3.50,
    coupon: 'ABC123',
    affiliation: 'business shop'
});
// todo
// todo
// See JavaScript

osb('set', 'screen', ...)

Sets properties of a screen. Recommended is to use osb('send', 'screen', ...) instead. If you call this more than once, the previous values will be overwritten. Custom data fields will be added to the hit custom data record.

Supported in trackers: iOS, Android, ReactNative (it works in JavaScript, but it's use is uncommon)

screen propertytyperequireddescription
namestringyesName of the screen
any otherstringnocustom data key/value pairs (up to 50 per screen)

Examples

Sets action fields. Recommended is to do this with the send screen command.

// todo
// todo
// See JavaScript

osb('set', 'page', ...)

Sets all properties of a page. Recommended is to set these fields in the send page command. If you call this more than once, the previous values will be overwritten. Custom data fields will be added to the hit custom data record.

Supported in trackers: JavaScript (works in mobile trackers, but it's use is uncommon)

page propertytyperequireddescription
idstringnopage id, e.g. the unique identifier used by the Content Management System
refstringnoContains the referring URL. Default is document.referrer.
titlestringnoTitle of the page. Default is document.title.
urlstringnoContains the URL of the page. Default is location.href.
view_idstringno Contains a unique ID per page view. Can be used to count pageviews (in combination with cookie id) and to find out which events were generated on which pageviews. This is especially useful with users visiting the same site using multiple tabs in their browser.
any otherstringnoCustom data key/value pairs (up to 50 per page).

Examples

Sets page fields. Recommended is to do this with the osb('send', 'pageview', ...) command.

osb('set', 'page', {
    id: 'homepage_id_12345',
    title: 'Welcome to the homepage',
    url: 'https://www.mysite.com',
    ref: 'https://www.google.com',
    view_id: 'abcd1234ijkl'
});

// Custom data content_type
osb('set', 'page', {
    id: 'homepage_id_12345',
    title: 'Welcome to the homepage',
    url: 'https://www.mysite.com',
    ref: 'https://www.google.com',
    view_id: 'abcd1234ijkl',
    content_type: 'product detail'
});

osb('set', 'browser', ...)

Sets all properties of a browser. These are set by default in the page tag. Only use this to overwrite incorrect information. If you call this more than once, the previous values will be overwritten. Custom data fields will be added to the hit custom data record.

nametyperequireddescription
flashnumericnoWhether Flash is supported by the browser. 1 = yes, 0 = no, any other value means it can not be determined.
javanumericnoWhether Java is supported by the browser. 1 = yes, 0 = no, any other value means it can not be determined.
pdfnumericnoWhether PDF is supported by the browser. 1 = yes, 0 = no, any other value means it can not be determined.
cknumericnoWhether browser accepts first party cookies. 1 = yes, 0 = no, any other value means it can not be determined.
swnumericnoScreen width in pixels.
shnumericnoScreen height in pixels.
iwnumericnoInner width of the visible part of the browser in pixels.
ihnumericnoInner height of the visible part of the browser in pixels.
tznumericnoDifference to UTC timezone in minutes, e.g. timezone Central European time (CET) is 60, Central European Summer Time (CEST) is 120.
any otherstringnoCustom data key/value pairs (up to 50 per page).

Supported in trackers: JavaScript (native support with mobile trackers)

Examples

osb('set', 'browser', {
    iw: 300
});

// With customer data
osb('set', 'browser', {
    iw: 300,
    screen_orientation: 'sideways'
});

osb('set', ...)

Sets all properties in the root of the payload. These are set by default by the page tag. Only use this if you know what you are doing. If you call this more than once, the previous values will be overwritten. Custom data fields will be added to the hit custom data record.

Supported in trackers: JavaScript (native support with mobile trackers)

Usage

osb('set', { object } or [ array ]);
osb('set', [{ object }, ... ]);

Parameters

object propertytyperequireddescription
duidstringnoOverwrite the domain user id with your own.
any otherstringnoCustom data key/value pairs (up to 50 per page).

osb('config', ...)

Web specific

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: 1 }).

See osb('create', ...) for all options.

App specific

Let's you set configuration options of trackers, like tracker URL's. We recommend to set these when you create the tracker, but there are always some cases when this comes in handy. If you call this more than once, the previous values will be overwritten.

Supported in trackers: iOS, Android, ReactNative

Parameters

  • config (required) - fixed
  • dataObject (required) - Can hold the following properties:
    • siteId (string) - Site ID, to distinguish which site send the hit. Especially useful if your site spans more then one domain or you want to categorize hits of the same domain.
    • trackerUrl (string) - Set's the trackerUrl. Default is https://g.ab21.xyz
    • ipSettings (int) - 0 (default) = IP address will be saved, 1 = Last octet of the IP address will be remove before storage (but used in internal memory matching), 2 = IP address will be saved encrypted, 3 = IP address will not be saved
    • dispatchInterval (integer) - Time in seconds that measurements will be send. Default is 2 minutes. If the interval is 0 or negative, automatic dispatching is switched off and manual (programmatic) dispatching is needed.
    • sendHitsInBackground (boolean) - If set to true (YES), the hits will also be send when the app is in the background.
    • allowIDFACollection (boolean) - If set to true (YES), the ID for Advertisers (IDFA) can be collected

osb('get', ...)

Returns the content of the payload of a particular tracker.

Supported in trackers: JavaScript (native support with mobile trackers)

Usage

osb('get', callback);
osb('get', name, callback);
parameter nametyperequireddescription
'get'stringyesName of command.
namestringnoName of payload you'd like to see, leave empty for everything.
callbackJS functionyesCallback function(payload) that receives the payload.

Examples

// Return entire payload
osb('get', function(payload) {
    console.log(JSON.stringify(payload));
}):

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

osb('remove', ...)

Removes data.

Supported in trackers: JavaScript

Usage

osb('set', 'ids', { ... });
osb('remove', 'ids');
// No data for 'ids'

Parameters

parameter nametyperequireddescription
'remove'stringyesName of command.
trackerNamestringnoName of tracker to remove, leave empty to remove all trackers.

Examples

// Remove all trackers
osb('remove');

// Remove second tracker
osb('remove', 'secondTracker');

osb('reset')

Removes all data.

Supported in trackers: JavaScript

Usage

osb('reset');

Parameters

parameter nametyperequireddescription
'reset'stringyesName of command.

Examples

osb('set', 'ids', { ... });
osb('reset');
// No data for 'ids'

osb('show')

Returns the payload and config of all trackers as a JSON object. Useful for debugging.

Supported in trackers: JavaScript (native support with mobile trackers)

Usage

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

Parameters

nametyperequireddescription
'show'stringyesName of command.
callbackJS functionNoCallback with the response with all the data. If not specified will output the response to the browser's console.

Examples

osb('show', function(response) {
    console.log('Version =', response.version);
});

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.

Based upon external (batch) processes these profiles can be created and updated using information gathered while the user is browsing the website.
parameter nametyperequireddescription
'profile'stringyesName of command.
callbackJS functionnoCallback function that will be called with the cross-domain user id and public profile of the visitor (an array of strings).

Usage

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

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

External / central cookie domain
If the user has given consent, continue on the same page, otherwise, redirect the browser toa 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.
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.

External / central cookie domain

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

Usage

Parameters

parameter nametyperequireddescription
'consent'stringyesName of command.
{ consent options }JS objectyesOptions to configure the consent page, see below.

Consent options for external cookie domain

consent optiontyperequireddescription
callbackJS functionnoCallback function(consent, cduid) called after the redirect to the original page where consent was requested. This callback is fired both for consent accepted and not accepted.
cduidNamestringnoName of querystring parameter and first-party cookie name for cross-domain user-id added to the URL of the original page where consent was requested, default 'cduid'.
consentNamestringnoName of querystring parameter and first-party cookie name that stores which consent the user has given consent, default 'consent'.
consentUrlstringyesURL to redirect browser to page where user gives consent, e.g. 'https://privacy.example.com'.

Example

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 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 below videos.

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 show is added, the cookie bar becomes visible).
    #cookiebar { display: none; }
    #cookiebar.show { display: block; }
  • The cookie bar contains an <a> or <button> element with class="allow" the user can click to allow consent.
  • Optionally, the cookie bar als contains a <a> or <button> with class="deny" the user can trigger to deny all consent.

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 deny buttons.

When either button is clicked a first-party cookie is set with the given consent, and the cookie bar is hidden again.

Consent options for cookie bar

consent optiontyperequireddescription
consentIdstringyesHTML id of the cookie bar HTML element, e.g. 'cookiebar'.
consentNamestringnoName of first-party cookie used to store consent, default 'consent'.

Example

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

<div id="cookiebar" class="fade">
    <div class="container">
        <span>
            Lorem ipsum dolor sit amet
            <a href="/link/to/privacy">privacy statement</a>.
        </span>
        <button class="btn btn-primary allow">OK, give consent</button>
    </div>
</div>

And the following CSS:

#cookiebar {
  color: #fff;
  background-color: #000;
  padding: 15px;
  position: fixed;
  bottom: 0;
  width: 100%;
  z-index: 20;
}
#cookiebar > div {
  display: flex;
  align-items: center;
}
#cookiebar > div span {
  flex: 1 1 auto;
}
#cookiebar > div button {
  flex: 0 0 auto;
}

And the following javascript:

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

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

This website uses cookies to ensure you get the best personal experience.