Detailed Reference Guide

This page provides reference details for all available Lotame Lightning Tag functionality. If you need any other assistance, please reach out to Lotame by emailing support@lotame.com.

Platform Setup

Before implementing the Lotame Lightning Tag on your site, there is setup that needs to be completed inside the Lotame Platform as described on Pre-Implementation Setup Tasks

Lightning Tag Setup

Setup of the Lotame Lightning Tag javascript on your website involves an input object that gets passed to an initialization function that prepares a window namespace on your page for the javascript tag itself. The basic setup looks like the below:

<script>
  ! function() {
    var lotameClientId = '<lotameClientId>';
    var lotameTagInput = {
        data: {},
        config: {}
    };

    // Lotame initialization
    var lotameConfig = lotameTagInput.config || {};
    var namespace = window['lotame_' + lotameClientId] = {};
    namespace.config = lotameConfig;
    namespace.data = lotameTagInput.data || {};
    namespace.cmd = namespace.cmd || [];
  } ();
</script>
<script async src="https://tags.crwdcntrl.net/lt/c/<lotameClientId>/lt.min.js"></script>

The details of the input data and config options are below.

Config Object

The config object in the Lotame Lightning Tag input has the following possible parameters:

Audience Callback

As noted above in the config object created at script setup, there is a callback method named onProfileReady that is called after targeting completes. This work happens asynchronously, so the callback is fired when the targeting work is completed.

When fired, the callback is passed a profile object that has the following functionality.

Note: if you have implemented the TCF 2.0 framework on your site you must enable Lotame as a vendor in your CMP in order for Lotame to return a Panorama ID. Learn more about TCF 2.0 implementations here.

Local Storage Usage

As noted above in the config object created at script setup, there is a parameter named audienceLocalStorage. If passed, when targeting is completed, the audiences are written out to the browser's localStorage.

Audiences are written out as a string of comma-delimited targeting codes or audience IDs, based on your established tag settings. Example: "aud1,aud2" or "123,789"

Tag Ready Callback

The onTagReady callback fires when the Lotame Lightning Tag interface is ready to be used. Which includes below described methods such as collect and page.

onTagReady: function(namespace) {
  // Lightning Tag script is ready to be used
},

This event does not confirm audiences are available, that is the onProfileReady callback described above in this document.

Auto Run Flag

The autoRun boolean is defaulted true and runs the Lotame data collection and targeting retrieval immediately after the script is loaded. If set to false control is left to the client's website to fire data collection and targeting using the collect() and page() methods described later on this document.

A use-case for setting this to false is if you want to get the customer's consent before enabling the data collection and targeting to run.

Data Object

The data object is used to pass first party-data to the Lotame DMP for use in targeting or other features of the Lotame platform. The object is optionally passed at setup time in the tag input function. It can also be passed post-page load in the collect({data}) or in the page({data}) methods that are described further down this page.

{
  behaviorIds: [1,2,3],
},

{
  behaviors: {
    int: ['site section: news', 'traffic: mysite.com'],
    med: ['article category : politics']
  },
},

{
  ruleBuilder: {
    article_tags: ['food', 'in the news'],
    article_title: ['Todays Headline'],
    article_author: ['Bob Roberts'],
  },
},

{
  thirdParty: {
    namespace: 'FAKE',
    value: '123456789101112131415'
  },
},

{
  sha256email: 'lowercase_no_whitespace_sha256_hashed_email'
},

Lightning Tag Methods

collect()

The collect() method is available to pass data to your Lotame DMP after the Lotame javascript is loaded. An example use-case is tracking events such as user interaction with a video player on your site.

window.lotame_<lotameClientId>.cmd.push(function() {
  window.lotame_<lotameClientId>.collect({data});
});

The data object parameters are described in the Data Collection page.

Calls to this method are queued up. Every 1 second (and also at the page.unload() event) the Lightning Tag flushes the queue and sends the batch of data objects to the DMP. This functionality allows your website to make calls to this method and not need to wait on a response.

page()

The page() method allows you to re-run your targeting call without reloading the Lotame Lightning Tag script. A use-case is a single-page site which as a user scrolls, new articles pop up. Your site can now pass in new {data} elements that describe this new article the user is now viewing and then retrieve updated audiences based on that new information.

window.lotame_<lotameClientId>.cmd.push(function() {
  window.lotame_<lotameClientId>.page({data});
});

Please note that {data} is an optional parameter to the page() method.

The following tasks occur when page() is called:

1. The data queue described above in the collect() method flushes, including any new data passed on this page() call.
2. Your Optimus rules execute, pulling in new values based on the page contents.
3. A new page view registers in your Lotame DMP.
4. Targeting executes, and audiences return on either the callback method or localStorage (or both) depending on how you configured audience extraction on your site.

Please note that the page() method fully re-runs all Lightning Tag processing including re-running Optimus rules. If all you are looking to do is send new data as more of the page is loaded and visible, please use the collect() method. That method is asynchronous and therefore much faster for your site.

getAudiences()

getAudiences([limit]) is a shortcut that retrieves the targeted audience array from localStorage. It optionally accepts a limit parameter that will restrict the number of audiences returned.

window.lotame_<lotameClientId>.getAudiences();

Audiences will be returned as an array of targeting codes or audience IDs, based on your established tag settings. Example: ["aud1","aud2"] or ["123","789"]. If you would like to limit the number of audiences returned, send in a limit like getAudiences(100).

The audienceLocalStorage parameter must be set on the Lotame Lightning Tag config object. If it is not, the response to getAudiences will be an empty array and an error message will be written to console log.

setConsent()

The Lotame Lightning Tag provides a method setConsent to submit consent signals to the Lotame Consent API for enforcement within the Lotame DMP. Once you've collected the appropriate consent from your customer within your privacy user experience, submit the appropriate signals as follows:

function setConsentCb(returnData) {
  console.log('LT.JS: Placeholder for setConsentCb logic');
}

var customerConsents = {
  analytics: true,
  crossdevice: true,
  datasharing: true,
  targeting: true
};

window.lotame_<lotameClientId>.cmd.push(function() {
  window.lotame_<lotameClientId>.setConsent(setConsentCb, <lotameConsentClientId>, customerConsents);
});

The returnData object provided to the callback is fully described in User Consent Guide.