Cookie sync
Cookie syncMatching user IDs between two ad systems. links your user ID with ours so that we recognize the user in requests: without it, audience targeting and frequency capping can't be applied.At a glance
/sync: you send us your ID;/rsync: you get ours. MethodsGETandHEAD, parameters in the query string, HTTPS only.- Your identifier on our side is
platform_id. Your account manager sends it together with the full sync URL. - There is one macro,
{inner_id}: we use it to put our ID into your return URL. - The link is stored for a limited time, and each
/synccall extends it: sync users regularly. - Our cookie is a third-party cookie (
Secure,SameSite=None): where third-party cookies are blocked, sync doesn't work. Consent parameters are not passed in the URL, see Privacy.
Scenarios
The manager sets who stores the ID match table. If you are not sure which to choose, call /sync with sync_url.
| Who stores the table | Endpoint to call | What to pass in OpenRTB | What to pass in the JSON feed |
|---|---|---|---|
| You | /rsync, or /sync with sync_url | Our ID in user.buyeruid | user_buyer_uid |
| Us | /sync with your ID in external_id | Your ID in user.id, the same as in external_id | user_id |
| Both sides | /sync with external_id and sync_url | user.id and user.buyeruid | user_id and user_buyer_uid |
- If you store the table,
user.idalone is not enough: in this case we don't check our own table. - User fields: user in OpenRTB, JSON feed parameters.
- The manager enables the buying mode: all requests (default), synced only or unsynced only. A request that doesn't fit gets
204: with "synced only", a growing share of204means sync works worse than expected.
The /sync endpoint
Stores the link between your ID and ours. If there is no cookie of ours, it creates a new ID.
text
https://sync.example.com/sync?platform_id=7c9e6679-7425-40de-944b-e07fc1f90ae7&external_id=u-48213&sync_url=https%3A%2F%2Fpartner.example.com%2Fcm%3Fbuyer_uid%3D%7Binner_id%7D| Parameter | Required | Description |
|---|---|---|
platform_id | yes | Your identifier on our side. |
external_id | yes | The user ID on your side. |
sync_url | no | Return URL with {inner_id}, URL-encoded as a whole. |
| Code | When | What to do |
|---|---|---|
302 | sync_url was passed. Location holds it with our ID. | Store our ID if you store the table. |
200 | sync_url was not passed. The body is empty, not an image. | From an <img> tag, call it only with sync_url and serve the image from your side. |
400 | platform_id or external_id is missing. | Fix the URL. |
500 | The link was not stored because of an error on our side. | Retry later. |
The /rsync endpoint
Stores nothing on our side: sets the cookie if it is missing and redirects the browser to your URL with our ID.
text
https://sync.example.com/rsync?platform_id=7c9e6679-7425-40de-944b-e07fc1f90ae7&sync_url=https%3A%2F%2Fpartner.example.com%2Fcm%3Fbuyer_uid%3D%7Binner_id%7D| Parameter | Required | Description |
|---|---|---|
platform_id | yes | Your identifier on our side. |
sync_url | yes | Return URL with {inner_id}, URL-encoded as a whole. |
| Code | When | What to do |
|---|---|---|
302 | Both parameters are present. Location holds sync_url with our ID. | Store the "your ID – our ID" pair. |
400 | platform_id or sync_url is missing. | Fix the URL. |
The {inner_id} macro
It is written without $; other macros ({uid}, ${USER_ID}) stay as they are. Our ID is a string of Latin letters, digits, - and _, for example Xk3_pQ9aZ.
- Write your return URL:
https://partner.example.com/cm?buyer_uid={inner_id}. - URL-encode it exactly once, as a whole:
https%3A%2F%2Fpartner.example.com%2Fcm%3Fbuyer_uid%3D%7Binner_id%7D. - Put the result into
sync_url.
Response to the request from the /sync example:
text
302 Found
Location: https://partner.example.com/cm?buyer_uid=Xk3_pQ9aZChecking
- Open
/syncwithoutsync_url: the response is200withSet-Cookiefor thesmi_uidcookie, which is our ID. - Add
sync_urland open it twice in the same browser: the response is302, andLocationholds the same value as the cookie, and it doesn't change. - Check
/rsyncthe same way: the response is302with our ID inLocation. - Send test requests with the ID in the field from the scenario.
- Reports don't show the share of recognized users; ask the manager for it after launch.
Common errors
| Symptom | Cause | What to do |
|---|---|---|
Location still contains {inner_id} or %7Binner_id%7D | sync_url is encoded twice. | Encode it once. |
| Your parameters don't reach your return URL | sync_url is not encoded, and its parameters went into our URL. | URL-encode sync_url as a whole. |
| A new ID on every call | The browser doesn't store the cookie: the call goes over HTTP or third-party cookies are blocked. | Call over HTTPS. |
| Sync succeeded, but the user is not recognized | The ID is in the wrong field, or user.id doesn't match external_id. | Pass the ID according to the scenario. |
For external DSPs
- In
user.idwe pass our ID, and inuser.buyeruidyours, if a link exists. No link, nouser.buyeruid. - To get your ID in
user.buyeruid, call/syncwith yourplatform_idand your ID inexternal_id. If you store the table yourself, call/rsyncand match byuser.id. - The manager can enable sending only synced traffic: then a request is sent to you only if we have your ID.