¶ Process Overview
As part of our synchronization 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.
- ID5 will initiate ID synchronizations to you; we refer to these synchronizations 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.
- 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
0as the UID.
¶ GDPR Support
ID5 will check that you have consent before performing cookie synchronizations, in addition to checking that ID5 has consent before processing. 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.
¶ 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.
- Dynamic Callback URL
- 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 synchronization URL without maintenance from you. This is our recommended implementation.
- Static Callback URL
- If you are not able to use a dynamic URL callback in pixel redirection, ID5 can store the state of cascade in cookies or via parameters on the request.
- 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:
- Encoded URL with a macro (recommended)
- Unencoded URL with a macro
- Appendable encoded URL
¶ Dynamic Callback URL Types
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. The macro text (i.e. {{UID}}) can be any string of text that you will replace with your own ID; this will need to be communicated to ID5 during the pixel set up phase. |
| TCF_CONSENT_STRING | String | (required in EEA) A valid IAB TCF consent string. |
| GDPR_FLAG | Integer | (optional) Whether or not GDPR applies to this request. We will send either 0 or 1. |
| GPP_CONSENT_STRING | String | (optional) A valid IAB Global Privacy Platform consent string. |
| GPP_APPLICABLE_SECTIONS | String | (optional) The GPP section ID(s) (integers) in force for the current transaction. In most cases, this field should have a single section ID. In rare occasions where such a single section ID can not be determined, the field may contain up to 2 values, separated by a comma. More information in GPP documentation |
¶ Example Implementation
- ID5 calls your pixel:
- You decode the URL and replace
{{UID}}with your UID for the user (in this example, ABCDE-12345), then redirect the user to:
- ID5 continues cascading to other platforms
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 {ENCODEDURL} value by ID5. The macro text (i.e. {{UID}}) can be any string of text that you will replace with your own ID; this will need to be communicated to ID5 during the pixel set up phase. |
| TCF_CONSENT_STRING | String | (required in EEA) A valid IAB TCF consent string. |
| GDPR_FLAG | Integer | (optional) Whether or not GDPR applies to this request. We will send either 0 or 1. |
| GPP_CONSENT_STRING | String | (optional) A valid IAB Global Privacy Platform consent string. |
| GPP_APPLICABLE_SECTIONS | String | (optional) The GPP section ID(s) (integers) in force for the current transaction. In most cases, this field should have a single section ID. In rare occasions where such a single section ID can not be determined, the field may contain up to 2 values, separated by a comma. More information in GPP documentation |
¶ Example Implementation
- ID5 calls your pixel:
- You replace
{{UID}}with your UID for the user (in this example, ABCDE-12345), then redirect the user to:
- ID5 continues cascading to other platforms
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 |
|---|---|---|
| TCF_CONSENT_STRING | String | (required in EEA) A valid IAB TCF consent string. |
| GDPR_FLAG | Integer | (optional) Whether or not GDPR applies to this request. We will send either 0 or 1. |
| ENCODEDURL | String | A dynamically generated unencoded URL that ID5 will populate in real time during the cascade process |
| GPP_CONSENT_STRING | String | (optional) A valid IAB Global Privacy Platform consent string. |
| GPP_APPLICABLE_SECTIONS | String | (optional) The GPP section ID(s) (integers) in force for the current transaction. In most cases, this field should have a single section ID. In rare occasions where such a single section ID can not be determined, the field may contain up to 2 values, separated by a comma. More information in GPP documentation |
¶ Example Implementation
- ID5 calls your pixel:
- You decode the callback URL, append it with your UID for the user (in this example, ABCDE-12345), then redirect the user to:
- ID5 continues cascading to other platforms
¶ Static Callback URL
In these scenarios, you will hardcode a portion or the entire URL to call back to ID5 after receiving a cookie sync request from us.
There are two types of static callback URLs we support:
- Static Callback URL with Dynamic Parameters (recommended)
- Static Callback URL
¶ Static Callback URL Types
In this scenario, your pixel endpoint will 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.
This method is preferred over the normal static callback integration, as it doesn't rely on cookies to store the cascade state.
¶ Callback URL Syntax
https://id5-sync.com/k/[id5AccountNum].gif?puid=[encodedPlatformUid]&[allQsParamsFromInitialCall]
![https://id5-sync.com/k/[id5AccountNum].gif?puid=[encodedPlatformUid]&[allQsParamsFromInitialCall]](https://id5-sync.com/k/id5AccountNum.gif?puid=encodedPlatformUid&all=Qs&Params=From&Initial=Call){kind=link}
¶ Callback URL Parameters
| Parameter | Type | Description |
|---|---|---|
| id5AccountNum | Integer | Your ID account number, provided by ID5 |
| encodedPlatformUid | String | Your UID for the user, encoded as a url parameter |
| allQsParamsFromInitialCall | String | One or more querystring parameters that were originally passed to your platform on the request to you. These should not be modified |
¶ Example Implementation
- ID5 calls your pixel:
- Your pixel would redirect to the following URL
https://id5-sync.com/k/113.gif?puid=ABCDE-12345&p=123&c=2&ca=8
- ID5 continues cascading to other platforms
In this scenario, your pixel endpoint will be expected to redirect the browser with a 302 HTTP response to a hardcoded URL that we provide below.
¶ Callback URL Syntax
https://id5-sync.com/k/[id5AccountNum].gif?puid=[encodedPlatformUid]
![https://id5-sync.com/k/[id5AccountNum].gif?puid=[encodedPlatformUid]](https://id5-sync.com/k/id5AccountNum.gif?puid=encodedPlatformUid){kind=link}
¶ Callback URL Parameters
| Parameter | Type | Description |
|---|---|---|
| id5AccountNum | Integer | Your ID account number, provided by ID5 |
| encodedPlatformUid | String | Your UID for the user, encoded as a url parameter |
¶ Example Implementation
- ID5 calls your pixel:
- Your pixel would redirect to the following URL
- ID5 continues cascading to other platforms
Note: With this integration method it's not possible to directly call your pixel for testing the full redirect, as it requires us to set cookies to continue the cascade. If you have questions, reach out to support@id5.io.
¶ 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 in place of uidValueHere:
[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. There may be a commercial impact to turning this on.
¶ 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):