LT.js Detailed Reference Guide

OVERVIEW

This page provides reference details for all available Lotame Lightning Tag functionality. It assumes you have already completed the pre-requisites and steps in the basic implementation on your website.


Lightning Tag Setup Object

As configured in the basic implementation, the lotameTagInput object has two main sub-objects that permit various options to be set:

      var lotameTagInput = {
          data: {},
          config: {}
      };

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

config Object

The config object has the following possible parameters:

Parameter Description Type Required? Default
clientId Your Lotame Client ID int YES N/A
onProfileReady Callback function called once Lotame targeting returns.  function (profile) NO {}
audienceLocalStorage Determines whether to write audiences to the browser's localStorage and what the name of the key is. Discussed further below in the Local Storage section boolean -OR- string NO false
onTagReady Callback function called once Lotame Lightning Tag object is loaded and ready to be used. function (namespace) NO {}
autoRun Determines whether Lotame Lightning Tag runs on load. If set to false, your website needs to explicitly call the page() method listed on this page to send data and retrieve targeting audiences. boolean NO true
gpc Tell Lotame if the Global Privacy Control should be enforced. Only set to 1 if the user has an active GPC flag so Lotame can disable processing on the page. boolean NO 0

onProfileReady Callback

As noted above in the config object created at script setup, you may specify the callback method onProfileReady to fire after targeting completes. This work happens asynchronously, so the callback is fired when the targeting work is completed.

When fired, the callback passes a profile object with the following methods:

Method Name Type Parameters Description
getProfileId() String n/a The id of the profile associated with the browser
getPanorama() Object n/a An object with two methods:
1. getId() - returns the String Panorama ID™ linked to the Profile ID
2. getIdType() - returns a String that is either 'panoIndiv' or 'panoDevice'. See  the below getPanorama() method details for further information.
getThirdParty(namespace) String namespace - required, string The Third Party id associated to the Profile id. The namespace will be provided by Lotame
getAudienceString( [delimiter=','], [limit]) String 1. delimiter - optional, string, defaults to comma.
2. limit - optional, integer, defaults to no limit
Delimited string of audience ids. The default, i.e. no arguments, is comma delimited with no limit. Example: "1,2"
getAudiences([limit]) Array limit - optional, integer, defaults to no limit Array of audience ids as integers. Example: [123,789]

Note: If you have implemented the TCF 2.2 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.2 implementations here.

audienceLocalStorage Parameter

If this parameter is set to other than "false" then when targeting is completed, the audiences are written out to the browser's localStorage.

Value Result
false This is the default, and audiences are not written to browser localStorage.
true Lightning Tag writes audiences to localStorage under the key lotame_CLIENT_ID_auds (where CLIENT_ID is your Lotame clientId)
'string' Passing a string tells Lightning Tag to write the audiences to localStorage under the key of the string you pass. (i.e. audienceLocalStorage: 'myLotameAudiences')

Audiences are written out as a string of audience IDs. Example: "123,789"

onTagReady Callback

You may pass a function to the onTagReady callback that will fire when the Lotame Lightning Tag interface is ready to be used. This callback firing is also an indication that the collect() and page() methods described below are ready to be used.

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.

autoRun Parameter

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 you to fire data collection and targeting by calling the collect() and/or 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 Spherical Platform for use in targeting or other features. 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.

Name Description Example
behaviorIds Existing behavior ID's from your Platform account that are owned by the same client supplied in the tag
{
  behaviorIds: [1,2,3],
},

 

behaviors New or existing behaviors as type/value pairs, where the type is a supported type in the Platform, respectively
'int' = interest
'med' = media
'act' = action
'seg' = custom segment
{
  behaviors: {
    int: ['site section: news', 'traffic: mysite.com'],
    med: ['article category : politics']
  },
},

 

ruleBuilder Custom keys and values to be used for the Rule Builder tool within the Platform
{
  ruleBuilder: {
    article_tags: ['food', 'in the news'],
    article_title: ['Todays Headline'],
    article_author: ['Bob Roberts'],
  },
},

 

thirdParty An identifier to associate with the current browser, typically to enable server side data transfer. Your Lotame representative will provide the namespace value as necessary for your implementation.
{
  thirdParty: {
    namespace: 'FAKE',
    value: '123456789101112131415'
  },
},

 

Lightning Tag Methods

collect()

The collect() method is available to pass data to the Spherical Platform 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 earlier in this article.

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 Platform. 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 Platform.
  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.

setIdentity()

The setIdentity() method is used to pass user-identifiable info directly to Lotame for targeting. Currently, email is the only supported identifier type with two variations.

Note: We encrypt and store all values passed to setIdentity() in our Identity Vault to ensure security-first handling of your customer information.

For all Identity types, in the <head> of your page, include the below to speed up HTTP & DNS overhead time of the setIdentity() call.

<link rel="preconnect" href="https://bcp.st.crwdcntrl.net">
<link rel="dns-prefetch" href="https://bcp.st.crwdcntrl.net">
<link rel="preconnect" href="https://c.st.ltmsphrcl.net">
<link rel="dns-prefetch" href="https://c.st.ltmsphrcl.net">

Plain-Text Email

This is a plain-text email address and uses the EMAIL type.

window.lotame_<lotameClientId>.cmd.push(function() {
  window.lotame_<lotameClientId>.setIdentity(
    { id: 'username@domain.com', type: 'EMAIL'}
  );
});

Note: the email being passed should be whitespace trimmed and set to lowercase before submission to follow industry best practices.

SHA-256 Encoded Email

This is the SHA-256 encoded email, noted by the type of EMAIL_SHA256.

window.lotame_<lotameClientId>.cmd.push(function() {
  window.lotame_<lotameClientId>.setIdentity(
    { id: '028101f2faf2d8ce1c33e6e9226d6703a72a98e72c09c08021142ceb3580a173', type: 'EMAIL_SHA256'}
  );
});

Note: The email being passed should be whitespace trimmed and set to lowercase before SHA-256 encoding and submission Lotame. This maximizes the match rate by following industry practices.

getPanorama()

getPanorama() returns an object with two methods; getId() and getIdType(). The getId() returns the Lotame Panorama ID as a string. The getIdType() returns the type of Panorama ID as a string and will be either 'panoIndiv' or 'panoDevice'.

var PanoObject = window.lotame_<lotameClientId>.getPanorama();
var PanoID = PanoObject.getId();
var PanoIDType = PanoObject.getIdType();

The ID Type value panoIndiv is to denote Individual-Based Panorama ID that connects multiple devices (desktop, mobile, CTV, etc) to a single individiual persona. panoDevice is to note Device-Based Panorama ID that connects IDs to a single device/browser. If Lotame cannot resolve a browser to a panoIndiv, it will attempt to assign it to a panoDevice ID.

Note - Lotame will return an UNKNOWN ID type if a Panorama ID value cannot be returned. 

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 audience IDs. Example: ["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 the browser's 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 Platform. 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 Lotame Lightning Tag User Consent Guide describes the returnData object provided to the callback function.