1

Sync.js Developer Reference 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 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 contact Lotame support by emailing support@lotame.com 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 Lightning 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>

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();
});
Upvote1 Follow
  • 1 Upvotes
  • 1 mth agoLast active
  • 129Views
  • 1 Following
Log In