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:
- Pass in your own customer/user ID to sync with Lotame's userIDs
- Retrieve the Lotame Profile ID - Lotame's device ID
- 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:
-
Replace the two instances of <lotameClientId> in the two script blocks below. This will set up the Lotame namespace of window.lotame_sync_<lotameClientId>.
-
Change the code inside syncCallback to retrieve the Lotame Panorama ID or Lotame Profile ID and use them as needed on your site.
-
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. | |
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();
});
