User ID Syncing with Sync.js - Detailed Reference Guide

updated 8 mths ago

OVERVIEW

This page provides reference details for all available Lotame Sync.js Tag functionality. If you need further assistance, please get in touch with Lotame by submitting a Support ticket form through this link.

Sync.js Tag Setup

The Lotame Sync Tag javascript setup 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 following:

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

  <script>
  ! function() {
    // Callback that will be triggered after each call to sync()
    // and let you have access to the profile and/or panorama ids
    var syncCallback = function (profile) {

        // Get the profile id
        var profileId = profile.getProfileId();

        // Get the panorama id
        var panoramaId = profile.getPanorama().getId();
    };


    var lotameClientId = '<lotameClientId>';
    var lotameTagInput = {
        config: {
            onProfileReady: syncCallback
        }
    };

    var lotameDataInput = {
        thirdParty: {
            namespace: 'FAKE',
            value: '123456789101112131415'
        }
    };

    // Lotame initialization
    var lotameConfig = lotameTagInput.config || {};
    var namespace = window['lotame_sync_' + lotameClientId] = {};
    namespace.config = lotameConfig;
    namespace.data = lotameDataInput;
    namespace.cmd = namespace.cmd || [];
  } ();
</script>

<!-- Pull the sync.js script itself in -->
<script async src="https://tags.crwdcntrl.net/lt/c/<lotameClientId>/sync.min.js"></script>

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

Config Object Details

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

Parameter	Description	Type	Required?	Default
onProfileReady	This callback function is called every time a sync() call completes.	function (profile)	No	{}
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

Callback Profile Object Details

The onProfileReady callback fires after the sync call return and provides a profile object with the following methods.

Method Name	Return Type	Parameters	Description
getProfileId()	String	n/a	The id of the profile associated with the browser
getPanorama()	String or NULL	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.

Data Object Details

The data object provides a way to pass in a Third Party ID to Lotame. However, it is not required and can either be left empty or not provided.

Name	Description	Example
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' } }`

Sync.js Tag Methods

The following methods are also available on the window.lotame_sync_<lotameClientId> namespace is available any time after the main script block is defined. Whenever you make calls against the namespace, you should wrap them in a call to window.namespace.cmd.push(), as that allows your code to execute asynchronously as soon as our tag finishes loading on your page.

Using the below methods directly is a secondary option to retrieve the values inside the callback function. Use whichever scenario works best for your codebase.

sync()

The Sync call is what fires to pass your identifiers to Lotame and fires the onProfileReady callback.

<!-- Initiate the sync call. When it completes, it will trigger syncCallback with a profile object -->
<script>
    window.lotame_sync_<lotameClientId>.cmd.push(function() {
        window.lotame_sync_<lotameClientId>.sync();
    });
</script>

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

window.lotame_sync_<lotameClientId>.cmd.push(function() {
  var PanoObject = window.lotame_sync_<lotameClientId>.getPanorama();
  var PanoID = PanoObject.getId();
  var PanoIDType = PanoObject.getIdType();
}

The ID Type value panoIndiv denotes an Individual-Based Panorama ID that connects multiple devices (desktop, mobile, CTV, etc) to a single individual 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 - Depending on what other Lotame tech is on the page, there is a chance Lotame will return an UNKNOWN ID type. This can happen because Lotame has not fully implemented the getIdType across all of its server-side endpoints.

getProfileId()

The getProfileId() method looks in local storage and cookies for a previously retrieved Lotame profile id and returns it to the caller.

window.lotame_sync_<lotameClientId>.cmd.push(function() {
  var lotameProfileId = window.lotame_sync_<lotameClientId>.getProfileId();
});

setIdentity()

The setIdentity() method is used to pass user-identifiable info directly to Lotame for syncing. 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_sync_<lotameClientId>.cmd.push(function() {
  window.lotame_sync_<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_sync_<lotameClientId>.cmd.push(function() {
  window.lotame_sync_<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.

Previous User ID Syncing with Sync.js - Developer Guide Next User ID Syncing with Sync.js - Active Consent Guide