Cookie-sync
Cookie-syncСопоставление идентификаторов пользователя между двумя рекламными системами. связывает ваш ID пользователя с нашим, чтобы мы узнавали пользователя в запросах: без этого к нему не применить таргетинг по аудиториям и ограничение частоты.Коротко
/sync— вы сообщаете нам свой ID,/rsync— узнаёте наш. МетодыGETиHEAD, параметры в строке запроса, только HTTPS.- Ваш идентификатор у нас —
platform_id. Его и полный адрес синхронизации присылает менеджер. - Макрос один —
{inner_id}, им мы подставляем наш ID в ваш адрес возврата. - Связь хранится ограниченное время, каждый вызов
/syncеё продлевает: синхронизируйте пользователей регулярно. - Наша cookie сторонняя (
Secure,SameSite=None): где сторонние cookie заблокированы, синхронизация не работает. Параметры согласия в адресе не передаются, см. Приватность.
Сценарии
Кто хранит таблицу соответствия 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, параметры JSON-фида.
- Режим покупки включает менеджер: все запросы (по умолчанию), только синхронизированные или только несинхронизированные. Неподходящий запрос получает
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.
- Запишите адрес возврата:
https://partner.example.com/cm?buyer_uid={inner_id}. - URL-кодируйте его ровно один раз целиком:
https%3A%2F%2Fpartner.example.com%2Fcm%3Fbuyer_uid%3D%7Binner_id%7D. - Подставьте результат в
sync_url.
Ответ на запрос из примера /sync:
text
302 Found
Location: https://partner.example.com/cm?buyer_uid=Xk3_pQ9aZПроверка
- Откройте
/syncбезsync_url: ответ200иSet-Cookieс cookiesmi_uid— это наш ID. - Добавьте
sync_urlи откройте дважды в том же браузере: ответ302, вLocationто же значение, что в cookie, и оно не меняется. - Проверьте
/rsyncтак же: ответ302, вLocationнаш ID. - Отправьте тестовые запросы с ID в поле из сценария.
- Доли узнанных пользователей в отчётах нет — запросите её у менеджера после запуска.
Частые ошибки
| Симптом | Причина | Что делать |
|---|---|---|
В 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.