Receive Cookie Sync Requests from ID5

Receive Cookie Sync Requests from ID5

Process Overview

As part of our synchronisation process, we will need to make requests to your system that will return back to ID5 with your UID. There are several methods supported for this process that are explained in more detail.

  1. ID5 will initiate ID synchronisations to you; we refer to these synchronisations as "cascades". In order to receive cascades, you will need to provide ID5 with your cookie sync URL (endpoint). ID5 relies on HTTP redirects (i.e. 302) to handle these cascades.
  2. ID5 will call the URL you provide and expect to be called back by redirecting the user to a URL provided by ID5.
You must always redirect users to the callback URL provided by ID5, even if the user is unknown to your system. If the user is unknown, you should create an identity for this new user and return their new UID to ID5 in the callback or pass a 0 as the UID.

GDPR Support

ID5 acts as your Processor for cookie syncing, so we will check that you have consent before performing cookie synchronisations. Within the pixel URL that you provide us during Integration/Setup, you may specify parameters for ID5 to pass you a GDPR flag and an IAB TCF consent string. Typically, the two querystring fields are gdpr (with a value of 0 or 1) and gdpr_consent, respectively, but if you have a different setup, please let us know.

If GDPR applies to a particular request, we have a consent string, and you do not have consent, ID5 will not call your pixel. However, if we do call you and you then determine that you do not have proper consent for you to process data, you should still redirect back to ID5 like normal, and pass an empty string as the value for your UID.

If GDPR applies to a particular request but we do NOT have a consent string, you may tell us (during Integration/Setup of your account) whether you’d like us to call your pixel or not. Like above, if we do call you and you determine that you do not have proper consent to process data, you should still redirect back to ID5 like normal, and pass an empty string as the value for your UID.

Callback URL Options

We support three methods for callback URLs that you must supply us (step 2 in the diagram above). In all cases, we only support making calls to HTTPS endpoints.
  1. Dynamic Callback URL
    1. If you support receiving a dynamic callback URL in the querystring, ID5 will provide a URL containing a macro to be replaced by your UID. This process allows ID5 to update its own synchronisation URL without maintenance from you. This is our recommended implementation.
  2. Static Callback URL
    1. If you are not able to use a dynamic URL callback in pixel redirection, ID5 can store the state of cascade in cookies.
    2. NOTE: this means that you may have to update ID5’s callback URL in case of major changes/updates in the process.
  3. Static Callback URL with Dynamic Parameters
    1. If you require a static url, but are able to send back parameters to us that you received from us on the initial call, this method is preferred over Option 2.
    2. NOTE: this means that you may have to update ID5’s callback URL in case of major changes/updates in the process.

Dynamic Callback URL

In these scenarios, ID5 will dynamically generate a callback URL to our system, providing a mechanism for you to include your UID back to us to complete the sync. We will pass this callback URL in the querystring of the pixel call to your system.

There are three types of callback URLs we can provide:
  1. Encoded URL with a macro
  2. Unencoded URL with a macro
  3. Appendable encoded URL

Encoded URL with a Macro

In this scenario, ID5 will call your pixel, passing an encoded URL with a macro into a parameter you define. Your endpoint is expected to decode the URL, replace the macro within the ID5 URL with your UID, and then redirect the browser with a 302 HTTP response to the URL.

URL Syntax

URL Parameters
Parameter
Type
Description
{ENCODEDURL}
String
A dynamically generated encoded URL that ID5 will populate in real time during the cascade process
UID
String
UID macro to be replaced with the encoded user identifier from your system. This will be placed inside the {ENCODEDURL} value by ID5.
GDPR_FLAG
Integer
(optional) Whether or not GDPR applies to this request. We will send either 0 or 1.
TCF_CONSENT_STRING
String
(optional) A valid IAB TCF consent string.

Example Implementation
1) ID5 calls your pixel:
2) You decode the URL and replace [UID] with your UID for the user (in this example, ABCDE-12345), then redirect the user to:
3) ID5 continues cascading to other platforms

Unencoded URL with a macro

In this scenario, ID5 will call your pixel, appending an unencoded url with a macro onto your endpoint. Your endpoint is expected to replace the macro within the ID5 URL with your UID and then redirect the browser with a 302 HTTP response to the URL.
URL Syntax
URL Parameters
Parameter
Type
Description
{UNENCODEDURL}
String
A dynamically generated unencoded URL that ID5 will populate in real time during the cascade process
UID
String
UID macro to be replaced with the encoded user identifier from your system. This will be placed inside the {UNENCODEDURL} value by ID5
GDPR_FLAG
Integer
(optional) Whether or not GDPR applies to this request. We will send either 0 or 1.
TCF_CONSENT_STRING
String
(optional) A valid IAB TCF consent string.

Example Implementation
1) ID5 calls your pixel:
2) You replace [UID] with your UID for the user (in this example, ABCDE-12345), then redirect the user to:
3) ID5 continues cascading to other platforms

Appendable encoded URL

In this scenario, ID5 will call your pixel, appending an encoded url without a macro onto your endpoint. Your endpoint is expected to decode the callback URL, append the ID5 URL with your UID, and then redirect the browser with a 302 HTTP response to the URL.
URL Syntax
URL Parameters
Parameter
Type
Description
GDPR_FLAG
Integer
(optional) Whether or not GDPR applies to this request. We will send either 0 or 1.
TCF_CONSENT_STRING
String
(optional) A valid IAB TCF consent string.
{ENCODEDURL}
String
A dynamically generated encoded URL that ID5 will populate in real time during the cascade process

Example Implementation
1) ID5 calls your pixel:
2) You decode the callback URL, append it with your UID for the user (in this example, ABCDE-12345), then redirect the user to:
3) ID5 continues cascading to other platforms

Static Callback URL

In this scenario, your pixel endpoint will then be expected to redirect the browser with a 302 HTTP response to a hardcoded URL that we provide below.

Callback URL Syntax
Callback URL Parameters
Parameter
Type
Description
id5AccountNumIntegerYour ID account number, provided by ID5
encodedPlatformUidStringYour UID for the user, encoded as a url parameter

Example Implementation
1) ID5 calls your pixel:
2) Your pixel would redirect to the following URL
3) ID5 continues cascading to other platforms

Static Callback URL with Dynamic Parameters

In this scenario, your pixel endpoint will then be expected to redirect the browser with a 302 HTTP response to a hardcoded URL that we provide below, while appending any querystring parameters we provided on the call to your servers.

Callback URL Syntax
Callback URL Parameters
Parameter
Type
Description
id5AccountNumIntegerYour ID account number, provided by ID5
encodedPlatformUidStringYour UID for the user, encoded as a url parameter
allQsParamsFromInitialCallStringOne or more querystring parameters that were originally passed to your platform on our cascade to you. These should not be modified.

Example Implementation
1) ID5 calls your pixel:
2) Your pixel would redirect to the following URL
3) ID5 continues cascading to other platforms

Self-Testing the Cascade

To test the cascade process by yourself, you can emulate the cascade by using the following values as the ID5 redirect URL, placing your UID macro at the end:
{UNENCODEDURL} = https://id5-sync.com/tcb/t?puid=uidValueHere
{ENCODEDURL} = https%3A%2F%2Fid5-sync.com%2Ftcb%2Ft%3Fpuid%3DuidValueHere
The browser should reply with your own user ID. This will allow automated test on both side.

Example Testing

Load your pixel endpoint in a browser, substituting the {ENCODEDURL} or {UNENCODEDURL} macros from above, making sure to include your UID at the end of our test callback URL.

Receiving the ID5 ID

If you would like to receive the ID5 ID when we cascade to your platform, you will need to provide us with a parameter in your pixel URL that we can pass it into. Simply inform ID5 where we should place the ID5 ID in the querystring and we’ll make the necessary updates on our end.
If you would like to retrieve the ID5 ID, please let your ID5 representative know so we can configure your account accordingly

Example Receiving the ID5 ID

If you are using an Encoded URL with a macro from above, to receive the ID5 ID your url may look like this instead (adding an external_id parameter to the url):