doc

API

Installation

Page tracking

Unit tracking

API unit

The functions trackById, trackByNode, findUnit, findUnits, and withUnits all return an API unit object. These functions are all available on these objects.

Page tracking

startTracking (callback)

This is where it all begins. This function must always be called to start any kind of tracking. You pass it a callback, which will be called with api as argument. You can call all page and unit tracking functions described below on api.

window.burtApi.startTracking(function(api) {
  // use api
});

stopTracking ()

This function stops the currently active tracking. Its main use case is to stop tracking on single page app (SPA) sites as JavaScript’s are not reloaded for each pageview.

For more information about how to use the Burt script for SPA sites, see the single page app docs.

window.burtApi.startTracking(function() { ... });

// ...

window.burtApi.stopTracking();

setTrackingKey (key, name)

This function identifies the site, it must always be called.

window.burtApi.startTracking(function(api) {
  api.setTrackingKey('COMP7G823SXY', 'your-site-name');
});

See tracking-key for the details about the arguments.

setDomain (domain)

Setting the domain is optional, but highly recommended. The script will likely figure out the domain automatically, but in some cases this is not possible. So to make sure the domain always is correct, use this function to specify the top domain. Here are a few examples:

  • If the script runs on yoursite.com, the domain should be yoursite.com
  • If the script runs on blog.yoursite.com, the domain should be yoursite.com
  • If the script runs on person.blog.yoursite.co.uk, the domain should be yoursite.co.uk
  • If the script runs on www.yoursite.co.uk, the domain should be yoursite.co.uk

Use it like this:

window.burtApi.startTracking(function(api) {
  api.setTrackingKey('COMP7G823SXY', 'your-site-name');
  api.setDomain('yoursite.com');
});

setPageUrl (url)

Sets the URL of the current page view. This is optional as the script does this automatically when this function is not called.

This function is useful when for example the URL contains exotic characters such as åäö.

window.burtApi.startTracking(function(api) {
  api.setTrackingKey('COMP7G823SXY', 'your-site-name');
  api.setPageUrl(decodeURIComponent(window.location.href).replace(/[åäö]/g, function(c) {
    return { å: 'a', ä: 'a', ö: 'o' }[c];
  }));
});

setCategory (category, subCategory)

Set the category for this page.

window.burtApi.startTracking(function(api) {
  api.setCategory('article', 'sports');
});

This function can also be called before, but not after, #startTracking is called, but not after, for example:

window.burtApi.setCategory('article', 'sports');

// ...

window.burtApi.startTracking(function(api) {
  api.setTrackingKey('COMP7G823SXY', 'your-site-name');
  api.setDomain('yoursite.com');
});

addCloudKey (cloudKey)

This function adds a cloud key on the page level.

window.burtApi.startTracking(function(api) {
  api.addCloudKey('XXXXXXXXXXXX');
  api.addCloudKey('YYYYYYYYYYYY');
});

connect (scope, name, value)

Add a connection on page level.

window.burtApi.startTracking(function(api) {
  api.connect('burt.author', 'author-id', '1234');
});

or

window.burtApi.connect('burt.author', 'author-id', '1234');

See macros documentation for available scope macros.

annotate (scope, name, value)

Add an annotation on page level.

window.burtApi.startTracking(function(api) {
  api.annotate('burt.author', 'author', 'Joe');
});

or

window.burtApi.annotate('burt.author', 'author', 'Joe');

See macros documentation for available scope macros.

setDemographicsProvider (name)

To integrate demographics data with your campaign reporting you must set the demographics provider to use with this function call.

window.burtApi.startTracking(function(api) {
  api.setDemographicsProvider('cint');
});

Burt currently has support for a number of different demographics providers. Please contact your sales representative for more information.

withUserSegments (callback)

Deprecated. Use burtApi.profiles.getSegments instead.

Sync user segments and callback when done. The segments are cached locally for 24 hours.

window.burtApi.withUserSegments(function(segments) {
  window.myAdServer.targetingSegments = segments;
});

Unit tracking

startUnitTracking ()

When you call this function the agent will find and start tracking all DIV tags with class burt-unit, once the document is ready.

window.burtApi.startTracking(function(api) {
  api.startUnitTracking();
});

For each unit the agent will look for these data attributes and use their values:

  • data-name - Name of the unit (required)
  • data-type - Type of the unit, one of
    • ad - Track the unit as an ad (default)
    • area - Track the unit as an area. Can be images, text, videos, etc.
  • data-filled - Set to true if manually filling an ad unit
  • data-preview-url - Set a preview url for the unit
  • data-cloud-keys - Associate cloud keys with the unit (comma separated)
  • data-connect-scope - See unit connect scope
  • data-connect-name - See unit connect name
  • data-connect-value - See unit connect value
  • data-connect-values - See unit connect values

For example:

<div class="burt-unit" data-name="topbanner">
  ...
</div>

A unit can also complemented with additional information using metadata tags (span tag with class burt-unit-metadata).

<div class="burt-unit" data-name="my-unit">
  ...

  <span class="burt-unit-metadata" data-cloud-keys="XXXXXXXXXXXX"></span>
  <span class="burt-unit-metadata" data-cloud-keys="YYYYYYYYYYYY, ZZZZZZZZZZZZ"></span>
  <span class="burt-unit-metadata" data-type="area"></span>
  <span class="burt-unit-metadata" data-filled="true" data-preview-url="http://url-to-preview"></span>
</div>

trackById (id, meta)

Track unit with id using meta as metadata. meta needs to contain at least name, and can optionally contain the other unit metadata attributes specified in the documentation for startUnitTracking.

This function returns an API unit object.

window.burtApi.startTracking(function(api) {
  unit = api.trackById('some-id', { name: 'some-name' });
});

or

unit = window.burtApi.trackById('some-id', { name: 'some-name' });

The script will search for a node with corresponding id and start the tracking once the document is ready.

trackByNode (node, meta)

Track unit in node (a DOM node) using meta as metadata. meta needs to contain at least name, and can optionally contain the other unit metadata attributes specified in the documentation for startUnitTracking.

window.burtApi.startTracking(function(api) {
  unit = api.trackByNode(someNode, { name: 'some-name' });
});

or

unit = window.burtApi.trackById(someNode, { name: 'some-name' });

withUnits ([matchers = []], callback)

This function will invoke the callback function for every unit currently being tracked, and for any new units added during the lifetime of the pageview. Restarted units will not be callbacked.

Only units that match any of matchers will result in a callback.

There are three similar functions to this, namely withFilledUnits, findUnits and findUnit. While this function and withFilledUnits asynchronously callbacks new units over time, findUnits and findUnit will return the currently available units immediately, if any.

All units

If matchers is not present, the function will be called once for each unit.

window.burtApi.startTracking(function(api) {
  api.withUnits(function(unit) {
    adCount++;
  });
});

Name

If a matcher is a string, the function will be called once for each unit with that name.

window.burtApi.startTracking(function(api) {
  api.withUnits('topbanner', 'skyskraper', function(unit) {
    unit.annotate('burt.campaign', 'campaign-id', campaignIds[unit.getName()]);
  });
});

Id

If a matcher is a string that starts with #, the function will be called once for each unit with that ID.

This code:

window.burtApi.startTracking(function(api) {
  api.withUnits('#topbanner', '#skyscraper', function(unit) {
    unit.annotate('burt.campaign', 'campaign-id', campaignIds[unit.getName()]);
  });
});

will match these units:

<div id="topbanner" class="burt-unit" data-name="topbanner">
...
</div>

<div id="skyscraper" class="burt-unit" data-name="skyscraper">
...
</div>

Class

If a matcher is a string that starts with ., the function will be called once for each unit with that class.

This code:

window.burtApi.startTracking(function(api) {
  api.withUnits('.ad', function(unit) {
    unit.annotate('burt.campaign', 'campaign-id', campaignIds[unit.getName()]);
  });
});

will match these units:

<div class="ad" data-name="topbanner">
...
</div>

<div class="ad" data-name="skyscraper">
...
</div>

DOM node

If a matcher is a DOM node, the function will be called with any unit corresponding to that DOM node.

window.burtApi.startTracking(function(api) {
  window.topbannerNode = document.getElementById('topbanner');
  api.trackByNode(window.topbannerNode, { name: 'topbanner' });
});

// ...

window.burtApi.withUnits(window.topbannerNode, function(unit) {
  unit.annotate('burt.campaign', 'campaign-id', campaignIds[unit.getName()]);
});

Regex

If a matcher is a regex, the function will be called once for each unit whose name matches.

window.burtApi.startTracking(function(api) {
  api.withUnits(/Left-\d/, function(unit) {
    unit.annotate('column-report', 'left', '1');
  });

  api.withUnits(/Middle-\d/, function(unit) {
    unit.annotate('column-report', 'middle', '1');
  });

  api.withUnits(/Right-\d/, function(unit) {
    unit.annotate('column-report', 'right', '1');
  });
});

Combination

All of these different matchers can also be mixed:

window.burtApi.startTracking(function(api) {
  api.withUnits('.ad', '#topbanner', 'skyskraper', /Right-\d/, node, function(unit) {
    // ...
  });
});

withFilledUnits (matchers = [])

This function works like withUnits, except units will only be emitted once they are filled. Unlike withUnits, restarted units will be callbacked when they are filled.

findUnits (matchers = [])

Find units matching any of the matchers. The possible matchers are documented under the withUnits function.

This function returns an array with all found units. If no units are found, an empty array is returned.

Since functions such as trackById and startUnitTracking do not actually start the tracking of nodes until the DOM ready event has occurred, this function may not return any units prior to the time of that event.

findUnit (matchers = [])

This function works like findUnits, except it’s only the first matching unit that is returned.

If no unit if found, then null is returned.

API unit

fill ()

A unit of type ad becomes filled when one or more images or flash objects are detected and visible. area units are always filled. For other types of media nodes, the unit may have to be filled manually, for example when using creatives with css background or HTML5 video tags.

window.burtApi.withUnits('name', function(unit) {
  unit.fill()
});

isFilled ()</h3>

Returns a boolean stating if the unit is filled or not.

window.burtApi.withUnits('name', function(unit) {
  if (unit.isFilled()) {
    // Do something
  }
});

setPreviewUrl (url)

Sets a preview url for the unit. This is a shorthand method for sending a burt.creative connection

window.burtApi.withUnits('name', function(unit) {
  unit.setPreviewUrl('http://some-domain/image.png')
});

connect (scope, name, value)

Add a unit level connection.

window.burtApi.startTracking(function(api) {
  unit = api.trackByNode(someNode, { name: 'some-name' });
  unit.connect('burt.campaign', 'campaign-id', 'id');
});

or

unit = window.burtApi.trackByNode(someNode, { name: 'some-name' });
unit.connect('burt.campaign', 'campaign-id', 'id');

See macros documentation for available scope macros.

annotate (scope, name, value)

Add a unit level annotation.

window.burtApi.startTracking(function(api) {
  unit = api.trackByNode(someNode, { name: 'some-name' });
  unit.annotate('burt.demographics', 'sex', 'male');
  unit.annotate('burt.demographics', 'age', '38');
});

or

unit = window.burtApi.trackByNode(someNode, { name: 'some-name' });
unit.annotate('burt.demographics', 'sex', 'male');
unit.annotate('burt.demographics', 'age', '38');

See macros documentation for available scope macros.

getMeta ()

Returns the unit meta data, such as name, type, cloud keys, etc.

window.burtApi.startTracking(function(api) {
  unit = api.trackByNode(someNode, {
    name: 'some-name',
    type: 'area'
  });
  console.log(unit.getMeta()); // => { name: 'some-name', type: 'area' }
});

getName ()

Returns the unit name, which is provided as meta information.

window.burtApi.startTracking(function(api) {
  unit = api.trackByNode(someNode, {
    name: 'some-name'
  });
  console.log(unit.getName()); // => 'some-name'
});

getNode ()

Returns the unit dom node. This is the top level dom node that is being tracked.

window.burtApi.startTracking(function(api) {
  unit = api.trackByNode(someNode, {
    name: 'some-name'
  });
  console.log(unit.getNode()); // => someNode
});

restart (meta = {})

Note: This function has been deprecated and will be removed in future versions. Use the #destroy function and create a new unit instead.

Restart unit. This function is useful when an ad is replaced on the same page view.

window.unit = window.burtApi.trackByNode(someNode, {
  name: 'some-name',
  type: 'area'
});

// ...

window.unit.restart();

// or

window.unit.restart({name: 'new-name', type: 'ad'});

destroy ()

Stop tracking the unit and destroy it. The unit will no longer be found via the unit finding methods, e.g. findUnits.

This function is useful when an ad or area is removed and it is desired to stop measuring the unit before the end of the page view.

For example, if an ad on the page is swapped for a new creative during a page view and it is desired that the two ad units should be measured separately, call #destroy to stop and remove the old unit, then create a new unit that tracks the new ad via trackByNode or trackById. The example below illustrates an example to handle this.

window.trackUnit = function() {
  window.unit = window.burtApi.trackByNode(someNode, {
    name: 'some-name'
  });
};
window.trackUnit();

// Ad is swapped, destroy and set up the unit again

window.unit.destroy();
window.trackUnit();



Back to Top