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:
- Pass in your own customer/user ID (cookie tpid) to sync with Lotame's userIDs
- Pass in a customer email address 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 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:
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 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.
setUserConsent()
The Lotame Lightning Tag provides a method setUserConsent() to communicate whether user consent was obtained by passing an active consent flag directly into Lightning Tag. Once you've collected the appropriate consent from your customer within your privacy user experience, submit the appropriate signals as follows:
window.lotame_sync_<lotameClientId>.cmd.push(function() {
window.lotame_sync_<lotameClientId>.setUserConsent({
"lotameConsent": <true|false>
});
});The Lotame Sync.js Active Consent Guide describes the full details.
Content aside
Categories
- 1 Upvotes
- 2 yrs agoLast active
- 2203Views
- 1 Following