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

# Cookie-sync

> Как синхронизировать ID пользователей с Youtarget: сценарии, адреса /sync и /rsync, макрос {inner_id}, передача ID в запросах, проверка и типовые ошибки.

[Cookie-sync](https://docs.youtarget.com/rtb/glossary/cookie-sync.md) связывает ваш ID пользователя с нашим, чтобы мы узнавали пользователя в запросах: без этого к нему не применить таргетинг по аудиториям и ограничение частоты.

## Коротко

- `/sync` — вы сообщаете нам свой ID, `/rsync` — узнаёте наш. Методы `GET` и `HEAD`, параметры в строке запроса, только HTTPS.
- Ваш идентификатор у нас — `platform_id`. Его и полный адрес синхронизации присылает менеджер.
- Макрос один — `{inner_id}`, им мы подставляем наш ID в ваш адрес возврата.
- Связь хранится ограниченное время, каждый вызов `/sync` её продлевает: синхронизируйте пользователей регулярно.
- Наша cookie сторонняя (`Secure`, `SameSite=None`): где сторонние cookie заблокированы, синхронизация не работает. Параметры согласия в адресе не передаются, см. [Приватность](../ssp/openrtb.md#приватность).

## Сценарии

Кто хранит таблицу соответствия ID, задаёт менеджер. Не знаете, что выбрать, — вызывайте `/sync` с `sync_url`.

| Кто хранит таблицу | Какой адрес вызвать | Что передать в OpenRTB | Что передать в JSON-фиде |
| --- | --- | --- | --- |
| Вы | `/rsync` или `/sync` с `sync_url` | Наш ID в `user.buyeruid` | `user_buyer_uid` |
| Мы | `/sync` с вашим ID в `external_id` | Ваш ID в `user.id`, тот же, что в `external_id` | `user_id` |
| Обе стороны | `/sync` с `external_id` и `sync_url` | `user.id` и `user.buyeruid` | `user_id` и `user_buyer_uid` |

- Если таблицу храните вы, одного `user.id` недостаточно: свою таблицу мы в этом случае не смотрим.
- Поля пользователя: [user в OpenRTB](../ssp/openrtb.md#user), [параметры JSON-фида](../ssp/json-feed.md#параметры-запроса).
- Режим покупки включает менеджер: **все запросы** (по умолчанию), **только синхронизированные** или **только несинхронизированные**. Неподходящий запрос получает `204`: при «только синхронизированных» рост доли `204` значит, что синхронизация работает хуже ожидаемого.

## Адрес /sync

Сохраняет связь вашего ID с нашим. Если нашей cookie нет, создаёт новый 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
```

| Параметр | Обязательно | Описание |
| --- | --- | --- |
| `platform_id` | да | Ваш идентификатор у нас. |
| `external_id` | да | ID пользователя на вашей стороне. |
| `sync_url` | нет | Адрес возврата с `{inner_id}`, URL-кодированный целиком. |

| Код | Когда | Что делать |
| --- | --- | --- |
| `302` | Передан `sync_url`. В `Location` — он с нашим ID. | Сохранить наш ID, если таблицу храните вы. |
| `200` | `sync_url` не передан. Тело пустое, не картинка. | Из тега `<img>` вызывайте только с `sync_url` и отдавайте картинку у себя. |
| `400` | Нет `platform_id` или `external_id`. | Исправить адрес. |
| `500` | Связь не сохранилась из-за ошибки на нашей стороне. | Повторить позже. |

## Адрес /rsync

Ничего у нас не сохраняет: ставит cookie, если её нет, и перенаправляет браузер на ваш адрес с нашим 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
```

| Параметр | Обязательно | Описание |
| --- | --- | --- |
| `platform_id` | да | Ваш идентификатор у нас. |
| `sync_url` | да | Адрес возврата с `{inner_id}`, URL-кодированный целиком. |

| Код | Когда | Что делать |
| --- | --- | --- |
| `302` | Оба параметра на месте. В `Location` — `sync_url` с нашим ID. | Сохранить пару «ваш ID — наш ID». |
| `400` | Нет `platform_id` или `sync_url`. | Исправить адрес. |

## Макрос `{inner_id}`

Пишется без `$`, другие макросы (`{uid}`, `${USER_ID}`) остаются как есть. Наш ID — строка из латинских букв, цифр, `-` и `_`, например `Xk3_pQ9aZ`.

1. Запишите адрес возврата: `https://partner.example.com/cm?buyer_uid={inner_id}`.
2. URL-кодируйте его ровно один раз целиком: `https%3A%2F%2Fpartner.example.com%2Fcm%3Fbuyer_uid%3D%7Binner_id%7D`.
3. Подставьте результат в `sync_url`.

Ответ на запрос из [примера /sync](#адрес-sync):

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

## Проверка

1. Откройте `/sync` без `sync_url`: ответ `200` и `Set-Cookie` с cookie `smi_uid` — это наш ID.
2. Добавьте `sync_url` и откройте дважды в том же браузере: ответ `302`, в `Location` то же значение, что в cookie, и оно не меняется.
3. Проверьте `/rsync` так же: ответ `302`, в `Location` наш ID.
4. Отправьте тестовые запросы с ID в поле из [сценария](#сценарии).
5. Доли узнанных пользователей в отчётах нет — запросите её у менеджера после запуска.

## Частые ошибки

| Симптом | Причина | Что делать |
| --- | --- | --- |
| В `Location` осталось `{inner_id}` или `%7Binner_id%7D` | `sync_url` закодирован дважды. | Кодируйте один раз. |
| На адрес возврата не приходят ваши параметры | `sync_url` не закодирован, его параметры ушли в наш адрес. | URL-кодируйте `sync_url` целиком. |
| При каждом вызове новый ID | Браузер не сохраняет cookie: вызов по HTTP или сторонние cookie заблокированы. | Вызывайте по HTTPS. |
| Синхронизация прошла, но пользователь не узнаётся | ID не в том поле или `user.id` не совпадает с `external_id`. | Передавайте ID по [сценарию](#сценарии). |

## Внешним DSP

- В `user.id` передаём наш ID, в `user.buyeruid` — ваш, если связь есть. Нет связи — нет `user.buyeruid`.
- Чтобы получать свой ID в `user.buyeruid`, вызывайте `/sync` со своим `platform_id` и ID в `external_id`. Храните таблицу у себя — вызывайте `/rsync` и сопоставляйте по `user.id`.
- Менеджер может включить отправку только синхронизированного трафика: тогда запрос уходит вам, только если есть ваш ID.
