Submit Support Ticket
User ID Syncing
Technical Implementation documentation for the sync.js tag
HomeTechnical DocumentationUser ID Syncing
Search
1

Sync.js Developer Reference Guide

  • updated 5 days ago

Overview

This page provides reference details for all available Lotame Sync Tag functionality. The Lotame Sync Tag is a lightweight JavaScript, that performs user ID syncing in all browser environments, including those that are 3rd party cookie restricted. 

Use the Lotame Sync Tag to:

  1. Pass in your own customer/user ID (cookie tpid) to sync with Lotame's userIDs
  2. Retrieve the Lotame Profile ID - Lotame's device ID
  3. Retrieve the Lotame Panorama ID ™ - Lotame's people-based ID

The Sync Tag is designed to be as lightweight as possible to closely mimic a standard 3rd party syncing pixel. This tag will not perform any data collection or deploy 3rd party code. The Sync Tag will only perform user ID syncing.

Pre-Implementation

Before implementing Lotame sync.js on your site, please submit a Lotame Support ticket form through this link and let them know that you are interested in deploying sync.js. You will need to inform our support teams on whether you plan only to retrieve the Lotame Profile ID or if you also plan to retrieve the Lotame Panorama ID ™. Lotame support will enable sync.js for your account so you can begin using it on your site.

Retrieving Lotame IDs

Take the below script block and perform the following to prepare for use on your site:

  1. Replace the two instances of <lotameClientId> in the two script blocks below. This will set up the Lotame namespace of window.lotame_sync_<lotameClientId>.

  2. Change the code inside syncCallback to retrieve the Lotame Panorama ID ™ or Lotame Profile ID and use them as needed on your site.

  3. Replace <lotameClientId> in the code example from “Triggering the Sync” section below.

Lotame recommends loading the Sync.JS Tag directly on your page, in the <head> section. Lotame recommends against loading through a tag manager such as Google Tag Manager (GTM) if at all possible. It is a supported use-case, just not best practice when it comes to running as quickly as possible.

Configure & Load Sync.js script

<!-- Configure the sync.js script -->
<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.getPanoramaId();
    };


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

    // Lotame initialization
    var lotameConfig = lotameTagInput.config || {};
    var namespace = window['lotame_sync_' + lotameClientId] = {};
    namespace.config = lotameConfig;
    namespace.data = {};
    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>

Note: You need to source the Javascript tag from Lotame's server, as shown above to ensure correct functionality. Our Javascript tags are hosted in AWS Cloudfront CDN to provide the lowest latency possible worldwide.

Triggering the Sync Call

The way to trigger the actual sync logic is by using the following piece of code anywhere after you have defined the main script block above. When the sync() call completes, the callback defined in the above config code will be called and you can use the Profile and Panorama IDs  ™ as needed.

<!-- 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>

You will notice that the above code example pushes the sync() call onto a command queue that allows your code to execute asynchronously as soon as our tag finishes loading on your page.

When to call sync()

As a best practice, you should make the sync() call on every page load when only retrieving IDs. Lotame sync.js uses local caching to minimize making regular calls to Lotame servers.

Sending Your ID to Lotame

Use the same configuration as noted in the above section, including optionally using the returned Lotame IDs, Panorama ID ™ and the Profile ID.

Triggering the Sync Call with Third Party ID sent to Lotame

The way to trigger the actual sync logic is by using the following piece of code anywhere after you have defined the main script block above. Here you will add your thirdParty namespace and value that will be sent to Lotame during the sync() call. When the sync() call completes, the callback defined in the above config code will be called and you can use the Profile and Panorama IDs ™ as needed.

<!-- Initiate the sync call. When it completes, it will trigger syncCallback with a profile object -->
<script>
    var dataObject = {
        thirdParty: {
            namespace: 'FAKE',
            value: '123456789101112131415'
        }
    };
    window.lotame_sync_<lotameClientId>.cmd.push(function() {
        window.lotame_sync_<lotameClientId>.sync(dataObject);
    });
</script>

You will notice that the following code example pushes the sync() call onto a command queue that allows your code to execute asynchronously as soon as our tag finishes loading on your page.

When to call sync()

As a best practice, only send your id to Lotame when you first want to link it, it needs to be updated, or to refresh it after 30 days. Each sync() call with your id will trigger a call to the Lotame servers and skip any client-side caching. 

Detailed Reference Documentation

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

Config Object Details

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

Parameter Name Description Required? Default
onProfileReady Callback function called every time a sync() call completes. function (profile) No {}

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
getPanoramaId() String or NULL n/a The Panorama ID ™ linked to the Profile ID

Additional Namespace 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 retrieving the values inside the callback function. Use whichever scenario works best for your codebase.

getPanoramaId()

The getPanoramaId() method looks in local storage and cookies for a previously retrieved Lotame panorama ID ™ and returns it to the caller.

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

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

window.lotame_sync_<lotameClientId>.cmd.push(function() {
  window.lotame_sync_<lotameClientId>.setIdentity(
    { id: 'kevin@lotame.com', type: 'EMAIL'}
  );
});

Also, 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">

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

Upvote1 Follow
  • 1 Upvotes
  • 9 mths agoLast active
  • 1097Views
  • 1 Following
cancel
Mention someone by typing their name
No matching users
Powered by Forumbee

Home

 View all topics
Log In

Tags