<!-- https://docs.youtarget.com/rtb/en/common/cookie-sync.html -->

# Cookie sync

> How to sync user IDs with Youtarget: scenarios, the /sync and /rsync endpoints, the {inner_id} macro, passing IDs in requests, checks and common errors.

[Cookie sync](https://docs.youtarget.com/rtb/en/glossary/cookie-sync.md) 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. Methods `GET` and `HEAD`, 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 `/sync` call 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](../ssp/openrtb.md#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.id` alone is not enough: in this case we don't check our own table.
- User fields: [user in OpenRTB](../ssp/openrtb.md#user), [JSON feed parameters](../ssp/json-feed.md#request-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 of `204` means 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`.

1. Write your return URL: `https://partner.example.com/cm?buyer_uid={inner_id}`.
2. URL-encode it exactly once, as a whole: `https%3A%2F%2Fpartner.example.com%2Fcm%3Fbuyer_uid%3D%7Binner_id%7D`.
3. Put the result into `sync_url`.

Response to the request from the [/sync example](#the-sync-endpoint):

```text
302 Found
Location: https://partner.example.com/cm?buyer_uid=Xk3_pQ9aZ
```

## Checking

1. Open `/sync` without `sync_url`: the response is `200` with `Set-Cookie` for the `smi_uid` cookie, which is our ID.
2. Add `sync_url` and open it twice in the same browser: the response is `302`, and `Location` holds the same value as the cookie, and it doesn't change.
3. Check `/rsync` the same way: the response is `302` with our ID in `Location`.
4. Send test requests with the ID in the field from the [scenario](#scenarios).
5. 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](#scenarios). |

## For external DSPs

- In `user.id` we pass our ID, and in `user.buyeruid` yours, if a link exists. No link, no `user.buyeruid`.
- To get your ID in `user.buyeruid`, call `/sync` with your `platform_id` and your ID in `external_id`. If you store the table yourself, call `/rsync` and match by `user.id`.
- The manager can enable sending only synced traffic: then a request is sent to you only if we have your ID.
