Сопоставление файлов cookie

Сопоставление файлов cookie — это функция, которая позволяет сопоставлять файл cookie (например, идентификатор пользователя, просматривавшего ваш веб-сайт), с соответствующим идентификатором пользователя Google для конкретного участника торгов и создавать списки пользователей, которые могут помочь вам сделать более эффективный выбор ставок. В этом руководстве описываются концепции, используемые в сопоставлении файлов cookie, а также различные рабочие процессы сопоставления файлов cookie и любые варианты, которые они могут иметь для определенных случаев использования.

Концепции

Владельцы доменов обычно устанавливают содержимое файлов cookie для пользователей, просматривающих их сайт, которые используются для идентификации пользователей в этом домене. Даже если два владельца домена в противном случае согласились бы на обмен этими данными, модель безопасности интернет-браузеров ограничивает чтение файла cookie, установленного другим доменом.

В контексте цифровой рекламы Google идентифицирует пользователей с помощью файлов cookie, принадлежащих домену doubleclick.net , а участники торгов, участвующие в торгах в реальном времени, могут иметь собственный домен, в котором они определяют некоторый набор пользователей, которым они хотели бы показывать рекламу. Сопоставление файлов cookie позволяет участнику торгов сопоставлять свои файлы cookie с файлами Google, чтобы они могли определить, связан ли показ, отправленный в запросе ставки, с одним из целевых пользователей. Они получат либо свои собственные данные файлов cookie, либо идентификатор пользователя Google для конкретного участника торгов. это зашифрованная форма файла cookie doubleclick.net в запросе ставки.

Служба сопоставления файлов cookie, описанная в этом руководстве, облегчает создание и поддержание связи между файлом cookie участника торгов и идентификатором пользователя Google, а также позволяет заполнять списки пользователей.

Таблицы соответствий

Таблицу соответствия можно использовать для сопоставления идентификатора или других данных из одного домена в другой. Участники торгов могут использовать службу сопоставления файлов cookie для заполнения своих собственных таблиц соответствия, сопоставляя свои файлы cookie для данного пользователя с идентификатором пользователя Google, или для заполнения таблицы соответствия, размещенной в Google. Таблицы соответствия необходимы для того, чтобы приложение участника торгов могло получить доступ к данным cookie для пользователя, которому показывается показ.

Таблицы соответствий, размещенные в Google

Для упрощения обслуживания, сокращения задержек и доступа к данным о совпадениях для пользователей в определенных регионах рекомендуется разрешить Google размещать вашу таблицу соответствий. Это позволяет вам указать безопасную для Интернета строку в кодировке base64 — далее именуемую размещенными данными соответствия — которая будет сопоставлена ​​с идентификатором пользователя Google для данного пользователя. После установления совпадения его можно использовать следующими способами:

  • Ставки в режиме реального времени . В последующих запросах ставок на показы, связанные с пользователем, Google будет отправлять вам размещенные данные соответствия, которые вы сопоставили с их идентификатором пользователя Google. Если ваша конечная точка назначения ставок настроена на использование протокола Google RTB, вы получите его в виде декодированных байтов через поле BidRequest.hosted_match_data . В реализации Google OpenRTB BidRequest.user.buyeruid вернет эти данные в виде безопасной для Интернета строки в кодировке base64.

  • Списки пользователей . Списки пользователей могут быть заполнены либо идентификаторами пользователей Google, либо размещенными данными о совпадениях.

  • Предварительный таргетинг . Вы можете настроить предварительный таргетинг таким образом, чтобы получать только запросы ставок, содержащие размещенные данные соответствия. Это можно использовать для устранения менее релевантных показов для пользователей за пределами вашего пространства файлов cookie.

Списки пользователей

Списки пользователей можно создавать и управлять ими с помощью Real-Time Bidding API . После создания эти списки можно заполнить с помощью рабочих процессов сопоставления файлов cookie, описанных ниже, или с помощью службы массовой загрузки .

Начиная

Чтобы начать работу с сопоставлением файлов cookie, вы должны связаться со своим техническим менеджером по работе с клиентами, который может активировать определенные рабочие процессы и помочь вам настроить следующее:

  • Идентификатор сети сопоставления файлов cookie (NID) : строковый идентификатор, однозначно идентифицирующий учетную запись участника торгов для сопоставления файлов cookie и других связанных операций.
  • URL-адрес сопоставления файлов cookie : базовый URL-адрес конечной точки, которая будет принимать и обрабатывать входящие запросы в рамках рабочих процессов сопоставления файлов cookie. Участники торгов могут встраивать макросы в этот URL-адрес, чтобы управлять порядком параметров, передаваемых ему в рабочих процессах сопоставления файлов cookie.
  • Тег сопоставления . Тег, который необходимо разместить в браузере пользователя для инициированного участником торгов рабочего процесса сопоставления файлов cookie. Это может быть показано вместе с рекламой или размещено на веб-ресурсах вне рекламы.
  • URL-адрес отчета о сопоставлении файлов cookie (необязательно): в рабочем процессе однонаправленного сопоставления файлов cookie это необязательный URL-адрес, который можно указать для указания конечной точки, которая будет получать сведения об ошибке в случае сбоя сопоставления файлов cookie из-за перенаправления HTTP 302. По умолчанию ответы будут отправляться на этот URL-адрес только в случае ошибки при сопоставлении файлов cookie, но участники торгов могут запросить, чтобы перенаправление всегда отправлялось.
  • URL-адрес службы сопоставления файлов cookie : для бирж, реализующих рабочий процесс службы сопоставления файлов cookie , это базовый URL-адрес конечной точки, предназначенной для ответа на входящие запросы.
  • Квота Cookie Match Assist : для бирж, реализующих рабочий процесс Cookie Match Assist , это максимальное количество запросов, которые их URL-адрес сопоставления файлов cookie может получать каждую секунду. Это сделано для того, чтобы запросы CMA не перегружали серверы биржи запросами.

В любом из поддерживаемых рабочих процессов сопоставления файлов cookie URL-адрес сопоставления файлов cookie участника торгов обычно имеет параметры, добавленные в негарантированном порядке. Участники торгов с интеграцией, требующей последовательного порядка параметров, могут размещать макросы в своем URL-адресе сопоставления файлов cookie, чтобы гарантировать их размещение.

Поддерживаемые макросы

Участники торгов могут дополнительно настроить URL-адрес сопоставления файлов cookie, включив в него один или несколько макросов в форме %%GOOGLE_<PARAM_NAME>%% или %%GOOGLE_<PARAM_NAME>_PAIR%% . Поддерживаемые макросы и их расширенные значения:

макрос Расширенное значение
GOOGLE_GID GOOGLE_USER_ID
GOOGLE_GID_PAIR &google_gid= GOOGLE_USER_ID
GOOGLE_CVER COOKIE_VERSION_NUMBER
GOOGLE_CVER_PAIR &cver= COOKIE_VERSION_NUMBER
GOOGLE_ERROR ERROR_ID
GOOGLE_ERROR_PAIR &google_error= ERROR_ID
GOOGLE_PUSH PIXEL_MATCH_DATA
GOOGLE_PUSH_PAIR &google_push= PIXEL_MATCH_DATA
GOOGLE_ALL_ПАРАМЫ google_gid= GOOGLE_USER_ID &cver= COOKIE_VERSION_NUMBER &google_error= ERROR_ID

Пример макроса

Участник торгов имеет интеграцию сопоставления файлов cookie с конечной точкой, размещенной по https://user.bidder.com.cookies , и для их реализации требуются предустановленные параметры, определенные участником торгов, в дополнение к параметрам сопоставления пикселей в следующем порядке: google_push , google_gid , google_cver , и google_error . Участник торгов может сделать это, установив URL-адрес сопоставления файлов cookie следующим образом:

https://user.bidder.com/cookies?w=0%%GOOGLE_PUSH_PAIR%%&x=1%%GOOGLE_GID_PAIR%%&y=2%%GOOGLE_CVER_PAIR%%&z=3%%GOOGLE_ERROR_PAIR%%

Когда позже Google отправит этому участнику торгов запрос на сопоставление, он будет расширен примерно до следующего вида:

https://user.bidder.com/cookies?w=0&google_push=PUSH_DATA&x=1&google_gid=GOOGLE_GID&y=2&google_cver=1&z=3

Служба сопоставления файлов cookie Google в настоящее время поддерживает три рабочих процесса для различных вариантов использования, которые описаны ниже.

Двунаправленное сопоставление файлов cookie относится к рабочему процессу, инициированному участниками торгов, когда они размещают тег соответствия в браузере пользователя, который направляет его в Google. Этот рабочий процесс позволяет Google и системе назначения ставок заполнять таблицы соответствий. Ниже приведен простой пример этого рабочего процесса.

Шаг 1. Разместите тег совпадения

Чтобы инициировать этот поток, участник торгов должен разместить свой тег соответствия таким образом, чтобы он отображался в браузере пользователя. Простой тег соответствия, возвращающий участнику торгов только идентификатор пользователя Google, может иметь следующую структуру:

<img src="https://cm.g.doubleclick.net/pixel?google_nid=BIDDER_ACCOUNT_NID&google_cm" />

Существуют дополнительные параметры, которые вы можете включить в тег соответствия для выполнения различных вариантов использования. Дополнительные сведения об этих параметрах см. в разделе Параметры URL-адреса тега сопоставления .

Шаг 2. Google отвечает переадресацией, включая данные соответствия.

Тег соответствия приведет к тому, что служба сопоставления файлов cookie Google получит запрос от браузера пользователя, который выдаст перенаправление HTTP 302 на URL сопоставления файлов cookie участника торгов. Перенаправление будет включать параметры запроса с указанием идентификатора пользователя Google и номера его версии в URL-адресе, и участник торгов также получит свой файл cookie, включенный в заголовки запроса. На практике для URL-адреса сопоставления файлов cookie, указанного как https://ad.network.com/pixel , URL-адрес перенаправления для простого тега соответствия, как показано выше, может выглядеть следующим образом:

https://ad.network.com/pixel?google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1

Идентификатор пользователя Google, передаваемый через параметр google_gid , представляет собой строку без дополнений, безопасную для Интернета, в кодировке base64 . Участникам торгов, решившим разместить таблицу соответствия, рекомендуется хранить точную строку, возвращаемую службой сопоставления файлов cookie. В последующих запросах ставок это будет соответствовать значениям, указанным через BidRequest.google_user_id в протоколе Google RTB или BidRequest.user.id в реализации Google OpenRTB.

Версия, указанная в google_cver , указывает числовой номер версии для идентификатора пользователя Google. Идентификатор пользователя Google для данного пользователя будет изменяться нечасто, после чего он будет увеличиваться.

Если Google обнаружит ошибку при обработке вашего запроса на сопоставление, вместо этого будет указан параметр google_error .

Шаг 3. Участник торгов обрабатывает переадресацию и отвечает пикселем

Участник торгов получает перенаправление на соответствующий URL-адрес файла cookie, включая параметры, указанные им на первом этапе, и параметры, предоставленные Google на втором этапе. Кроме того, они также получат свои файлы cookie в заголовках HTTP. Если операция прошла успешно, участник торгов, размещающий собственную таблицу соответствий, мог сопоставить свой файл cookie с идентификатором пользователя Google, включенным в ответ. Участникам торгов рекомендуется хранить точную строку, возвращенную службой сопоставления файлов cookie.

Если операция не удалась, участник аукциона получит параметр google_error в редиректе. Это числовое значение, соответствующее различным состояниям ошибки, которые идентифицируют конкретную возникшую ошибку. Подробнее о возможных значениях ошибок можно узнать здесь . Если вы получили сообщение об ошибке, вы можете попытаться снова сопоставить этого пользователя, разместив новый тег соответствия.

Участник торгов должен всегда отвечать, предоставляя изображение невидимого пикселя 1x1, или, в качестве альтернативы, возвращать ответ HTTP 204 No Content .

Этот рабочий процесс показан на диаграмме ниже, где запросы и ответы представлены стрелкой, а элементы данных, которые сопровождают их, перечислены в скобках.

Сопоставить параметры URL тега

Параметр Описание
google_nid Идентификатор сети (NID) для учетной записи участника торгов. Этот идентификатор можно получить через ресурс Bidders .
google_cm Указывает службе сопоставления файлов cookie Google, что она должна выполнять сопоставление файлов cookie. Значение параметра игнорируется и может быть опущено.
google_sc Этот параметр устарел. Устанавливает файл cookie Google для пользователя, если он отсутствует. Значение параметра игнорируется и может быть опущено. Отсутствие параметра приводит к ошибке, если файл cookie не существует.
google_no_sc Этот параметр устарел. Это указывает службе сопоставления файлов cookie Google, что она не должна устанавливать файл cookie для пользователя, если он отсутствует. Значение параметра игнорируется и может быть опущено.
google_hm

Данные, которые участник торгов хочет сохранить в таблице соответствия, размещенной в Google.

Значение представляет собой безопасную для Интернета строку в кодировке base64 (заполнение необязательно). Необработанные данные должны быть 40 байт или меньше. Например, Q29va2llIHRoYXQgaXMgdW5kZXIgNDAgdG90YWwgYnl0ZXMuLi4u .

google_redir Строка в кодировке URL, которую может указать участник торгов, если он хочет, чтобы Google отправил перенаправление HTTP 302 на закодированный URL для этого тега соответствия. Это позволяет Google быть впереди в цепочке обращений к партнерам. Это приведет к ошибке, если указать без google_hm или с google_cm .
google_ula Строка, используемая для добавления пользователя в существующий список пользователей. Ожидаемый формат значения — userlistid[,timestamp] :
  • userlistid : единый числовой идентификатор списка пользователей.
  • timestamp : необязательная временная метка в формате POSIX, указывающая, когда пользователь был добавлен в список пользователей.

Этот параметр URL-адреса можно повторять, чтобы добавить пользователя в несколько списков.

В дополнение к указанным выше параметрам участники торгов могут указать свои собственные, которые будут добавлены в качестве параметров к URL-адресу перенаправления. Обратите внимание, что определенные участником аукциона параметры с префиксом google_ будут игнорироваться, поскольку они зарезервированы Google для будущего развития, и сохранение порядка параметров не гарантируется. Тег соответствия, включающий параметры, определенные участником аукциона, может выглядеть следующим образом:

<img src="https://cm.g.doubleclick.net/pixel?google_nid=BIDDER_ACCOUNT_NID&google_cm&extra1=xx&extra2=yy" />

Параметры URL-адреса перенаправления

URL-адрес перенаправления создается на основе базового URL-адреса сопоставления файлов cookie, настроенного для учетной записи участника торгов, включая google_ и параметры, определенные участником аукциона, в зависимости от тех, которые указаны в теге соответствия. Определены следующие параметры ответа google_ :

Параметр Описание
google_gid Идентификатор пользователя Google. Устанавливается, если в запросе указан google_cm и запрос прошел успешно.
google_cver Версия куки. Устанавливается, если в запросе указан google_cm и запрос прошел успешно.
google_error

Целочисленное значение, указывающее общую ошибку запроса. При получении указывает на то, что никаких операций не производилось, и никакие другие параметры ответа google_ не будут заданы. Поддерживаемые значения ошибок включают следующее:

  • 1 : у пользователя есть файл cookie Google, но он отказался от отслеживания с помощью этого файла cookie.
  • 2 : Допустимые операции не указаны. например, был получен запрос об отсутствии операций.
  • 3 : у пользователя нет файла cookie Google. Google не будет устанавливать файлы cookie через службу сопоставления файлов cookie.
  • 4 : Определены конфликтующие операции. Вы не можете указать оба флага google_push и google_cm в одном и том же запросе, так как они имеют противоречивые цели.
  • 5 : Недопустимый параметр google_push был передан при перенаправлении на сервер Google как часть двунаправленного запроса сопоставления пикселей. Ваше перенаправление должно установить google_push на то же значение, которое было передано вам в исходном запросе пикселя.
  • 6 : В теге соответствия указан неверный NID.
  • 7 : Обнаружен недействительный файл cookie.
  • 8 : Устарело. Файл cookie не найден.
  • 9 : Файл cookie не найден, сделана попытка установить тестовый файл cookie.
  • 10 : параметр google_redir использовался без указания google_hm или использовался в дополнение к google_cm .
  • 15 : Запрос исходит из региона, где Google требует, чтобы таблица соответствий размещалась в Google. В результате этот ответ не содержит идентификатора пользователя Google. В настоящее время это включено только для небольшого процента трафика, но планируется полностью включить его в июне 2020 года.
google_hm

Появляется только в случае неудачной попытки записи в таблицу соответствия, размещенную в Google. Когда это происходит, его значением является один из следующих кодов состояния:

  • 1 — Запрещено: клиент еще не внесен в белый список для записи записей размещенной таблицы соответствий.
  • 2 - Ошибка декодирования: значение параметра не может быть декодировано.
  • 3 - Слишком длинная полезная нагрузка: значение параметра декодировано более чем в 24 байта данных.
  • 4 - Внутренняя ошибка: произошла внутренняя ошибка при сохранении данных.
  • 5 — Throttled: эта запись не была обработана из-за дросселирования.
google_ula

Статус операции добавления списка пользователей, повторяющейся, если в запросе указано несколько google_ula . Формат:
userlistid,status code

Пример: google_ula=1234567890,0

Операция google_ula может возвращать любой из следующих кодов состояния:

  • 0 - Нет ошибки. Пользователь добавлен в список пользователей.
  • 2 - Отказано в доступе. У вас недостаточно прав для добавления пользователей в указанный список пользователей.
  • 5 - Неправильный идентификатор списка пользователей. Предоставленный идентификатор списка пользователей недействителен.
  • 6 - ID закрытого атрибута. Предоставленный идентификатор списка пользователей закрыт.
  • 10 - Внутренняя ошибка. Служба сопоставления файлов cookie обнаружила внутреннюю ошибку; вы можете попробовать повторно сопоставить пользователя.

В следующих сценариях описывается, как может выглядеть сопоставление файлов cookie для обычного пользователя, просматривающего веб-страницу.

Сценарий 1. Пользователь очищает свои файлы cookie и просматривает сайт.

Джейн очищает их кеш от всех файлов cookie. Затем они посещают домашнюю страницу ExampleNews.com.

Вот что происходит:

  1. ExampleNews.com отображает и вызывает рекламу из Google (Менеджер рекламы).
  2. Поскольку рекламный блок подходит для динамического размещения, Google отправляет запросы ставок FinestDSP и другим участникам торгов через службу ставок в реальном времени.
  3. Приложение FinestDSP для торгов получает и обрабатывает запрос на предложение, а также отправляет ответ на предложение.
  4. Google получает ответы от участников торгов, в том числе ответ FinestDSP, в котором указано объявление с тегом соответствия (пикселем).
  5. FinestDSP выигрывает аукцион. Google показывает объявление FinestDSP и тег соответствия Джейн.
  6. Тег соответствия вызывает службу сопоставления файлов cookie Google, указывая параметры google_nid и google_cm .
  7. Служба сопоставления файлов cookie считывает файл cookie Google Джейн и отправляет браузеру Джейн перенаправление на URL-адрес сопоставления файлов cookie FinestDSP с установленными параметрами google_user_id и google_cver .
  8. Браузер Джейн загружает перенаправление на URL-адрес сопоставления файлов cookie FinestDSP.
  9. Конечная точка сопоставления файлов cookie FinestDSP обрабатывает запрос на перенаправление, который включает параметры URL, установленные Google, и их файлы cookie для Джейн в заголовках HTTP. Теперь FinestDSP может хранить сопоставление своего файла cookie с google_user_id в своей таблице соответствий.
  10. FinestDSP отвечает на перенаправление невидимым пикселем 1x1.
Сценарий 2: Пользователь с существующим сопоставлением

Через неделю после сценария 1 Джейн снова посещает сайт ExampleNews.com. Теперь, когда на компьютере Джейн установлены файлы cookie и системы назначения ставок, и файлы cookie Менеджера рекламы, вот как работает сопоставление.

  1. Веб-страница отображается, в результате чего Google (Менеджер рекламы) запрашивает рекламу, которая будет отображаться на странице.
  2. Во время аукциона объявлений Google отправляет запрос ставки соответствующим участникам торгов, включая FinestDSP.
  3. FinestDSP получает запрос ставки, включая такие сигналы, как google_user_id .
  4. FinestDSP ищет google_user_id в своей таблице соответствий и находит файл cookie, связанный с Джейн, который был создан неделей ранее (в сценарии 1).
  5. На основе информации, связанной с файлом cookie, логика ставок FinestDSP делает ставку на показ и выигрывает аукцион.
  6. Джейн может увидеть рекламу, адаптированную к их интересам на основе информации, которой располагает FinestDSP.

Однонаправленное сопоставление файлов cookie похоже на двунаправленный рабочий процесс, за исключением того, что он изменен таким образом, что только Google размещает и заполняет таблицу соответствия. Это можно использовать в тех случаях, когда участнику торгов не разрешено размещать идентификаторы пользователей Google в своей собственной таблице соответствия. Чтобы использовать этот поток, участники торгов должны разрешить Google разместить таблицу соответствий, больше не могут указывать google_cm в запросах к службе сопоставления файлов cookie Google и, следовательно, не будут получать google_gid для заполнения своей собственной таблицы соответствий. Как только Google установит совпадение для пользователя, участники торгов могут добавить его в списки пользователей, используя свои собственные данные cookie. Точно так же запросы ставок для этих пользователей будут исключать идентификатор пользователя Google, но включать размещенные данные соответствия. Ниже приведен простой пример пересмотренного рабочего процесса.

Чтобы инициировать этот поток, участник торгов должен разместить тег соответствия таким образом, чтобы он отображался в браузере пользователя. В отличие от рабочего процесса для пользователей не из штата США с ограничениями конфиденциальности, тег соответствия должен направлять браузер пользователя на ваш URL-адрес сопоставления файлов cookie. Например, если URL-адрес сопоставления файлов cookie настроен как https://ad.network.com/pixel , это будет выглядеть так:

<img src="https://ad.network.com/pixel" />

При загрузке в браузере пользователя он запрашивает пиксель из URL-адреса сопоставления файлов cookie участника торгов. Этот запрос будет содержать их файл cookie в заголовке HTTP, который необходимо извлечь для следующего шага.

Конечная точка сопоставления файлов cookie участника торгов должна перенаправляться на службу сопоставления файлов cookie Google, включая параметр google_hm , заполненный безопасными для Интернета данными файлов cookie в кодировке base64. URL-адрес перенаправления может выглядеть следующим образом:

https://cm.g.doubleclick.net/pixel?google_nid=BIDDER_ACCOUNT_NID&google_hm=HOSTED_MATCH_DATA

Google получит перенаправление, содержащее указанные вами параметры, помимо файла cookie Google в заголовках HTTP.

Шаг 4. Google показывает пиксель при успешном или ошибочном перенаправлении, если указан URL-адрес отчета.

Если операция сопоставления файлов cookie выполнена успешно или если для аккаунта участника торгов не указан URL-адрес отчета о сопоставлении файлов cookie, Google по умолчанию будет использовать прозрачный пиксель размером 1 x 1, и на этом рабочий процесс завершится. Показы для этого пользователя в последующих запросах ставок будут включать размещенные данные соответствия участника торгов в BidRequest.hosted_match_data для протокола Google или BidRequest.user.buyeruid для реализации Google OpenRTB. Участники торгов также могут заполнять списки пользователей, используя указанные ими размещенные данные о совпадениях.

В противном случае, если произошла ошибка, Google отправит перенаправление на URL-адрес отчета о сопоставлении файлов cookie участника торгов с указанием причины ошибки, указанной в параметре google_error . Если бы URL-адрес отчета о сопоставлении файлов cookie участника торгов был https://ad.network.com/report , URL-адрес перенаправления выглядел бы так:

<img src="https://ad.network.com/report?google_error=ERROR_ID" />

Браузер пользователя будет перенаправлен на URL-адрес отчета о сопоставлении файлов cookie участника торгов, включая причину ошибки (если таковая имеется), указанную Google в параметре google_error . Чтобы узнать больше об интерпретации кода ошибки, см. описание параметра .

Шаг 6. Участник аукциона подает прозрачный пиксель 1 x 1.

Участник торгов должен отобразить прозрачный пиксель размером 1 x 1 в браузере пользователя.

Рабочий процесс по умолчанию для пользователей в штатах США с ограничениями конфиденциальности показан на диаграмме ниже, где запросы и ответы представлены стрелкой, а элементы данных, которые сопровождают их, перечислены в скобках.

Параметр Описание
google_nid Идентификатор сети (NID) для учетной записи участника торгов. Этот идентификатор можно получить через ресурс Bidders .
google_sc Этот параметр устарел. Устанавливает файл cookie Google для пользователя, если он отсутствует. Значение параметра игнорируется и может быть опущено. Отсутствие параметра приводит к ошибке, если файл cookie не существует.
google_no_sc Этот параметр устарел. Это указывает службе сопоставления файлов cookie Google, что она не должна устанавливать файл cookie для пользователя, если он отсутствует. Значение параметра игнорируется и может быть опущено.
google_hm

Содержит данные, которые участник торгов хочет сохранить в таблице соответствия, размещенной в Google.

google_redir Закодированный URL-адрес, который вы хотите, чтобы Google отправил перенаправление HTTP 302. Указанный URL будет получать перенаправления с параметром google_error как для ошибок, так и для успешных операций.
google_ula Строка, используемая для добавления пользователя в существующий список пользователей. Ожидаемый формат значения — userlistid[,timestamp] :
  • userlistid : единый числовой идентификатор списка пользователей.
  • timestamp : необязательная временная метка в формате POSIX, указывающая, когда пользователь был добавлен в список пользователей.

Этот параметр URL-адреса можно повторять, чтобы добавить пользователя в несколько списков.

Параметр Описание
google_error

Целочисленное значение, указывающее общую ошибку запроса. При получении указывает на то, что никаких операций не производилось, и никакие другие параметры ответа google_ не будут заданы. Поддерживаемые значения ошибок включают следующее:

  • 1 : у пользователя есть файл cookie Google, но он отказался от отслеживания с помощью этого файла cookie.
  • 2 : Допустимые операции не указаны. например, был получен запрос об отсутствии операций.
  • 3 : у пользователя нет файла cookie Google. Google не будет устанавливать файлы cookie через службу сопоставления файлов cookie.
  • 4 : Определены конфликтующие операции. Вы не можете указать оба флага google_push и google_cm в одном и том же запросе, так как они имеют противоречивые цели.
  • 5 : Недопустимый параметр google_push был передан при перенаправлении на сервер Google как часть двунаправленного запроса сопоставления пикселей. Ваше перенаправление должно установить google_push на то же значение, которое было передано вам в исходном запросе пикселя.
  • 6 : В теге соответствия указан неверный NID.
  • 7 : Обнаружен недействительный файл cookie.
  • 8 : Устарело. Файл cookie не найден.
  • 9 : Файл cookie не найден, сделана попытка установить тестовый файл cookie.
  • 10 : параметр google_redir использовался без указания google_hm или использовался в дополнение к google_cm .
  • 15 : Запрос исходит из региона, где Google требует, чтобы таблица соответствий размещалась в Google. В результате этот ответ не содержит идентификатора пользователя Google. В настоящее время это включено только для небольшого процента трафика, но планируется полностью включить его в июне 2020 года.

По инициативе Google: двунаправленное сопоставление пикселей

Двунаправленное сопоставление пикселей — это рабочий процесс для службы сопоставления файлов cookie Google, в котором Google пытается сопоставить идентификатор пользователя Google с алгоритмически выбранным участником торгов, отличным от победителя аукциона в режиме реального времени. При размещении объявления Google размещает тег сопоставления, указывающий браузеру пользователя на загрузку прозрачного пикселя из URL-адреса сопоставления файлов cookie выбранного участника торгов. Это позволит как Google, так и участнику торгов заполнить таблицу соответствий данным пользователем. Ниже приведен простой пример этого рабочего процесса.

Шаг 1. Google размещает тег соответствия

Когда страница участвующего издателя загружается в браузере пользователя и рекламное место на этой странице заполняется Google, может быть размещен тег соответствия, который запрашивает пиксель у алгоритмически выбранного участника торгов. Тег Pixel Matching, размещенный Google, объединяет URL-адрес сопоставления файлов cookie участника торгов с дополнительными параметрами, которые участник торгов может использовать для заполнения своей таблицы соответствия. URL-адрес сопоставления файлов cookie, указанный как https://ad.network.com/pixel , имеет следующую структуру:

<img src="https://ad.network.com/pixel?google_gid=GOOGLE_GID&google_cver=1&google_push=PUSH_DATA" />

Участники торгов, получающие запросы на сопоставление пикселей, должны ответить перенаправлением на службу сопоставления файлов cookie Google, которая структурирована следующим образом:

https://cm.g.doubleclick.net/pixel?google_nid=GOOGLE_NID&google_push=PUSH_DATA

Обратите внимание, что приведенный выше URL-адрес перенаправления аналогичен URL-адресу, используемому в теге сопоставления для рабочего процесса сопоставления файлов cookie, инициированного участником торгов . В Pixel Matching параметр google_cm заменяется параметром google_push , и его значение должно быть равно значению, предоставленному Google в запросе. Также аналогично рабочему процессу, инициированному участником торгов, можно указать дополнительные параметры для выполнения дополнительных вариантов использования.

Шаг 3. Google обрабатывает переадресацию и отвечает пикселем

Google регистрирует, что совпадение было создано для пользователя, и обрабатывает любые дополнительные операции, запрошенные через параметры запроса. Наконец, Google отвечает прозрачным пикселем 1x1.

Диаграмма рабочего процесса сопоставления пикселей

Этот рабочий процесс показан на диаграмме ниже, где запросы и ответы представлены стрелкой, а элементы данных, которые сопровождают их, перечислены в скобках.

Параметры запроса тега сопоставления Google

Параметр Описание
google_gid Идентификатор пользователя Google. Для пользователей не из штата США с ограничениями конфиденциальности это всегда будет указано в теге соответствия Google.
google_cver Версия куки. Это всегда будет указано в теге соответствия Google.
google_push Указывает, что этот запрос инициирует рабочий процесс сопоставления пикселей. Значение должно быть возвращено через соответствующий параметр в ответе перенаправления участника торгов.

Bidder Pixel Matching параметры перенаправления

Параметр Описание
google_nid Идентификатор сети (NID) для учетной записи участника торгов. Этот идентификатор можно получить через ресурс Bidders .
google_push Указывает, что это перенаправление завершает рабочий процесс сопоставления пикселей. Здесь необходимо указать значение из соответствующего тега соответствия Google.
google_hm

Содержит данные, которые участник торгов хочет сохранить в таблице соответствия, размещенной в Google.

google_ula Строка, используемая для добавления пользователя в существующий список пользователей. Ожидаемый формат значения — userlistid[,timestamp] :
  • userlistid : единый числовой идентификатор списка пользователей.
  • timestamp : необязательная временная метка в формате POSIX, указывающая, когда пользователь был добавлен в список пользователей.

Этот параметр URL-адреса можно повторять, чтобы добавить пользователя в несколько списков.

По инициативе Google: однонаправленное сопоставление пикселей

Однонаправленное сопоставление пикселей отличается от двунаправленного рабочего процесса тем, что тег соответствия Google не включает параметр, указывающий идентификатор пользователя Google, но продолжает заполнять таблицу соответствия, размещенную в Google. Это можно использовать в тех случаях, когда участнику торгов не разрешено размещать идентификаторы пользователей Google в своей собственной таблице соответствия. Ниже приведен простой пример пересмотренного рабочего процесса.

Шаг 1. Google размещает тег соответствия

Google размещает тег соответствия для автоматически выбранного участника торгов. Тег соответствия включает параметр google_push . Вот пример:

<img src="https://ad.network.com/pixel?google_push=PUSH_DATA" />

Шаг 2. Браузер пользователя запрашивает пиксель с URL-адреса, совпадающего с кулинарией, участника торгов.

Браузер пользователя запрашивает пиксель из URL-адреса сопоставления файлов cookie участника торгов, включая файл cookie участника торгов в заголовках HTTP.

Конечная точка сопоставления файлов cookie участника торгов должна перенаправляться на службу сопоставления файлов cookie Google, включая параметр google_hm , заполненный безопасными для Интернета данными файлов cookie в кодировке base64. URL-адрес перенаправления может выглядеть следующим образом:

https://cm.g.doubleclick.net/pixel?google_nid=BIDDER_ACCOUNT_NID&google_hm=HOSTED_MATCH_DATA&google_push=PUSH_DATA

Google получит перенаправление, содержащее указанные вами параметры, помимо файла cookie Google в заголовках HTTP. If the operation was successful, impressions for this user in subsequent bid requests will include the bidder's hosted match data in BidRequest.hosted_match_data for the Google Protocol, or BidRequest.user.buyeruid for Google's OpenRTB implementation. Bidders can also populate user lists using the hosted match data they specified.

Finally, Google returns a 1x1 transparent pixel to the user's browser.

Open Bidding allows exchanges to use bidder initiated and Google initiated cookie matching workflows, to match a Google User ID with their cookie. Cookie Match Assist (CMA) is an additional feature for exchanges that enables them to build match tables with their own bidders.

  1. When placing an ad, Google algorithmically selects a participating exchange and places a Cookie Match Assist tag that has the following structure:

    <img src="https://ob.exchange.com/pixel?google_gid=GOOGLE_GID&google_cver=1"/>

  2. Google's CMA match tag causes the exchange's Cookie Matching URL to receive a pixel request.

  3. The exchange's Cookie Matching endpoint receives the request, where its own cookie matching service is responsible for matching the user ID with one of its bidders. In the diagram below, the exchange's cookie matching service responds to the user's browser with a redirect to one of its bidder's endpoints.
  4. The bidder receives the request, along with any parameters specified by the exchange to match the user ID with their cookie.

Restrictions

Cap frequency of requests for fresh matches

Bidders are responsible for limiting the number of calls to the Cookie Matching service for users who have a fresh entry in the Google-hosted match table. An entry in the hosted match table may be considered expired in 14 days, after which it can be refreshed.

Respond to all pixel match requests

Bidders using the Pixel Matching workflow are expected to respond to all incoming Pixel Match requests with a response including the google_push parameter. This allows Google to enforce policies by monitoring usage. If a bidder's response rate drops below 90%, Google will throttle the number of Pixel Match requests sent to their account.

Use HTTPS endpoints

It is required that endpoints used in all Cookie Matching workflows use HTTPS.

When responding to a Pixel Match request sent to you over HTTPS, you are required to redirect to the Cookie Matching Service over HTTPS. Likewise, a Cookie Match Assist endpoint that redirects to bidders must also use HTTPS. If you send requests to Google over HTTP more often than once every 2 minutes, the number of match requests sent to your account will be throttled.

Примеры

The examples below illustrate how to use the Cookie Matching service to accomplish specific objectives. Note that unless stated otherwise, it is assumed that the user being acted upon is not from a US state with privacy restrictions.

Populate a bidder-hosted match table

A bidder can use the Cookie Matching workflow to populate their own match table by providing only the google_nid and google_cm parameters in their match tag. This might look like:

<img src="https://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm" />

If the bidder's Cookie Matching URL is set to https://ad.network.com/pixel?id=1 , and the cookie matching operation is successful, the redirect Google sends in response to the bidder's match tag might look like:

https://ad.network.com/pixel?id=1&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1

If the cookie matching operation fails because the user does not have a Google cookie, the response would be:

https://ad.network.com/pixel?id=1&google_error=3

The error code is dependent on the underlying cause of the error. To learn more about possible error codes for the Cookie Matching workflow, see the redirect URL parameters .

Add to single user list

The google_ula parameter can be specified in a bidder's match tag to add the user to a user list with the given ID. If the Google or bidder-hosted match table has a fresh entry for the user, the bidder can place a match tag including the google_nid and google_ula parameters to add the user to the specified list without initiating the full Cookie Matching workflow. See the restrictions on invoking the Cookie Matching Service for more deails. The corresponding match tag may look like:

<img src="https://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345" />

For a successful response, where the bidder's Cookie Matching URL is https://ad.network.com/pixel , Google's redirect URL would be:

https://ad.network.com/pixel?google_ula=12345,0

If there is an overall error— for example, there is no Google cookie for the user— the redirect URL will include the google_error parameter:

  • https://ad.network.com/pixel?google_error=3

If there is an error specifically concerning adding the user to the list, you will receive google_ula in the redirect. Unlike the corresponding match tag parameter, this replaces the timestamp with a status code to indicate the operation's success. For example, if the request failed because the bidder account didn't have access to the specified user list, the redirect URL would be:

https://ad.network.com/pixel?google_ula=12345,2

Add to multiple user lists

Bidders can specify that a user should be added to multple user lists by including multiple google_ula parameters in the match tag. In practice, this may look like:

<img src="https://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345,7654321&google_ula=45678" />

The status of the operation for each user list is similarly reported through distinct google_ula parameters in the redirect:

https://ad.network.com/pixel?google_ula=12345,2&google_ula=45678,0

In the redirect above, we can see that the operation succeeded for the user list with ID 45678 , but failed for user list ID 12345 because the bidder didn't have permission to access it.

To perform cookie matching and add the user to a user list in a single request, a bidder's match tag should include google_cm and google_ula :

<img src="https://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345&google_cm" />

The redirect URL specified by Google would include google_gid , google_cver , and google_ula . This might look like the following:

https://ad.network.com/pixel?id=&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1&google_ula=12345,0

Storing a match in a Google-hosted match table

If a bidder wants to store their cookie data in a Google-hosted match table, and does not intend to store match with the Google User ID in their own match table, their match tag must include the google_hm parameter where its value must be a web-safe base64-encoded string. For a user where the bidder's unencoded cookie data is Cookie number 1! , the encoded value would be Q29va2llIG51bWJlciAxIQ== , which would be used in a match tag like the following:

<img src="https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=Q29va2llIG51bWJlciAxIQ%3D%3D" />

For a successful response, where the bidder's Cookie Matching URL is https://cookie-monster.com/pixel , Google's redirect URL would be:

https://cookie-monster.com/pixel

The google_gid parameter is not in the redirect because the match tag did not include google_cm , and google_hm is not included in successful responses. In future bid requests for impressions for this user, the bidder will receive their hosted match data in BidRequest.hosted_match_data for Google's RTB protocol, or BidRequest.user.buyeruid for Google's OpenRTB implementation.

If the bidder instead used a match tag where the value of google_hm was not base64-encoded—such as chocolate_chunk! —the redirect URL might look like the following:

https://cookie-monster.com/pixel?google_hm=2

The above redirect URL includes a google_hm value of 2 , suggesting that the operation failed because the value could not be decoded.

Bidder and Google-hosted match tables with user lists

If a bidder hosts their own use list in addition to a Google-hosted user list, and wants a single match tag to match both tables and add the user to a given user list, their match tag must include the google_cm , google_hm , and google_ula parameters. If the bidder's cookie data is Cookie number 1! , the encoded value would be Q29va2llIG51bWJlciAxIQ== , which would produce a match tag like the following:

<img src="https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=Q29va2llIG51bWJlciAxIQ%3D%3D&google_cm&google_ula=12345" />

For a successful response, where the bidder's Cookie Matching URL is https://cookie-monster.com/pixel , Google's redirect URL would look like the following:

https://cookie-monster.com/pixel?google_gid=ABCDETC&google_cver=1&google_ula=12345,0

On receiving the redirect, the bidder can match the Google User ID specified in google_gid with their cookie data in their match table. In addition, they can determine that the Google-hosted match table and user list operations were successful. As a consequence, any Pretargeting the bidder configured to target the specified user list ID will now cause the bidder to receive bid requests for impressions from the user. Likewise, in these bid requests, the bidder will receive their hosted match data in BidRequest.hosted_match_data for Google's RTB protocol, or BidRequest.user.buyeruid for Google's OpenRTB implementation.