
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 submitting a Support ticket form through this link.
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:
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:
Parameter | Name | Description | Type | Required? | Default |
clientId | Your Lotame Client ID | int |
YES | Always | N/A |
onProfileReady | Callback function called once Lotame targeting returns. Discussed further below in the Callback section of this page | function (profile) |
NO | Implement when using client-side targeting | {} |
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 | Implement when using client-side targeting | false |
onTagReady | Callback function called once Lotame Lightning Tag object is loaded and ready to be used. | function (namespace) |
NO | In most cases, use the asynchronous command queue instead | {} |
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 | Set to true unless you have logic that must fire before Lotame's code runs and you have written the logic to call the page() method manually |
true |
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.
Method Name | Return Type | Parameters | Description |
getProfileId() |
String | n/a | The id of the profile associated with the browser |
getPanoramaId() |
String or NULL | n/a | The Panorama ID ™ linked to the Profile ID |
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.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.
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"
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
.
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 Platform 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.
Name | Description | Example |
behaviorIds | Existing behavior ID's from your Platform account that are owned by the same client supplied in the tag |
|
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 |
|
ruleBuilder | Custom keys and values to be used for the Rule Builder tool within the Platform |
|
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. |
|
Lightning Tag Methods
collect()
The collect()
method is available to pass data to your Lotame 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.
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 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.
Please note that {data}
is an optional parameter to the page()
method.
The following tasks occur when page()
is called:
- The data queue described above in the
collect()
method flushes, including any new data passed on thispage()
call. - Your Optimus rules execute, pulling in new values based on the page contents.
- A new page view registers in your Lotame Platform.
- 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 thecollect()
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 use in targeting. As of this writing, email is the only supported identifier type.
This functionality is part of our Lotame Spherical offering. If you would like to explore using it, please reach out to your Lotame account representative for more information and details.
Note: The email must be provided as plain-text, and not hashed. We encrypt and store it in our Identity Vault to ensure security-first handling of your customer information.
Also, in the <head> of your page, include the below to speed up HTTP & DNS overhead time of the setIdentity() call.
Note: the email being passed should be whitespace trimmed and set to lowercase before submission to follow industry best practices.
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.
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 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:
The returnData
object provided to the callback is fully described in User Consent Guide.