User ID Syncing with Sync.js - Developer Guide

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. Pass in a customer email address to sync with Lotame's userIDs.
  3. Retrieve the Lotame Profile ID - Lotame's device ID
  4. 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 you want to deploy 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.getPanorama().getId();
    };


    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.