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

Сопоставление файлов cookie – это функция, которая позволяет сопоставлять файлы cookie (например, идентификатор пользователя, просматривавшего ваш веб-сайт) с соответствующим идентификатором пользователя Google, специфичным для участника торгов, и создавать списки пользователей, которые помогут вам сделать более эффективный выбор ставок. В этом руководстве описаны концепции, используемые в сопоставлении файлов cookie, а также различные рабочие процессы сопоставления файлов 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 укажет BidRequest.user.buyeruid как безопасную для Интернета строку в кодировке Base64.

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

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

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

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

Начиная

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

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

Макросы сопоставления файлов cookie

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

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

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

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

В системе назначения ставок имеется интеграция сопоставления файлов 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

Служба сопоставления файлов cookie Google поддерживает следующие три рабочих процесса.

По инициативе участника торгов: двунаправленное сопоставление файлов cookie

Двунаправленное сопоставление файлов 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.user.id .

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

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

Шаг 3. Система назначения ставок обрабатывает перенаправление и отправляет в ответ пиксель.

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

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

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

Схема рабочего процесса сопоставления файлов cookie

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

Сопоставить параметры 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_ :

Примеры сценариев рабочего процесса сопоставления файлов 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_gid и google_cver .
8. Браузер Джейн загружает перенаправление на URL-адрес соответствия файлов cookie FinestDSP.
9. Конечная точка сопоставления файлов cookie FinestDSP обрабатывает запрос на перенаправление, который включает параметры URL-адреса, установленные Google, и их файлы cookie для Джейн в заголовках HTTP. FinestDSP теперь может хранить сопоставление своего файла cookie с google_gid в своей таблице соответствия.
10. FinestDSP отвечает на перенаправление невидимым пикселем размером 1x1.

Сценарий 2: Пользователь с существующим сопоставлением

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

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

По инициативе участника торгов: однонаправленное сопоставление файлов cookie

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

Шаг 1. Разместите тег соответствия, направленный на URL-адрес сопоставления файлов cookie участника назначения ставок.

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

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

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

Шаг 2. Перенаправление на службу сопоставления файлов cookie Google.

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

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

Шаг 3. Браузер пользователя перенаправляется на службу сопоставления файлов cookie Google.

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

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

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

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

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

Шаг 5. Браузер пользователя перенаправляется на URL-адрес отчета о сопоставлении файлов cookie участника аукциона.

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

Шаг 6. Система назначения ставок показывает прозрачный пиксель 1 x 1.

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

Схема рабочего процесса сопоставления файлов cookie для пользователей из штатов США с ограничениями конфиденциальности

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

Параметры URL-адреса для перенаправления системы назначения ставок на службу сопоставления файлов cookie Google

Параметры URL-адреса для перенаправления Google на URL-адрес отчета о сопоставлении файлов cookie участника аукциона

По инициативе 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" />

Шаг 2. Участник торгов должен ответить перенаправлением на URL-адрес службы сопоставления файлов cookie Google.

Участники торгов, получающие запросы на сопоставление пикселей, должны в ответ перенаправить их в службу сопоставления файлов 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

Параметры перенаправления с сопоставлением пикселей Bidder

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

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

Шаг 1: Google помещает маги

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

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

Шаг 2: Пользовательский браузер запрашивает Pixel от URL -адреса Биддера

Браузер пользователя запрашивает пиксель из URL -адреса Cookie's Cookie's Cookie's Cookie, включая Cookie's Cookie's в заголовках HTTP.

Шаг 3: перенаправление в службу совпадения файлов cookie Google

Конечная точка Cookie's Cookie's 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

Шаг 4: Браузер пользователя перенаправлен на службу соответствия файлов cookie Google

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

Наконец, Google возвращает прозрачный пиксель 1x1 в браузер пользователя.

Помощь в печенье

Открытие торгов позволяет биржам использовать инициированные претенденты , а Google инициировал рабочие процессы Cookie Cookie, чтобы соответствовать идентификатору пользователя Google с их файлом cookie. Cookie Match Assist (CMA) - дополнительная функция для обменов, которая позволяет им создавать столы со спинками со своими участниками.

Как работает помощь в печенье

1. При размещении рекламы Google Алгоритмически выбирает участие обмен и помещает ассистент Cookie Match Assist, который имеет следующую структуру:

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

2. Тег CMA Match от Google заставляет URL -адрес cookie Cookie для получения совпадения файла cookie Exchange.

3. Конечная точка Cookie для Cookie Exchange получает запрос, где его собственная служба соответствия cookie отвечает за сопоставление идентификатора пользователя с одним из его участников. На следующей диаграмме служба соответствия файлов cookie обмена отвечает на браузер пользователя с перенаправлением на одну из конечных точек своего участника.
4. Участник получает запрос вместе с любыми параметрами, указанными в обмене, чтобы соответствовать идентификатору пользователя с их файлом cookie.

Ограничения

Частота CAP запросов на свежие матчи

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

Ответьте на все запросы на совпадение пикселей

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

Используйте https endpoints

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

При ответе на запрос на матч Pixel, отправленный вам по HTTPS, вы должны перенаправить в службу совпадения файлов cookie через HTTPS. Аналогичным образом, конечная точка помощи в печенье, которая перенаправляет участникам торгов, также должна использовать HTTPS. Если вы отправляете запросы в Google через HTTP чаще, чем один раз каждые 2 минуты, количество запросов на совпадение, отправляемых на вашу учетную запись, будет заброшенным.

Требования к согласию пользователя ЕС

Запросы на сопоставление cookie, которые подлежат политике согласия пользователя ЕС в ЕС, должны указывать на согласие конечного пользователя. Такие запросы необходимы, чтобы указать, что согласие было собрано с использованием одного из следующих способов:

• TCFV2: это включает параметры gdpr и gdpr_consent . Для получения подробной информации обратитесь к документации по авторизованным покупателям IAB TCF v2.0 .
• process_consent : объявление о том, что участник получения согласия пользователя получил необходимое согласие.

Примеры

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

Заполнить таблицу матчей с участниками

Ударщик может использовать рабочую процесс Cookie -Matching для заполнения собственной таблицы совпадений, предоставляя только параметры google_nid и google_cm в их теге соответствия. Это может выглядеть:

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

Если URL -адрес для Cookie's Cookie's Satchie's Satchies установлен по адресу https://ad.network.com/pixel?id=1 , а операция по сопоставлению cookie успешна, Google отправляет в ответ на тег совпадения участника участника.

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

Если операция по сопоставлению cookie не удастся, потому что у пользователя нет файла cookie Google, ответ будет:

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

Код ошибки зависит от основной причины ошибки. Чтобы узнать больше о возможных кодах ошибок для рабочего процесса, соответствующего Cookie, см. Параметры Redirect URL -адреса .

Добавить в список пользователей.

Параметр google_ula может быть указан в теге соответствия участника, чтобы добавить пользователя в список пользователей с данным идентификатором. Если таблица соответствия Google или участников, расположенной в размере для участников, имеет свежую запись для пользователя, участник участника может разместить параметры Match, включая параметры google_nid и google_ula , чтобы добавить пользователя в указанный список без инициирования полноценного рабочего процесса Cookie. Смотрите ограничения на вызов услуги по сопоставлению файлов cookie для большего количества Deails. Соответствующий тег совпадения может выглядеть как:

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

Для успешного ответа, где URL -адрес для Cookie's Cookie's Cookie's Satchiess - https://ad.network.com/pixel , URL -адрес Google Redirect будет:

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

Если есть общая ошибка - например, нет никакого Google cookie для пользователя - URL -адрес redirect будет включать параметр google_error :

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

Если есть ошибка, специально касающаяся добавления пользователя в список, вы получите google_ula в перенаправлении. В отличие от соответствующего параметра тега совпадения, это заменяет метку времени на код состояния, чтобы указать успех операции. Например, если запрос не удался, поскольку учетная запись участника торгов не имела доступа к указанному списку пользователей, URL -адрес redirect будет:

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

Добавить в несколько списков пользователей

Участники могут указать, что пользователь должен быть добавлен в несколько списков пользователей, включив несколько параметров google_ula в тег Match. На практике это может выглядеть как:

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

Состояние операции для каждого списка пользователей аналогично сообщается через различные параметры google_ula в перенаправлении:

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

В предыдущем перенаправлении мы видим, что операция была успешной для списка пользователей с ID 45678 , но не удалась для идентификатора списка пользователей 12345 поскольку участник не имел разрешения на него.

Перейдите через рабочий процесс Cookie Matching и добавьте в список пользователей

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

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

URL -адрес redirect, указанный Google, будет включать google_gid , google_cver и google_ula . Это может выглядеть следующим образом:

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

Хранить матч в таблице матчей Google-Host

Если участник торгов хочет сохранить данные своих файлов cookie в таблице совпадений в Google, и не собирается хранить совпадение с идентификатором пользователя Google в их собственной таблице совпадений, их тег соответствия должен включать параметр google_hm , где его значение должно быть строкой, защищенной в Интернете 64. Для пользователя, где некодируемые данные cookie's Data Foodisted Cookie number 1! , кодированное значение будет Q29va2llIG51bWJlciAxIQ== , который будет использоваться в тегке, как следующее:

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

Для успешного ответа, где URL-адреса Cookie's Cookie's Cookie's Matching- https://cookie-monster.com/pixel , URL-адрес Google Redirect будет:

https://cookie-monster.com/pixel

Параметр google_gid не находится в перенаправлении, потому что тег соответствия не включал google_cm , а google_hm не включен в успешные ответы. В будущих запросах на предложение для впечатлений для этого пользователя участник будет получать свои размещенные данные о соответствии в BidRequest.user.buyeruid .

Если участник вместо этого использовал метку совпадения, где значение google_hm не было базовым 64-кодированием-например, chocolate_chunk! - URL перенаправления может выглядеть следующим образом:

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

Предыдущий URL -адрес Redirect включает значение google_hm 2 , что позволяет предположить, что операция не удалась, поскольку значение не может быть декодировано.

Участники и Google-Hosted Match с списками пользователей

Если участник участника размещает свой собственный список использования в дополнение к списку пользователей Google-Hosted и хочет, чтобы один тег соответствия соответствовал обеим таблицам и добавлению пользователя в данный список пользователей, их тег Match должен включать параметры google_cm , google_hm и google_ula . Если данные печенья торговли являются Cookie number 1! , кодированное значение будет Q29va2llIG51bWJlciAxIQ== , который будет создавать тег соответствия, например, следующее:

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

Для успешного ответа, где URL-адреса Cookie's Cookie's Cookie's Matching-https: https://cookie-monster.com/pixel , URL-адрес Google Redirect будет выглядеть следующим образом:

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

При получении перенаправления, участник торгов может соответствовать идентификатору пользователя Google, указанного в google_gid с данными cookie в их таблице соответствия. Кроме того, они могут определить, что таблица матчей Google-Hosted и операции списка пользователей были успешными. Как следствие, любая предварительная предварительная деятельность, настроенная участниками, настраиваемой для нацеливания указанного идентификатора списка пользователей, теперь приведет к тому, что участник участника будет получать запросы на предложение на впечатления от пользователя. Аналогичным образом, в этих запросах заявки участник будет получать свои размещенные данные о соответствии в BidRequest.user.buyeruid .

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

Концепции

Что такое печенье?

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

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

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

Сопоставленные таблицы

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

Матч-таблицы Google-Hosted

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

• Торги в режиме реального времени : в последующих запросах на предложение на впечатления, связанные с пользователем, Google отправит вам данные о размещенном совпадении, которые вы сопоставили с их идентификатором пользователя Google. Google будет указывать BidRequest.user.buyeruid как веб-безопасная строка Base64.

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

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

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

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

Начиная

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

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

Печенье, соответствующие макросам

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

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

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

Макросмер

У торгожа есть интеграция с соответствующей точкой cookie с конечной точкой, размещенной по адресу https://user.bidder.com/cookies , и их реализация требует заданных участников, определяемых участниками, в дополнение к параметрам сопоставления Pixel в следующем порядке: 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" />

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

Шаг 2: Google отвечает с помощью перенаправления, включая данные соответствия

Тег матча приведет к тому, что сервис соответствия файлов cookie Google получит запрос из браузера пользователя, который выпустит HTTP 302 перенаправление на URL -адрес cookie's Cookie's 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.user.id .

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

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

Шаг 3: Пардер обрабатывает перенаправление и отвечает с помощью Pixel

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

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

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

Диаграмма рабочего процесса соответствующего печенья

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

Параметры URL -адреса Match TAG

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

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

Перенаправить параметры URL

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

Сценарии рабочего процесса соответствующего рабочего процесса

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

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

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

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

1. Examplenews.com рендерирует и вызывает рекламу из Google (рекламный менеджер).
2. Поскольку рекламная единица имеет право на динамическое распределение, Google отправляет запросы на предложение FinestDSP и другим участникам торгов через службу торгов в реальном времени.
3. Заявление FinestDSP в заявке на претенденте получает и обрабатывает запрос на предложение и отправляет свой ответ на предложение.
4. Google получает ответы на ставку от участников торгов, включая ответ FinestDSP, который определяет объявление с тегом совпадения (Pixel).
5. FinestDSP выигрывает аукцион. Google обслуживает рекламу FineStDsp и Match Tag для Джейн.
6. Теги Match вызывает службу Cookie Cookie's Cookie, указав параметры google_nid и google_cm .
7. Служба совпадения Cookie читает Jane's Google Cookie и отправляет браузер Джейн перенаправление на URL -файл cookie FinestDSP с набором параметров google_gid и google_cver .
8. Браузер Джейн загружает перенаправление в URL -адрес cookie FinestDSP.
9. FinestDSP Cookie Matching Comploy Process обрабатывает запрос перенаправления, который включает параметры URL, установленные Google, и их файл cookie для Джейн в заголовках HTTP. FinestDSP теперь может сохранить отображение их cookie с google_gid в их столе матча.
10. FinestDSP реагирует на перенаправление невидимым 1х1 пикселем.

Сценарий 2: Пользователь с существующим отображением

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

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

Инициировано участником торгов: однонаправленное соответствие файлов печенья

Однонаправленное сопоставление cookie аналогично двунаправленному рабочему процессу, за исключением того, что он изменен так, что только Google Hosts и заполняет таблицу сочетания. Это может использоваться в случаях, когда участнику претендента не разрешается размещать идентификаторы пользователей Google в своей собственной таблице соответствия. In order to use this flow, bidders must allow Google to host the match table, can no longer specify google_cm in requests to Google's Cookie Matching Service, and will consequently not receive google_gid to populate their own match table. Once Google has established a match for a user, bidders can add them to user lists using their own cookie data. Similarly, bid requests for these users will exclude the Google User ID, but include hosted match data. An example of the revised workflow is summarized in the following steps.

Step 1: Place the match tag directed to bidder's Cookie Matching URL

In order to initiate this flow, a bidder must place a match tag such that it renders in the user's browser. Unlike the workflow for users not from a US state with privacy restrictions, the match tag must direct the user's browser to your Cookie Matching URL. For example, with a Cookie Matching URL configured as https://ad.network.com/pixel , it would look like:

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

When loading in the user's browser, it will request a pixel from the bidder's Cookie Matching URL. This request will contain their cookie in the HTTP header, which should be extracted for the next step.

Step 2: Redirect to Google's Cookie Matching service

The bidder's cookie matching endpoint must redirect to Google's Cookie Matching service, including the google_hm parameter populated with their web-safe base64-encoded cookie data. The redirect URL might look like the following:

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

Step 3: User's browser is redirected to Google's Cookie Matching service

Google will receive a redirect containing the parameters you specified, in addition to Google's cookie in the HTTP headers.

Step 4: Google serves pixel on success or error redirect if report URL specified

If the cookie matching operation is successful—or if no Cookie Matching Report URL has been specified for the bidder's account—Google will serve a 1x1 transparent pixel by default, and the workflow will end here. Impressions for this user in subsequent bid requests will include the bidder's hosted match data in BidRequest.user.buyeruid . Bidders can also populate user lists using the hosted match data they specified.

Otherwise, if an error occurred, Google will send a redirect to the bidder's Cookie Matching Report URL with the cause of the error specified in the google_error parameter. If the bidder's Cookie Matching Report URL were https://ad.network.com/report , the redirect URL would look like:

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

Step 5: User's browser redirects to bidder's Cookie Matching Report URL

The user's browser will redirect to the bidder's Cookie Matching Report URL, including the error reason (if any) specified by Google in the google_error parameter. To learn more about interpreting the error code, see the parameter description .

Step 6: Bidder serves 1x1 transparent pixel

The bidder must respond by serving a 1x1 transparent pixel to the user's browser.

Cookie Matching workflow diagram for users from US states with privacy restrictions

The default workflow for users in US states with privacy restrictions is illustrated by the following diagram, where requests and responses are represented by an arrow, and the data items that accompany them are listed in parentheses.

URL Parameters for bidder redirect to Google's Cookie Matching service

URL Parameters for Google redirect to Bidder's Cookie Matching Report URL

Google-initiated: Bidirectional Pixel Matching

Bidirectional Pixel Matching is a workflow for Google's Cookie Matching Service where Google attempts to match a Google User ID with an algorithmically selected bidder other than the Real-Time Bidding auction winner. When an ad is placed, Google will place a match tag directing the user's browser to load a transparent pixel from the chosen bidder's Cookie Matching URL. This will enable both Google and the bidder to populate a match table with a given user. The following is an example of this workflow.

Step 1: Google places a match tag

When a participating publisher's page loads in the user's browser, and an ad slot on that page is filled by Google, a match tag may be placed that requests a pixel from an algorithmically selected bidder. The Pixel Matching tag placed by Google combines the bidder's Cookie Matching URL with additional parameters the bidder can use to populate their match table. For a Cookie Matching URL specified as https://ad.network.com/pixel , it is structured as follows:

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

Step 2: Bidder must respond with redirect to Google's Cookie Matching Service URL

Bidders receiving pixel matching requests are required to respond with a redirect to Google's Cookie Matching Service that is structured as follows:

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

Note that the preceding redirect URL is similar to that of the URL used in the match tag for the Bidder-Initiated Cookie Matching Workflow . In Pixel Matching, the google_cm parameter is replaced by the google_push parameter, and its value must be equal to the value provided by Google in the request. Also similar to the bidder-initiated workflow, additional parameters can be specified to fulfill additional use cases.

Step 3: Google processes redirect and responds with pixel

Google logs that a match has been created for the user, and handles any additional operations requested through query parameters Finally, Google responds with a 1x1 transparent pixel.

Pixel Matching workflow diagram

This workflow is illustrated by the following diagram, where requests and responses are represented by an arrow, and the data items that accompany them are listed in parentheses.

Google match tag request parameters

Bidder Pixel Matching redirect parameters

Google-initiated: Unidirectional Pixel Matching

Unidirectional Pixel Matching differs from the Bidirectional workflow in that Google's match tag does not include a parameter specifying the Google User ID, but will continue to populate a Google-hosted match table. This can be used in instances where the bidder is not permitted to host Google User IDs in their own match table. An example of the revised workflow is summarized in the following steps.

Step 1: Google places a match tag

Google places a match tag for an algorithmically selected bidder. The match tag includes the google_push parameter. Here's an example:

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

Step 2: User's browser requests pixel from bidder's Cooking Matching URL

The user's browser requests a pixel from the bidder's Cookie Matching URL, including the bidder's cookie in the HTTP headers.

Step 3: Redirect to Google's Cookie Matching Service

The bidder's cookie matching endpoint must redirect to Google's Cookie Matching service, including the google_hm parameter populated with their web-safe base64-encoded cookie data. The redirect URL might look like the following:

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

Step 4: User's browser is redirected to Google's Cookie Matching service

Google will receive a redirect containing the parameters you specified, in addition to Google's cookie in the HTTP headers. If the operation was successful, impressions for this user in subsequent bid requests will include the bidder's hosted match data in BidRequest.user.buyeruid . 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.

Cookie Match Assist

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.

How Cookie Match Assist works

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 following diagram, 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.

Ограничения

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 is less than 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.

EU user consent requirements

Cookie Matching requests that are subject to Google's EU User Consent Policy should indicate end-user consent. Such requests are required to indicate that consent has been gathered using one of the following ways:

• TCFv2: This includes gdpr and gdpr_consent parameters. For details, consult the Authorized Buyers IAB TCF v2.0 documentation .
• process_consent : a declaration that the bidder has obtained necessary user consent.

Примеры

The following examples 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 multiple 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 preceding redirect, 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.

Step through Cookie Matching workflow and add to user list

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

Store 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.user.buyeruid .

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 preceding redirect URL includes a google_hm value of 2 , suggesting that the operation failed because the value couldn't 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.user.buyeruid .

Cookie Matching is a feature that lets you match your cookie—for example, an ID for a user that browsed your website—with a corresponding bidder-specific Google User ID, and construct user lists that can help you make more effective bidding choices. This guide describes concepts used in Cookie Matching, as well as different Cookie Matching workflows, and any variations they may have for certain use cases.

Concepts

What is Cookie Matching?

Domain owners typically set the contents of cookies for users that browse their site, which are used to identify users within that domain. Even if two domain owners would otherwise agree to exchanging this data, the security model of internet browsers restricts one from reading a cookie set by another domain.

In the context of digital advertising, Google identifies users with cookies that belong to the doubleclick.net domain, and bidders participating in Real-Time Bidding may have their own domain where they identify some set of users they would like to show ads. Cookie Matching enables the bidder to match their cookies with Google's, such that they can determine whether an impression sent in a bid request is associated with one of users being targeted, they will receive either their own cookie data or a bidder-specific Google User ID that is an encrypted form of the doubleclick.net cookie in the bid request.

The cookie matching service described in this guide facilitates the creation and maintenance of the association between a bidder's cookie and the Google User ID, and also allows one to populate user lists.

Match tables

A match table can be used to map an ID or other data from one domain to another. Bidders can use the Cookie Matching Service to populate their own match tables by mapping their cookie for a given user to the user's Google User ID, or to populate a match table hosted by Google. Match tables are necessary for a bidder's bidder application to access cookie data for the user being shown the impression.

Google-hosted match tables

For easier maintenance, latency improvements, and access to match data for users in certain regions, it is recommended that you allow Google to host your match table. This lets you specify a web-safe base64-encoded string — hereafter referred to as hosted match data—that will be mapped to the Google User ID for a given user. Once a match has been established, it can be used in the following ways:

• Real-Time Bidding : In subsequent bid requests for impressions associated with the user, Google will send you the hosted match data you matched with their Google User ID. Google will specify BidRequest.user.buyeruid as a web-safe base64-encoded string.

• User Lists : User lists can be populated with either Google User IDs or hosted match data.

• Pretargeting : You can configure your pretargeting such that you only receive bid requests containing hosted match data. This can be used to eliminate less relevant impressions for users outside of your cookie space.

User lists

User lists can be created and managed with the Real-Time Bidding API . Once created, you can populate these lists with the following Cookie Matching workflows, or through the Bulk Uploader Service .

Начиная

In order to get started with Cookie Matching, you must contact your Technical Account Manager, who can enable specific workflows and help you configure the following:

• Cookie Matching Network ID (NID) : A string ID uniquely identifying a bidder account for Cookie Matching and other related operations.
• Cookie Matching URL : The base URL for an endpoint that will accept and handle incoming requests as part of the Cookie Matching workflows. Bidders can embed macros in this URL to control the ordering of parameters passed to it in Cookie Matching workflows.
• Match Tag : The tag you must place in a user's browser for the bidder-initiated Cookie Matching workflow. This can be served alongside ads, or placed on web properties outside of ads.
• Cookie Matching Report URL (optional): In the Unidirectional Cookie Matching Workflow, this is an optional URL that can be provided to specify an endpoint that will receive error details in the event that cookie matching fails through an HTTP 302 redirect. By default, responses will only be sent to this URL if there was an error with the cookie matching operation, but bidder's may request that the redirect always be sent.
• Cookie Match Assist URL : For exchanges implementing the Cookie Match Assist workflow , this is the base URL of the endpoint intended to respond to incoming requests.
• Cookie Match Assist Quota : For exchanges implementing the Cookie Match Assist workflow , this is the maximum number of requests that their Cookie Matching URL can receive every second. This is intended to prevent CMA requests from overloading the exchange's servers with requests.

Cookie matching macros

In any of the supported Cookie Matching workflows , a bidder's Cookie Matching URL typically has parameters appended in a non-guaranteed ordering. Bidders with integrations requiring consistent ordering of parameters can place macros in their Cookie Matching URL to indicate their placement.

Supported macros

Bidders can optionally configure their Cookie Matching URL to include one or more macros in the form of either %%GOOGLE_<PARAM_NAME>%% or %%GOOGLE_<PARAM_NAME>_PAIR%% . The supported macros and their expanded values are:

Macro example

A bidder has a cookie matching integration with an endpoint hosted at https://user.bidder.com/cookies , and their implementation requires preset bidder-defined parameters in addition to Pixel Matching parameters in the following order: google_push , google_gid , google_cver , and google_error . The bidder can accomplish this by setting their Cookie Matching URL to:

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%%

When Google later sends a match request to this bidder, it will be expanded to something like the following:

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 Matching Service workflows

Google's Cookie Matching Service supports the following three workflows.

Bidder-initiated: Bidirectional Cookie Matching

Bidirectional Cookie Matching refers to a bidder-initiated workflow, where they place a match tag in the user's browser that directs it to Google. This workflow allows both Google and the bidder to populate match tables. The following is an example of this workflow.

Step 1: Place the match tag

In order to initiate this flow, the bidder must place their match tag such that it renders in the user's browser. A match tag that only returns the Google User ID to the bidder may be structured as follows:

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

There are additional parameters you can include in the match tag to fulfill different use cases. To learn more about these parameters, see Match Tag URL Parameters .

Step 2: Google responds with redirect including match data

The match tag will cause Google's Cookie Matching Service to receive a request from the user's browser, which will issue an HTTP 302 redirect to the bidder's Cookie Matching URL. The redirect will include query parameters specifying the Google User ID and its version number in the URL, and the bidder will also receive their cookie included in the request headers. In practice, for a cookie matching URL specified as https://ad.network.com/pixel , the redirect URL for the previous match tag could look like the following:

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

The Google User ID passed through the google_gid parameter is an unpadded web-safe base64-encoded string. For bidders choosing to host a match table, it is recommended that they store the exact string returned by the Cookie Matching Service. In subsequent bid requests, this will correspond to values specified through BidRequest.user.id .

The version specified in google_cver indicates the numeric version number for the Google User ID. The Google User ID for a given user will infrequently change, after which this will be incremented.

If Google encounters an error while processing your match request, a google_error parameter will instead be specified.

Step 3: Bidder processes redirect and responds with pixel

The bidder receives a redirect to their cookie matching URL including parameters they specified in the first step, and those Google provided in the second step. In addition, they will also receive their cookie in the HTTP headers. If the operation was successful, a bidder hosting their own match table could match their cookie to the Google User ID included in the response. It is recommended that bidders store the exact string returned by the Cookie Matching Service.

If the operation was unsuccessful, the bidder will receive a google_error parameter in the redirect. This is a numeric value corresponding to different error states that identify the particular error that occurred. You can learn more about the possible error values in the description of the google_error URL parameter. If you receive an error, you may attempt to match for that user again by placing a new match tag.

The bidder must always respond by serving a 1x1 invisible pixel image, or alternatively return an HTTP 204 No Content response.

Cookie Matching workflow diagram

This workflow is illustrated by the following diagram, where requests and responses are represented by an arrow, and the data items that accompany them are listed in parentheses.

Match Tag URL Parameters

In addition to the earlier parameters, bidders may specify their own, which will be appended as parameters to the redirect URL. Note that bidder-defined parameters named with the google_ prefix will be ignored because those are reserved by Google for future development, and preservation of the parameters' ordering is not guaranteed. A match tag including bidder-defined parameters may look like:

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

Redirect URL Parameters

The redirect URL is built from the base Cookie Matching URL configured for a bidder's account, including google_ and bidder-defined parameters depending on those specified in the match tag. The following google_ response parameters are defined:

Cookie Matching workflow example scenarios

The following scenarios describe what cookie matching might look like for a typical user browsing a web page.

Scenario 1: User clears their cookies and browses a site

Jane clears their cache of all cookies. They then visit the homepage of ExampleNews.com.

Here's what happens:

1. ExampleNews.com renders, and calls ads from Google (Ad Manager).
2. Because the ad unit is eligible for dynamic allocation, Google sends bid requests to FinestDSP and other bidders through the Real-Time Bidding service.
3. FinestDSP's bidder application receives and processes the bid request, and sends its bid response.
4. Google receives bid responses from bidders, including FinestDSP's response that specifies an ad with a match tag (pixel).
5. FinestDSP wins the auction. Google serves FinestDSP's ad and match tag to Jane.
6. The match tag calls Google's Cookie Match Service, specifying the google_nid and google_cm parameters.
7. The Cookie Match Service reads Jane's Google cookie, and sends Jane's browser a redirect to FinestDSP's Cookie Matching URL with the google_gid and google_cver parameters set.
8. Jane's browser loads the redirect to FinestDSP's Cookie Match URL.
9. FinestDSP's cookie matching endpoint processes the redirect request, which includes URL parameters set by Google, and their cookie for Jane in the HTTP headers. FinestDSP can now store the mapping of their cookie to the google_gid in their match table.
10. FinestDSP responds to the redirect with an invisible 1x1 pixel.

Scenario 2: User with existing mapping

A week after Scenario 1, Jane visits ExampleNews.com again. Now that Jane has both bidder and Ad Manager cookies on their machine, here's how matching works.

1. The web page renders, causing Google (Ad Manager) to request ads that will be rendered on the page.
2. During the ad auction, Google sends a bid request to applicable bidders, including FinestDSP.
3. FinestDSP receives the bid request, including signals such as the google_gid .
4. FinestDSP looks up the google_gid in its match table, and finds the cookie associated with Jane that was created a week earlier (in Scenario 1).
5. Based on information associated with the cookie, FinestDSP's bidding logic places a bid on the impression, and wins the auction.
6. Jane might see an ad tailored to their interests, based on information that FinestDSP possesses.

Bidder-initiated: Unidirectional Cookie Matching

Unidirectional Cookie Matching is similar to the Bidirectional workflow, except that it is altered such that only Google hosts and populates a match table. This can be used in instances where the bidder is not permitted to host Google User IDs in their own match table. In order to use this flow, bidders must allow Google to host the match table, can no longer specify google_cm in requests to Google's Cookie Matching Service, and will consequently not receive google_gid to populate their own match table. Once Google has established a match for a user, bidders can add them to user lists using their own cookie data. Similarly, bid requests for these users will exclude the Google User ID, but include hosted match data. An example of the revised workflow is summarized in the following steps.

Step 1: Place the match tag directed to bidder's Cookie Matching URL

In order to initiate this flow, a bidder must place a match tag such that it renders in the user's browser. Unlike the workflow for users not from a US state with privacy restrictions, the match tag must direct the user's browser to your Cookie Matching URL. For example, with a Cookie Matching URL configured as https://ad.network.com/pixel , it would look like:

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

When loading in the user's browser, it will request a pixel from the bidder's Cookie Matching URL. This request will contain their cookie in the HTTP header, which should be extracted for the next step.

Step 2: Redirect to Google's Cookie Matching service

The bidder's cookie matching endpoint must redirect to Google's Cookie Matching service, including the google_hm parameter populated with their web-safe base64-encoded cookie data. The redirect URL might look like the following:

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

Step 3: User's browser is redirected to Google's Cookie Matching service

Google will receive a redirect containing the parameters you specified, in addition to Google's cookie in the HTTP headers.

Step 4: Google serves pixel on success or error redirect if report URL specified

If the cookie matching operation is successful—or if no Cookie Matching Report URL has been specified for the bidder's account—Google will serve a 1x1 transparent pixel by default, and the workflow will end here. Impressions for this user in subsequent bid requests will include the bidder's hosted match data in BidRequest.user.buyeruid . Bidders can also populate user lists using the hosted match data they specified.

Otherwise, if an error occurred, Google will send a redirect to the bidder's Cookie Matching Report URL with the cause of the error specified in the google_error parameter. If the bidder's Cookie Matching Report URL were https://ad.network.com/report , the redirect URL would look like:

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

Step 5: User's browser redirects to bidder's Cookie Matching Report URL

The user's browser will redirect to the bidder's Cookie Matching Report URL, including the error reason (if any) specified by Google in the google_error parameter. To learn more about interpreting the error code, see the parameter description .

Step 6: Bidder serves 1x1 transparent pixel

The bidder must respond by serving a 1x1 transparent pixel to the user's browser.

Cookie Matching workflow diagram for users from US states with privacy restrictions

The default workflow for users in US states with privacy restrictions is illustrated by the following diagram, where requests and responses are represented by an arrow, and the data items that accompany them are listed in parentheses.

URL Parameters for bidder redirect to Google's Cookie Matching service

URL Parameters for Google redirect to Bidder's Cookie Matching Report URL

Google-initiated: Bidirectional Pixel Matching

Bidirectional Pixel Matching is a workflow for Google's Cookie Matching Service where Google attempts to match a Google User ID with an algorithmically selected bidder other than the Real-Time Bidding auction winner. When an ad is placed, Google will place a match tag directing the user's browser to load a transparent pixel from the chosen bidder's Cookie Matching URL. This will enable both Google and the bidder to populate a match table with a given user. The following is an example of this workflow.

Step 1: Google places a match tag

When a participating publisher's page loads in the user's browser, and an ad slot on that page is filled by Google, a match tag may be placed that requests a pixel from an algorithmically selected bidder. The Pixel Matching tag placed by Google combines the bidder's Cookie Matching URL with additional parameters the bidder can use to populate their match table. For a Cookie Matching URL specified as https://ad.network.com/pixel , it is structured as follows:

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

Step 2: Bidder must respond with redirect to Google's Cookie Matching Service URL

Bidders receiving pixel matching requests are required to respond with a redirect to Google's Cookie Matching Service that is structured as follows:

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

Note that the preceding redirect URL is similar to that of the URL used in the match tag for the Bidder-Initiated Cookie Matching Workflow . In Pixel Matching, the google_cm parameter is replaced by the google_push parameter, and its value must be equal to the value provided by Google in the request. Also similar to the bidder-initiated workflow, additional parameters can be specified to fulfill additional use cases.

Step 3: Google processes redirect and responds with pixel

Google logs that a match has been created for the user, and handles any additional operations requested through query parameters Finally, Google responds with a 1x1 transparent pixel.

Pixel Matching workflow diagram

This workflow is illustrated by the following diagram, where requests and responses are represented by an arrow, and the data items that accompany them are listed in parentheses.

Google match tag request parameters

Bidder Pixel Matching redirect parameters

Google-initiated: Unidirectional Pixel Matching

Unidirectional Pixel Matching differs from the Bidirectional workflow in that Google's match tag does not include a parameter specifying the Google User ID, but will continue to populate a Google-hosted match table. This can be used in instances where the bidder is not permitted to host Google User IDs in their own match table. An example of the revised workflow is summarized in the following steps.

Step 1: Google places a match tag

Google places a match tag for an algorithmically selected bidder. The match tag includes the google_push parameter. Here's an example:

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

Step 2: User's browser requests pixel from bidder's Cooking Matching URL

The user's browser requests a pixel from the bidder's Cookie Matching URL, including the bidder's cookie in the HTTP headers.

Step 3: Redirect to Google's Cookie Matching Service

The bidder's cookie matching endpoint must redirect to Google's Cookie Matching service, including the google_hm parameter populated with their web-safe base64-encoded cookie data. The redirect URL might look like the following:

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

Step 4: User's browser is redirected to Google's Cookie Matching service

Google will receive a redirect containing the parameters you specified, in addition to Google's cookie in the HTTP headers. If the operation was successful, impressions for this user in subsequent bid requests will include the bidder's hosted match data in BidRequest.user.buyeruid . 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.

Cookie Match Assist

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.

How Cookie Match Assist works

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 following diagram, 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.

Ограничения

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 is less than 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.

EU user consent requirements

Cookie Matching requests that are subject to Google's EU User Consent Policy should indicate end-user consent. Such requests are required to indicate that consent has been gathered using one of the following ways:

• TCFv2: This includes gdpr and gdpr_consent parameters. For details, consult the Authorized Buyers IAB TCF v2.0 documentation .
• process_consent : a declaration that the bidder has obtained necessary user consent.

Примеры

The following examples 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 multiple 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 preceding redirect, 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.

Step through Cookie Matching workflow and add to user list

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

Store 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.user.buyeruid .

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 preceding redirect URL includes a google_hm value of 2 , suggesting that the operation failed because the value couldn't 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.user.buyeruid .

Cookie Matching is a feature that lets you match your cookie—for example, an ID for a user that browsed your website—with a corresponding bidder-specific Google User ID, and construct user lists that can help you make more effective bidding choices. This guide describes concepts used in Cookie Matching, as well as different Cookie Matching workflows, and any variations they may have for certain use cases.

Concepts

What is Cookie Matching?

Domain owners typically set the contents of cookies for users that browse their site, which are used to identify users within that domain. Even if two domain owners would otherwise agree to exchanging this data, the security model of internet browsers restricts one from reading a cookie set by another domain.

In the context of digital advertising, Google identifies users with cookies that belong to the doubleclick.net domain, and bidders participating in Real-Time Bidding may have their own domain where they identify some set of users they would like to show ads. Cookie Matching enables the bidder to match their cookies with Google's, such that they can determine whether an impression sent in a bid request is associated with one of users being targeted, they will receive either their own cookie data or a bidder-specific Google User ID that is an encrypted form of the doubleclick.net cookie in the bid request.

The cookie matching service described in this guide facilitates the creation and maintenance of the association between a bidder's cookie and the Google User ID, and also allows one to populate user lists.

Match tables

A match table can be used to map an ID or other data from one domain to another. Bidders can use the Cookie Matching Service to populate their own match tables by mapping their cookie for a given user to the user's Google User ID, or to populate a match table hosted by Google. Match tables are necessary for a bidder's bidder application to access cookie data for the user being shown the impression.

Google-hosted match tables

For easier maintenance, latency improvements, and access to match data for users in certain regions, it is recommended that you allow Google to host your match table. This lets you specify a web-safe base64-encoded string — hereafter referred to as hosted match data—that will be mapped to the Google User ID for a given user. Once a match has been established, it can be used in the following ways:

• Real-Time Bidding : In subsequent bid requests for impressions associated with the user, Google will send you the hosted match data you matched with their Google User ID. Google will specify BidRequest.user.buyeruid as a web-safe base64-encoded string.

• User Lists : User lists can be populated with either Google User IDs or hosted match data.

• Pretargeting : You can configure your pretargeting such that you only receive bid requests containing hosted match data. This can be used to eliminate less relevant impressions for users outside of your cookie space.

User lists

User lists can be created and managed with the Real-Time Bidding API . Once created, you can populate these lists with the following Cookie Matching workflows, or through the Bulk Uploader Service .

Начиная

In order to get started with Cookie Matching, you must contact your Technical Account Manager, who can enable specific workflows and help you configure the following:

• Cookie Matching Network ID (NID) : A string ID uniquely identifying a bidder account for Cookie Matching and other related operations.
• Cookie Matching URL : The base URL for an endpoint that will accept and handle incoming requests as part of the Cookie Matching workflows. Bidders can embed macros in this URL to control the ordering of parameters passed to it in Cookie Matching workflows.
• Match Tag : The tag you must place in a user's browser for the bidder-initiated Cookie Matching workflow. This can be served alongside ads, or placed on web properties outside of ads.
• Cookie Matching Report URL (optional): In the Unidirectional Cookie Matching Workflow, this is an optional URL that can be provided to specify an endpoint that will receive error details in the event that cookie matching fails through an HTTP 302 redirect. By default, responses will only be sent to this URL if there was an error with the cookie matching operation, but bidder's may request that the redirect always be sent.
• Cookie Match Assist URL : For exchanges implementing the Cookie Match Assist workflow , this is the base URL of the endpoint intended to respond to incoming requests.
• Cookie Match Assist Quota : For exchanges implementing the Cookie Match Assist workflow , this is the maximum number of requests that their Cookie Matching URL can receive every second. This is intended to prevent CMA requests from overloading the exchange's servers with requests.

Cookie matching macros

In any of the supported Cookie Matching workflows , a bidder's Cookie Matching URL typically has parameters appended in a non-guaranteed ordering. Bidders with integrations requiring consistent ordering of parameters can place macros in their Cookie Matching URL to indicate their placement.

Supported macros

Bidders can optionally configure their Cookie Matching URL to include one or more macros in the form of either %%GOOGLE_<PARAM_NAME>%% or %%GOOGLE_<PARAM_NAME>_PAIR%% . The supported macros and their expanded values are:

Macro example

A bidder has a cookie matching integration with an endpoint hosted at https://user.bidder.com/cookies , and their implementation requires preset bidder-defined parameters in addition to Pixel Matching parameters in the following order: google_push , google_gid , google_cver , and google_error . The bidder can accomplish this by setting their Cookie Matching URL to:

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%%

When Google later sends a match request to this bidder, it will be expanded to something like the following:

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 Matching Service workflows

Google's Cookie Matching Service supports the following three workflows.

Bidder-initiated: Bidirectional Cookie Matching

Bidirectional Cookie Matching refers to a bidder-initiated workflow, where they place a match tag in the user's browser that directs it to Google. This workflow allows both Google and the bidder to populate match tables. The following is an example of this workflow.

Step 1: Place the match tag

In order to initiate this flow, the bidder must place their match tag such that it renders in the user's browser. A match tag that only returns the Google User ID to the bidder may be structured as follows:

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

There are additional parameters you can include in the match tag to fulfill different use cases. To learn more about these parameters, see Match Tag URL Parameters .

Step 2: Google responds with redirect including match data

The match tag will cause Google's Cookie Matching Service to receive a request from the user's browser, which will issue an HTTP 302 redirect to the bidder's Cookie Matching URL. The redirect will include query parameters specifying the Google User ID and its version number in the URL, and the bidder will also receive their cookie included in the request headers. In practice, for a cookie matching URL specified as https://ad.network.com/pixel , the redirect URL for the previous match tag could look like the following:

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

The Google User ID passed through the google_gid parameter is an unpadded web-safe base64-encoded string. For bidders choosing to host a match table, it is recommended that they store the exact string returned by the Cookie Matching Service. In subsequent bid requests, this will correspond to values specified through BidRequest.user.id .

The version specified in google_cver indicates the numeric version number for the Google User ID. The Google User ID for a given user will infrequently change, after which this will be incremented.

If Google encounters an error while processing your match request, a google_error parameter will instead be specified.

Step 3: Bidder processes redirect and responds with pixel

The bidder receives a redirect to their cookie matching URL including parameters they specified in the first step, and those Google provided in the second step. In addition, they will also receive their cookie in the HTTP headers. If the operation was successful, a bidder hosting their own match table could match their cookie to the Google User ID included in the response. It is recommended that bidders store the exact string returned by the Cookie Matching Service.

If the operation was unsuccessful, the bidder will receive a google_error parameter in the redirect. This is a numeric value corresponding to different error states that identify the particular error that occurred. You can learn more about the possible error values in the description of the google_error URL parameter. If you receive an error, you may attempt to match for that user again by placing a new match tag.

The bidder must always respond by serving a 1x1 invisible pixel image, or alternatively return an HTTP 204 No Content response.

Cookie Matching workflow diagram

This workflow is illustrated by the following diagram, where requests and responses are represented by an arrow, and the data items that accompany them are listed in parentheses.

Match Tag URL Parameters

In addition to the earlier parameters, bidders may specify their own, which will be appended as parameters to the redirect URL. Note that bidder-defined parameters named with the google_ prefix will be ignored because those are reserved by Google for future development, and preservation of the parameters' ordering is not guaranteed. A match tag including bidder-defined parameters may look like:

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

Redirect URL Parameters

The redirect URL is built from the base Cookie Matching URL configured for a bidder's account, including google_ and bidder-defined parameters depending on those specified in the match tag. The following google_ response parameters are defined:

Cookie Matching workflow example scenarios

The following scenarios describe what cookie matching might look like for a typical user browsing a web page.

Scenario 1: User clears their cookies and browses a site

Jane clears their cache of all cookies. They then visit the homepage of ExampleNews.com.

Here's what happens:

1. ExampleNews.com renders, and calls ads from Google (Ad Manager).
2. Because the ad unit is eligible for dynamic allocation, Google sends bid requests to FinestDSP and other bidders through the Real-Time Bidding service.
3. FinestDSP's bidder application receives and processes the bid request, and sends its bid response.
4. Google receives bid responses from bidders, including FinestDSP's response that specifies an ad with a match tag (pixel).
5. FinestDSP wins the auction. Google serves FinestDSP's ad and match tag to Jane.
6. The match tag calls Google's Cookie Match Service, specifying the google_nid and google_cm parameters.
7. The Cookie Match Service reads Jane's Google cookie, and sends Jane's browser a redirect to FinestDSP's Cookie Matching URL with the google_gid and google_cver parameters set.
8. Jane's browser loads the redirect to FinestDSP's Cookie Match URL.
9. FinestDSP's cookie matching endpoint processes the redirect request, which includes URL parameters set by Google, and their cookie for Jane in the HTTP headers. FinestDSP can now store the mapping of their cookie to the google_gid in their match table.
10. FinestDSP responds to the redirect with an invisible 1x1 pixel.

Scenario 2: User with existing mapping

A week after Scenario 1, Jane visits ExampleNews.com again. Now that Jane has both bidder and Ad Manager cookies on their machine, here's how matching works.

1. The web page renders, causing Google (Ad Manager) to request ads that will be rendered on the page.
2. During the ad auction, Google sends a bid request to applicable bidders, including FinestDSP.
3. FinestDSP receives the bid request, including signals such as the google_gid .
4. FinestDSP looks up the google_gid in its match table, and finds the cookie associated with Jane that was created a week earlier (in Scenario 1).
5. Based on information associated with the cookie, FinestDSP's bidding logic places a bid on the impression, and wins the auction.
6. Jane might see an ad tailored to their interests, based on information that FinestDSP possesses.

Bidder-initiated: Unidirectional Cookie Matching

Unidirectional Cookie Matching is similar to the Bidirectional workflow, except that it is altered such that only Google hosts and populates a match table. This can be used in instances where the bidder is not permitted to host Google User IDs in their own match table. In order to use this flow, bidders must allow Google to host the match table, can no longer specify google_cm in requests to Google's Cookie Matching Service, and will consequently not receive google_gid to populate their own match table. Once Google has established a match for a user, bidders can add them to user lists using their own cookie data. Similarly, bid requests for these users will exclude the Google User ID, but include hosted match data. An example of the revised workflow is summarized in the following steps.

Step 1: Place the match tag directed to bidder's Cookie Matching URL

In order to initiate this flow, a bidder must place a match tag such that it renders in the user's browser. Unlike the workflow for users not from a US state with privacy restrictions, the match tag must direct the user's browser to your Cookie Matching URL. For example, with a Cookie Matching URL configured as https://ad.network.com/pixel , it would look like:

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

When loading in the user's browser, it will request a pixel from the bidder's Cookie Matching URL. This request will contain their cookie in the HTTP header, which should be extracted for the next step.

Step 2: Redirect to Google's Cookie Matching service

The bidder's cookie matching endpoint must redirect to Google's Cookie Matching service, including the google_hm parameter populated with their web-safe base64-encoded cookie data. The redirect URL might look like the following:

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

Step 3: User's browser is redirected to Google's Cookie Matching service

Google will receive a redirect containing the parameters you specified, in addition to Google's cookie in the HTTP headers.

Step 4: Google serves pixel on success or error redirect if report URL specified

If the cookie matching operation is successful—or if no Cookie Matching Report URL has been specified for the bidder's account—Google will serve a 1x1 transparent pixel by default, and the workflow will end here. Impressions for this user in subsequent bid requests will include the bidder's hosted match data in BidRequest.user.buyeruid . Bidders can also populate user lists using the hosted match data they specified.

Otherwise, if an error occurred, Google will send a redirect to the bidder's Cookie Matching Report URL with the cause of the error specified in the google_error parameter. If the bidder's Cookie Matching Report URL were https://ad.network.com/report , the redirect URL would look like:

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

Step 5: User's browser redirects to bidder's Cookie Matching Report URL

The user's browser will redirect to the bidder's Cookie Matching Report URL, including the error reason (if any) specified by Google in the google_error parameter. To learn more about interpreting the error code, see the parameter description .

Step 6: Bidder serves 1x1 transparent pixel

The bidder must respond by serving a 1x1 transparent pixel to the user's browser.

Cookie Matching workflow diagram for users from US states with privacy restrictions

The default workflow for users in US states with privacy restrictions is illustrated by the following diagram, where requests and responses are represented by an arrow, and the data items that accompany them are listed in parentheses.

URL Parameters for bidder redirect to Google's Cookie Matching service

URL Parameters for Google redirect to Bidder's Cookie Matching Report URL

Google-initiated: Bidirectional Pixel Matching

Bidirectional Pixel Matching is a workflow for Google's Cookie Matching Service where Google attempts to match a Google User ID with an algorithmically selected bidder other than the Real-Time Bidding auction winner. When an ad is placed, Google will place a match tag directing the user's browser to load a transparent pixel from the chosen bidder's Cookie Matching URL. This will enable both Google and the bidder to populate a match table with a given user. The following is an example of this workflow.

Step 1: Google places a match tag

When a participating publisher's page loads in the user's browser, and an ad slot on that page is filled by Google, a match tag may be placed that requests a pixel from an algorithmically selected bidder. The Pixel Matching tag placed by Google combines the bidder's Cookie Matching URL with additional parameters the bidder can use to populate their match table. For a Cookie Matching URL specified as https://ad.network.com/pixel , it is structured as follows:

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

Step 2: Bidder must respond with redirect to Google's Cookie Matching Service URL

Bidders receiving pixel matching requests are required to respond with a redirect to Google's Cookie Matching Service that is structured as follows:

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

Note that the preceding redirect URL is similar to that of the URL used in the match tag for the Bidder-Initiated Cookie Matching Workflow . In Pixel Matching, the google_cm parameter is replaced by the google_push parameter, and its value must be equal to the value provided by Google in the request. Also similar to the bidder-initiated workflow, additional parameters can be specified to fulfill additional use cases.

Step 3: Google processes redirect and responds with pixel

Google logs that a match has been created for the user, and handles any additional operations requested through query parameters Finally, Google responds with a 1x1 transparent pixel.

Pixel Matching workflow diagram

This workflow is illustrated by the following diagram, where requests and responses are represented by an arrow, and the data items that accompany them are listed in parentheses.

Google match tag request parameters

Bidder Pixel Matching redirect parameters

Google-initiated: Unidirectional Pixel Matching

Unidirectional Pixel Matching differs from the Bidirectional workflow in that Google's match tag does not include a parameter specifying the Google User ID, but will continue to populate a Google-hosted match table. This can be used in instances where the bidder is not permitted to host Google User IDs in their own match table. An example of the revised workflow is summarized in the following steps.

Step 1: Google places a match tag

Google places a match tag for an algorithmically selected bidder. The match tag includes the google_push parameter. Here's an example:

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

Step 2: User's browser requests pixel from bidder's Cooking Matching URL

The user's browser requests a pixel from the bidder's Cookie Matching URL, including the bidder's cookie in the HTTP headers.

Step 3: Redirect to Google's Cookie Matching Service

The bidder's cookie matching endpoint must redirect to Google's Cookie Matching service, including the google_hm parameter populated with their web-safe base64-encoded cookie data. The redirect URL might look like the following:

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

Step 4: User's browser is redirected to Google's Cookie Matching service

Google will receive a redirect containing the parameters you specified, in addition to Google's cookie in the HTTP headers. If the operation was successful, impressions for this user in subsequent bid requests will include the bidder's hosted match data in BidRequest.user.buyeruid . 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.

Cookie Match Assist

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.

How Cookie Match Assist works

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 following diagram, 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.

Ограничения

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 is less than 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.

EU user consent requirements

Cookie Matching requests that are subject to Google's EU User Consent Policy should indicate end-user consent. Such requests are required to indicate that consent has been gathered using one of the following ways:

• TCFv2: This includes gdpr and gdpr_consent parameters. For details, consult the Authorized Buyers IAB TCF v2.0 documentation .
• process_consent : a declaration that the bidder has obtained necessary user consent.

Примеры

The following examples 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 multiple 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 preceding redirect, 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.

Step through Cookie Matching workflow and add to user list

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

Store 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.user.buyeruid .

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 preceding redirect URL includes a google_hm value of 2 , suggesting that the operation failed because the value couldn't 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.user.buyeruid .