1. User Cookie Sync Process

Note: For clarification purposes, on this documentation subsequent steps are numerically ordered (1, 2, 3...), and different alternatives for the same step are listed with letters (A, B, C ...). 

The goal of the sync process is for Retargetly to be able to cookie the user and also to exchange user ids with the Data Provider (from now on called partner). This exchange is the first step, necessary to associate segment data to each user, using an ID to identify them.There are two options: using Retargetly's user id or using partner own specific user id. In the first case, a matching table of Ids will be hosted by the partner, in order for them to be able to translate their own user id, into Retargetly's id before data ingestion process. If Partner user id is used, then the matching table will be hosted on Retargetly's side, and Retargetly handles the user id translation.  

1.A) Partner hosts the matching table 

If partner holds the matching table, this means that it will be using Retargetly's user ids to ingest data into Retargetly. So, It will need to get to know its web users's Retargetly ids. There are two possible scenarios for this:

1.A.A) Partner websites do not have implemented Retargetly's web source tag

In this case, partner should instanciate and drop a Retargetly's getuid pixel in order to allow Retargetly to cookie the web users. Also, this pixel allows a redirect URL to be provided, so the partner can get the Retargetly's user id and then can populate its matching table. Retargetly's getuid URL is the following: 

https://api.retargetly.com/getuid?p={partnerId}&redirect={redirectURL}
  • {partnerId} should be replaced with the partnerId assigned by Retargetly to the partner (a DMP account should be created in order to get this).
  • {redirectURL} is the URL to which the user will be redirected. Retargetly will include the user id on the request, replacing the macro: %rlid%.

For example, if partner's sync URL is https://data.partner.com/sync?userId= (receiving the user id under userId query string parameter), then the redirect parameter should be the following URL: 

 https://data.partner.com/sync?userId=%rlid%

If partnerId assigned by Retargetly is 123456, then the complete img tag that the partner should drop when the user enters their site is as follows:

<img src="https://api.retargetly.com/getuid?p=123456&redirect=https%3A%2F%2Fdata.partner.com%2Fsync%3FuserId%3D%25rlid%25" alt="" width="0" height="0" />

1.A.B) Partner websites already have implemented the Retargetly's web source tag

If all partner's websites already implement the Retargetly's web source tag, this means Retargetly is already setting cookies for this users and generating ids for them. There is no need to implement a new getuid pixel sync, because the Retargetly Ids for the users can be accessed via Javascript directly on the websites. To get the Retargetly Id for each user this way, the partner should include a javascript code inside the webpages. Instructions for this can be found here: Getting Retargetly's web cookie user id

1.B) Retargetly hosts the matching table 

If partner requires that Retargetly should host the matching table, then partner should report their user ids. There are two different ways that can be used for this. The recommended one, is to setup Retargetly's standard script tag and use it to post the User Id. An alternative, is dropping an img tag containing the user id. For both this sync processes to work, there should be an additional setup on the partner's account, that should be done by Retargetly's engineering team. Please, contact desk@retargetly.com for this.

1.B.A) Implementing Retargetly's standard script tag 

Partner should include this tag inside the <body> section of every page inside partner application. This script tag includes Retargetly's library for different functions that can be executed (complete documentation included here). 

 <script type="text/javascript"> var _rl_cn = _rl_cn || 0,_rl_ptc = ("https:" == window.location.protocol ? "https" : "http"); window._rl_ids = window._rl_ids || []; window._rely = window._rely || []; _rl_ids.push({pid: {partnerId}, src:0}); _rely.send = _rely.send?_rely.send:  function() {}; (function() { var rl = document.createElement("script"); rl.type = "text/javascript"; rl.async = true; rl.src = _rl_ptc + "://api.retargetly.com/loader?id=" + _rl_ids[_rl_ids.length-1].pid; rl.id = "rely-api-"+(_rl_cn++); var s = document.getElementsByTagName("script")[0]; s.parentNode.insertBefore(rl, s); })(); </script>

{partnerId} label inside previous script tag, should be replaced with the provided partnerId. If partnerId is 123456, then the script tag that should be added will be as follows: 

 <script type="text/javascript"> var _rl_cn = _rl_cn || 0,_rl_ptc = ("https:" == window.location.protocol ? "https" : "http"); window._rl_ids = window._rl_ids || []; window._rely = window._rely || []; _rl_ids.push({pid: 123456, src:0}); _rely.send = _rely.send?_rely.send:  function() {}; (function() { var rl = document.createElement("script"); rl.type = "text/javascript"; rl.async = true; rl.src = _rl_ptc + "://api.retargetly.com/loader?id=" + _rl_ids[_rl_ids.length-1].pid; rl.id = "rely-api-"+(_rl_cn++); var s = document.getElementsByTagName("script")[0]; s.parentNode.insertBefore(rl, s); })(); </script>

 This standard tag gives you the capability to report the user ID (different for each user) to Retargetly. After including this tag, the external_id attribute for current user should be set, including another custom script tag, right after standard tag, as follows:

<script>
_rely.push({'external_id': {externalId}});
_rely.send();
</script>

{externalId} is a dummy label meaning external id, that should be replaced with the actual user id provided by the data partner. For instance, when a user with id: AcX24nm is using partner's web app, the tag that should be dropped will look like this:

<script>
_rely.push({'external_id': 'AcX24nm'});
_rely.send();
</script>

And thats it. 

1.B.B) Implementing Retargetly's sync URL

There is an alternative to provide Retargetly with partner user ids: instead of including the script tag, partner can include an image tag with Retargetly's specific sync URL. The sync URL is as follows:

https://api.retargetly.com/data?id={partnerId}&external_id={externalId}
  • {externalId}. As before, this label should be replaced with the actual partner user id.
  • {partnerId}. This label should be replaced with the partner Id provided by Retargetly.

If partnerId is 123456, and user with AcX24nm is entering partner's web app, the img tag that should be dropped will look like this

<img src="https://api.retargetly.com/data?id=123456&external_id=AcX24nm" alt="" />

That <img> tag should be droped at least once per user (inside <body> section). It is recommeded to keep dropping it on a daily or weekly basis.

How did we do?

2. Taxonomy Definition

Contact