Correspondência de cookie

A correspondência de cookie é um recurso que permite comparar seu cookie, por exemplo, um ID de um usuário que navegou no seu site, com um ID do usuário do Google específico ao bidder correspondente e criar listas de usuários que ajudam a fazer escolhas de lance mais eficientes. Este guia descreve os conceitos usados na correspondência de cookies, além de diferentes fluxos de trabalho de correspondência de cookies e variações que eles podem ter para determinados casos de uso.

Conceitos

Os proprietários de domínio geralmente definem o conteúdo dos cookies para usuários que navegam no site deles, que são usados para identificar usuários nesse domínio. Mesmo que dois proprietários de domínio concordem em trocar esses dados, o modelo de segurança dos navegadores de Internet impede que um leia um cookie definido por outro domínio.

No contexto da publicidade digital, o Google identifica os usuários com cookies que pertencem ao domínio doubleclick.net, e os bidders que participam do leilão em tempo real podem ter um domínio próprio em que identificam um conjunto de usuários para quem querem mostrar anúncios. A correspondência de cookies permite que o bidder faça a correspondência dos cookies dele com os do Google, para que ele possa determinar se uma impressão enviada em uma solicitação de lance está associada a um dos usuários segmentados. Ele vai receber os próprios dados de cookie ou um ID de usuário do Google específico do bidder, que é uma forma criptografada do cookie doubleclick.net na solicitação de lance.

O serviço de correspondência de cookies descrito neste guia facilita a criação e a manutenção da associação entre o cookie de um bidder e o ID do usuário do Google, além de permitir o preenchimento de listas de usuários.

Tabelas de correspondências

Uma tabela de correspondência pode ser usada para mapear um ID ou outros dados de um domínio para outro. Os bidders podem usar o serviço de correspondência de cookie para preencher as próprias tabelas de correspondência mapeando o cookie de um determinado usuário para o ID de usuário do Google dele ou para preencher uma tabela de correspondência hospedada pelo Google. As tabelas de correspondência são necessárias para que o aplicativo de um bidder acesse os dados de cookies do usuário que está recebendo a impressão.

Tabelas de correspondências hospedadas pelo Google

Para facilitar a manutenção, melhorar a latência e acessar dados de correspondência para usuários em determinadas regiões, recomendamos que você permita que o Google hospede sua tabela de correspondência. Isso permite especificar uma string codificada em base64 segura para a Web, daqui em diante chamada de dados de correspondência hospedados, que será mapeada para o ID do usuário do Google de um determinado usuário. Depois que uma correspondência é estabelecida, ela pode ser usada das seguintes maneiras:

  • Lances em tempo real: em solicitações de lances subsequentes para impressões associadas ao usuário, o Google vai enviar os dados de correspondência hospedados que você associou ao ID de usuário do Google dele. O Google vai especificar BidRequest.user.buyeruid como uma string codificada em base64 e segura para a Web.

  • Listas de usuários: podem ser preenchidas com IDs de usuário do Google ou dados de correspondência hospedados.

  • Pré-segmentação: é possível configurar a pré-segmentação para receber apenas solicitações de lance que contenham dados de correspondência hospedados. Isso pode ser usado para eliminar impressões menos relevantes para usuários fora do seu espaço de cookies.

Listas de usuários

As listas de usuários podem ser criadas e gerenciadas com a API de lances em tempo real. Depois de criadas, é possível preencher essas listas com os seguintes fluxos de trabalho de correspondência de cookies ou pelo serviço de upload em massa.

Primeiros passos

Para começar a usar a correspondência de cookies, entre em contato com seu gerente técnico de contas, que pode ativar fluxos de trabalho específicos e ajudar você a configurar o seguinte:

  • ID da rede de correspondência de cookie (NID): um ID de string que identifica exclusivamente uma conta de bidder para a correspondência de cookies e outras operações relacionadas.
  • URL de correspondência de cookie: é o URL base para um endpoint que aceita e processa as solicitações recebidas como parte dos fluxos de trabalho de correspondência de cookie. Os bidders podem incorporar macros nesse URL para controlar a ordem dos parâmetros transmitidos a ele nos fluxos de trabalho de correspondência de cookies.
  • Tag de correspondência: a tag que você precisa colocar no navegador de um usuário para o fluxo de trabalho de correspondência de cookie iniciada pelo bidder. Ele pode ser veiculado com anúncios ou colocado em propriedades da Web fora dos anúncios.
  • URL do relatório de correspondência de cookies (opcional): no fluxo de trabalho unidirecional de correspondência de cookies, é um URL opcional que pode ser usado para especificar um endpoint que recebe detalhes do erro no caso de falhas na correspondência de cookies por um redirecionamento HTTP 302. Por padrão, as respostas só serão enviadas para esse URL se houver um erro na operação de correspondência de cookies, mas os bidders podem solicitar que o redirecionamento seja sempre enviado.
  • URL de assistência à correspondência de cookies: para trocas que implementam o fluxo de trabalho de assistência à correspondência de cookies, esse é o URL base do endpoint destinado a responder às solicitações recebidas.
  • Cota de assistência de correspondência de cookie: para trocas que implementam o fluxo de trabalho de assistência de correspondência de cookie, esse é o número máximo de solicitações que o URL de correspondência de cookie pode receber por segundo. Isso evita que as solicitações da CMA sobrecarreguem os servidores da exchange.
.

Em qualquer um dos fluxos de trabalho de correspondência de cookies compatíveis, o URL de correspondência de cookies de um bidder geralmente tem parâmetros anexados em uma ordem não garantida. Os bidders com integrações que exigem uma ordenação consistente de parâmetros podem colocar macros no URL de correspondência de cookie para indicar a posição.

Macros com suporte

Os bidders podem configurar o URL de correspondência de cookies para incluir uma ou mais macros na forma de %%GOOGLE_<PARAM_NAME>%% ou %%GOOGLE_<PARAM_NAME>_PAIR%%. As macros compatíveis e os valores expandidos delas são:

Macro Valor ampliado
GOOGLE_GID GOOGLE_USER_ID
GOOGLE_GID_PAIR &google_gid=GOOGLE_USER_ID
GOOGLE_CVER COOKIE_VERSION_NUMBER
GOOGLE_CVER_PAIR &cver=COOKIE_VERSION_NUMBER
GOOGLE_ERROR ERROR_ID
GOOGLE_ERROR_PAIR &google_error=ERROR_ID
GOOGLE_PUSH PIXEL_MATCH_DATA
GOOGLE_PUSH_PAIR &google_push=PIXEL_MATCH_DATA
GOOGLE_ALL_PARAMS google_gid=GOOGLE_USER_ID&cver=COOKIE_VERSION_NUMBER&google_error=ERROR_ID

Exemplo de macro

Um bidder tem uma integração de correspondência de cookies com um endpoint hospedado em https://user.bidder.com/cookies, e a implementação dele exige parâmetros predefinidos definidos pelo bidder, além de parâmetros de correspondência de pixel na seguinte ordem: google_push, google_gid, google_cver e google_error. Para isso, o proponente precisa definir o URL de correspondência de cookie como:

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

Quando o Google enviar uma solicitação de correspondência a esse bidder, ela será expandida para algo como:

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

O serviço de correspondência de cookies do Google é compatível com os três fluxos de trabalho a seguir.

A correspondência de cookies bidirecional se refere a um fluxo de trabalho iniciado por um bidder, em que ele coloca uma tag de correspondência no navegador do usuário que o direciona ao Google. Esse fluxo de trabalho permite que o Google e o bidder preencham tabelas de correspondência. Confira a seguir um exemplo desse fluxo de trabalho.

Etapa 1: inserir a tag de correspondência

Para iniciar esse fluxo, o bidder precisa colocar a tag de correspondência de forma que ela seja renderizada no navegador do usuário. Uma tag de correspondência que retorna apenas o ID do usuário do Google ao bidder pode ser estruturada da seguinte maneira:

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

Há outros parâmetros que você pode incluir na tag de correspondência para atender a diferentes casos de uso. Para saber mais sobre esses parâmetros, consulte Parâmetros de URL da tag de correspondência.

Etapa 2: o Google responde com um redirecionamento que inclui dados de correspondência

A tag de correspondência faz com que o serviço de correspondência de cookies do Google receba uma solicitação do navegador do usuário, que emite um redirecionamento HTTP 302 para o URL de correspondência de cookies do bidder. O redirecionamento vai incluir parâmetros de consulta especificando o ID do usuário do Google e o número da versão no URL. Além disso, o bidder vai receber o cookie dele incluído nos cabeçalhos da solicitação. Na prática, para um URL de correspondência de cookie especificado como https://ad.network.com/pixel, o URL de redirecionamento da tag de correspondência anterior pode ter esta aparência:

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

O ID do usuário do Google transmitido pelo parâmetro google_gid é uma string codificada em base64 segura para a Web e sem padding. Para bidders que optarem por hospedar uma tabela de correspondência, é recomendável que eles armazenem a string exata retornada pelo serviço de correspondência de cookies. Em solicitações de lance subsequentes, isso vai corresponder aos valores especificados por BidRequest.user.id.

A versão especificada em google_cver indica o número da versão numérica do ID de usuário do Google. O ID do usuário do Google para um determinado usuário muda com pouca frequência, e depois disso é incrementado.

Se o Google encontrar um erro ao processar sua solicitação de correspondência, um parâmetro google_error será especificado.

Etapa 3: o bidder processa o redirecionamento e responde com o pixel

O bidder recebe um redirecionamento para o URL de correspondência de cookies, incluindo os parâmetros especificados na primeira etapa e os fornecidos pelo Google na segunda. Além disso, eles também vão receber o cookie nos cabeçalhos HTTP. Se a operação for bem-sucedida, um bidder que hospeda a própria tabela de correspondência poderá corresponder o cookie ao ID do usuário do Google incluído na resposta. Recomendamos que os bidders armazenem a string exata retornada pelo serviço de correspondência de cookies.

Se a operação não for bem-sucedida, o bidder vai receber um parâmetro google_error no redirecionamento. Esse é um valor numérico correspondente a diferentes estados de erro que identificam o erro específico que ocorreu. Saiba mais sobre os possíveis valores de erro na descrição do parâmetro de URL google_error. Se você receber um erro, tente fazer a correspondência para esse usuário novamente colocando uma nova tag de correspondência.

O bidder sempre precisa responder veiculando uma imagem de pixel invisível 1x1 ou, alternativamente, retornar uma resposta HTTP 204 Sem conteúdo.

Esse fluxo de trabalho é ilustrado no diagrama a seguir, em que solicitações e respostas são representadas por uma seta, e os itens de dados que as acompanham são listados entre parênteses.

Corresponder parâmetros de URL da tag

Parâmetro Descrição
google_nid ID da rede (NID) da conta do bidder. Esse ID pode ser recuperado pelo recurso Bidders.
google_cm Indica ao serviço de correspondência de cookie do Google que ele precisa realizar a correspondência de cookie. O valor do parâmetro é ignorado e pode ser omitido.
google_sc Este parâmetro foi descontinuado. Define o cookie do Google para o usuário, se não houver um. O valor do parâmetro é ignorado e pode ser omitido. Se o parâmetro for omitido, ocorrerá um erro se não houver cookie.
google_no_sc Este parâmetro foi descontinuado. Isso indica ao serviço de correspondência de cookies do Google que ele não deve definir um cookie para o usuário se um não estiver presente. O valor do parâmetro é ignorado e pode ser omitido.
google_hm

Dados que o bidder quer armazenar em uma tabela de correspondência hospedada pelo Google.

O valor é uma string codificada em base64 segura para a Web (o padding é opcional). Os dados brutos precisam ter 40 bytes ou menos. Por exemplo, Q29va2llIHRoYXQgaXMgdW5kZXIgNDAgdG90YWwgYnl0ZXMuLi4u.
google_redir Uma string codificada por URL que um bidder pode especificar se quiser direcionar o Google para enviar o redirecionamento HTTP 302 ao URL codificado para essa tag de correspondência. Isso permite que o Google seja colocado na frente em uma chamada encadeada para parceiros. Isso vai resultar em um erro se for especificado sem google_hm ou com google_cm.
google_ula Uma string usada para adicionar o usuário a uma lista de usuários. O formato esperado do valor é userlistid[,timestamp]:
  • userlistid: um único ID numérico de lista de usuários.
  • timestamp: um carimbo de data/hora opcional no formato POSIX, indica quando o usuário foi adicionado à lista de usuários.

Esse parâmetro de URL pode ser repetido para adicionar o usuário a várias listas.
gdpr Indica que a solicitação está sujeita às restrições do GDPR sobre o uso de dados. Para mais detalhes, consulte Requisitos de consentimento do usuário da UE ou Impacto na qualificação da correspondência de cookies na documentação da TCF v2.0 do IAB do Authorized Buyers.

Exemplo: gdpr=1
gdpr_consent Uma string de TC que representa o consentimento do usuário final. Para mais detalhes, consulte Requisitos de consentimento do usuário da UE ou Como a string de TC será transmitida? na documentação da TCF v2.0 do IAB do Authorized Buyers.
process_consent Indica que o bidder recebeu o consentimento do usuário final para os usos de dados especificados na Política de consentimento de usuários da União Europeia do Google.

Se a solicitação não estiver sujeita à Política de consentimento de usuários da União Europeia ou se houver outros parâmetros de consentimento disponíveis na solicitação (gdpr_consent), esse parâmetro será ignorado.

Exemplo: process_consent=T

Além dos parâmetros anteriores, os bidders podem especificar os próprios, que serão anexados como parâmetros ao URL de redirecionamento. Os parâmetros definidos pelo bidder com o prefixo google_ serão ignorados porque são reservados pelo Google para desenvolvimento futuro, e não há garantia de preservação da ordem dos parâmetros. Uma tag de correspondência que inclui parâmetros definidos pelo bidder pode ter esta aparência:

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

Parâmetros de URL de redirecionamento

O URL de redirecionamento é criado com base no URL de correspondência de cookies configurado para a conta de um bidder, incluindo google_ e parâmetros definidos pelo bidder, dependendo daqueles especificados na tag de correspondência. Os seguintes parâmetros de resposta google_ são definidos:

Parâmetro Descrição
google_gid ID do usuário do Google. Definido se google_cm for especificado na solicitação e ela for bem-sucedida.
google_cver Versão do cookie. Definido se google_cm for especificado na solicitação e ela for bem-sucedida.
google_error

Um valor inteiro que indica o erro geral da solicitação. Quando recebido, ele indica que nenhuma operação foi realizada e que nenhum outro parâmetro de resposta google_ será definido. Os valores de erro compatíveis incluem:

  • 1: o usuário tem um cookie do Google, mas desativou qualquer rastreamento usando esse cookie.
  • 2: nenhuma operação válida especificada. Por exemplo, uma solicitação nula foi recebida.
  • 3: o usuário não tem um cookie do Google. O Google não define o cookie pelo serviço de correspondência de cookies.
  • 4: operações conflitantes especificadas. Não é possível especificar as flags google_push e google_cm na mesma solicitação, já que elas têm propósitos conflitantes.
  • 5: um parâmetro google_push inválido foi transmitido em um redirecionamento para um servidor do Google como parte de uma solicitação de correspondência de pixel bidirecional. O redirecionamento precisa definir google_push com o mesmo valor transmitido a você na solicitação inicial de pixel.
  • 6: um NID inválido foi fornecido na tag de correspondência.
  • 7: um cookie inválido foi detectado.
  • 8: uso suspenso. Nenhum cookie encontrado.
  • 9: nenhum cookie encontrado. Uma tentativa de definir um cookie de teste é feita.
  • 10: o parâmetro google_redir foi usado sem que google_hm fosse especificado ou foi usado além de google_cm.
  • 15: a solicitação vem de uma região em que o Google exige que a tabela de correspondência seja hospedada pelo Google. Como resultado, essa resposta não contém um ID de usuário do Google.
google_hm

Só aparece se a tentativa de gravar na tabela de correspondência hospedada pelo Google falhar. Quando isso acontece, o valor é um dos seguintes códigos de status:

  • 1 - Proibido: o cliente não tem acesso para gravar entradas na tabela de correspondência hospedada.
  • 2 - Erro de decodificação: não foi possível decodificar o valor do parâmetro.
  • 3 - Payload muito longo: o valor do parâmetro decodificado em mais de 40 bytes de dados.
  • 4 - Erro interno: ocorreu um erro interno ao armazenar os dados.
  • 5 - Limitada: esta gravação não foi processada devido à limitação.
google_ula

Status da operação de adição à lista de usuários, repetido se vários google_ula foram especificados na solicitação. O formato é:
userlistid,status code

Por exemplo: google_ula=1234567890,0

A operação google_ula pode retornar qualquer um dos seguintes códigos de status:

  • 0: nenhum erro. O usuário foi adicionado à lista de usuários.
  • 2: permissão negada. Você não tem permissão para adicionar usuários à lista especificada.
  • 5: ID da lista de usuários inválido. O ID da lista de usuários fornecido é inválido.
  • 6: ID do atributo fechado. O ID da lista de usuários fornecido está fechado.
  • 10 - Erro interno. O serviço de correspondência de cookies encontrou um erro interno. Tente fazer a correspondência do usuário novamente.

Os cenários a seguir descrevem como a correspondência de cookies pode ser para um usuário típico navegando em uma página da Web.

Cenário 1: o usuário limpa os cookies e navega em um site

Jane limpa o cache de todos os cookies. Em seguida, eles acessam a página inicial de ExampleNews.com.

Veja o que acontece:

  1. O ExampleNews.com renderiza e chama anúncios do Google (Ad Manager).
  2. Como o bloco de anúncios está qualificado para alocação dinâmica, o Google envia solicitações de lances para a FinestDSP e outros bidders pelo serviço de lances em tempo real.
  3. O aplicativo do bidder da FinestDSP recebe e processa a solicitação de lance e envia a resposta.
  4. O Google recebe respostas de lances dos bidders, incluindo a resposta da FinestDSP que especifica um anúncio com uma tag de correspondência (pixel).
  5. A FinestDSP vence o leilão. O Google veicula o anúncio e a tag de correspondência da FinestDSP para Ana.
  6. A tag de correspondência chama o serviço de correspondência de cookies do Google, especificando os parâmetros google_nid e google_cm.
  7. O serviço de correspondência de cookies lê o cookie do Google de Jane e envia ao navegador dela um redirecionamento para o URL de correspondência de cookies da FinestDSP com os parâmetros google_gid e google_cver definidos.
  8. O navegador de Jane carrega o redirecionamento para o URL de correspondência de cookie da FinestDSP.
  9. O endpoint de correspondência de cookies da FinestDSP processa a solicitação de redirecionamento, que inclui parâmetros de URL definidos pelo Google e o cookie de Jane nos cabeçalhos HTTP. Agora, a FinestDSP pode armazenar o mapeamento do cookie para o google_gid na tabela de correspondência.
  10. A FinestDSP responde ao redirecionamento com um pixel invisível de 1 x 1.
Cenário 2: usuário com mapeamento atual

Uma semana depois do cenário 1, Jane visita o site ExampleNews.com novamente. Agora que Jane tem cookies do bidder e do Ad Manager na máquina, veja como funciona a correspondência.

  1. A página da Web é renderizada, fazendo com que o Google (Ad Manager) solicite anúncios que serão renderizados na página.
  2. Durante o leilão de anúncios, o Google envia uma solicitação de lance para os bidders aplicáveis, incluindo a FinestDSP.
  3. A FinestDSP recebe a solicitação de lance, incluindo indicadores como o google_gid.
  4. A FinestDSP pesquisa o google_gid na tabela de correspondências e encontra o cookie associado a Jane, que foi criado uma semana antes (no cenário 1).
  5. Com base nas informações associadas ao cookie, a lógica de lances da FinestDSP faz um lance na impressão e vence o leilão.
  6. Ana pode ver um anúncio adaptado aos interesses dela com base nas informações que a FinestDSP tem.

A correspondência de cookie unidirecional é semelhante ao fluxo de trabalho bidirecional, mas é alterada para que apenas o Google hospede e preencha uma tabela de correspondência. Isso pode ser usado em casos em que o bidder não tem permissão para hospedar IDs de usuário do Google na própria tabela de correspondência. Para usar esse fluxo, os bidders precisam permitir que o Google hospede a tabela de correspondência, não podem mais especificar google_cm em solicitações ao Serviço de correspondência de cookies do Google e, consequentemente, não vão receber google_gid para preencher a própria tabela de correspondência. Depois que o Google estabelece uma correspondência para um usuário, os bidders podem adicioná-lo a listas de usuários usando os próprios dados de cookies. Da mesma forma, as solicitações de lance para esses usuários vão excluir o ID do usuário do Google, mas incluir dados de correspondência hospedados. Um exemplo do fluxo de trabalho revisado é resumido nas etapas a seguir.

Etapa 1: coloque a tag de correspondência direcionada ao URL de correspondência de cookie do bidder

Para iniciar esse fluxo, um bidder precisa inserir uma tag de correspondência que seja renderizada no navegador do usuário. Ao contrário do fluxo de trabalho para usuários que não são de um estado dos EUA com restrições de privacidade, a tag de correspondência precisa direcionar o navegador do usuário para o URL de correspondência de cookies. Por exemplo, com um URL de correspondência de cookie configurado como https://ad.network.com/pixel, ele teria esta aparência:

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

Ao carregar no navegador do usuário, ele vai solicitar um pixel do URL de correspondência de cookies do bidder. Essa solicitação vai conter o cookie no cabeçalho HTTP, que precisa ser extraído para a próxima etapa.

O endpoint de correspondência de cookies do bidder precisa redirecionar para o serviço de correspondência de cookies do Google, incluindo o parâmetro google_hm preenchido com os dados de cookies codificados em base64 e otimizados para a Web. O URL de redirecionamento pode ser semelhante a este:

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

O Google vai receber um redirecionamento com os parâmetros especificados, além do cookie do Google nos cabeçalhos HTTP.

Etapa 4: o Google veicula o pixel no redirecionamento de sucesso ou erro se o URL do relatório for especificado

Se a operação de correspondência de cookies for bem-sucedida ou se nenhum URL de relatório de correspondência de cookies tiver sido especificado para a conta do bidder, o Google vai veicular um pixel transparente 1x1 por padrão, e o fluxo de trabalho vai terminar aqui. As impressões para esse usuário em solicitações de lances subsequentes vão incluir os dados de correspondência hospedados do bidder em BidRequest.user.buyeruid. Os bidders também podem preencher listas de usuários com os dados de correspondência hospedados especificados.

Caso contrário, se ocorrer um erro, o Google vai enviar um redirecionamento para o URL do relatório de correspondência de cookies do bidder com a causa do erro especificada no parâmetro google_error. Se o URL do relatório de correspondência de cookie do bidder fosse https://ad.network.com/report, o URL de redirecionamento seria assim:

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

O navegador do usuário vai redirecionar para o URL do relatório de correspondência de cookies do bidder, incluindo o motivo do erro (se houver) especificado pelo Google no parâmetro google_error. Para saber mais sobre como interpretar o código de erro, consulte a descrição do parâmetro.

Etapa 6: o bidder veicula um pixel transparente de 1 x 1

O bidder precisa responder veiculando um pixel transparente de 1 x 1 no navegador do usuário.

O fluxo de trabalho padrão para usuários em estados dos EUA com restrições de privacidade é ilustrado no diagrama a seguir, em que solicitações e respostas são representadas por uma seta, e os itens de dados que as acompanham são listados entre parênteses.

Parâmetro Descrição
google_nid ID da rede (NID) da conta do bidder. Esse ID pode ser recuperado pelo recurso Bidders.
google_sc Este parâmetro foi descontinuado. Define o cookie do Google para o usuário, se não houver um. O valor do parâmetro é ignorado e pode ser omitido. Se o parâmetro for omitido, ocorrerá um erro se não houver cookie.
google_no_sc Este parâmetro foi descontinuado. Isso indica ao serviço de correspondência de cookies do Google que ele não deve definir um cookie para o usuário se um não estiver presente. O valor do parâmetro é ignorado e pode ser omitido.
google_hm

Contém dados que o bidder quer armazenar em uma tabela de correspondência hospedada pelo Google.
google_redir Um URL codificado para que o Google envie um redirecionamento HTTP 302. O URL especificado vai receber redirecionamentos com o parâmetro google_error para erros e operações bem-sucedidas.
google_ula Uma string usada para adicionar o usuário a uma lista de usuários. O formato esperado do valor é userlistid[,timestamp]:
  • userlistid: um único ID numérico de lista de usuários.
  • timestamp: um carimbo de data/hora opcional no formato POSIX, indica quando o usuário foi adicionado à lista de usuários.

Esse parâmetro de URL pode ser repetido para adicionar o usuário a várias listas.
gdpr Indica que a solicitação está sujeita às restrições do GDPR sobre o uso de dados. Para mais detalhes, consulte Requisitos de consentimento do usuário da UE ou Impacto na qualificação da correspondência de cookies na documentação da TCF v2.0 do IAB do Authorized Buyers.

Exemplo: gdpr=1
gdpr_consent Uma string de TC que representa o consentimento do usuário final. Para mais detalhes, consulte Requisitos de consentimento do usuário da UE ou Como a string de TC será transmitida? na documentação da TCF v2.0 do IAB do Authorized Buyers.
process_consent Indica que o bidder recebeu o consentimento do usuário final para os usos de dados especificados na Política de consentimento de usuários da União Europeia do Google.

Se a solicitação não estiver sujeita à Política de consentimento de usuários da União Europeia ou se houver outros parâmetros de consentimento disponíveis na solicitação (gdpr_consent), esse parâmetro será ignorado.

Exemplo: process_consent=T
Parâmetro Descrição
google_error

Um valor inteiro que indica o erro geral da solicitação. Quando recebido, ele indica que nenhuma operação foi realizada e que nenhum outro parâmetro de resposta google_ será definido. Os valores de erro compatíveis incluem:

  • 1: o usuário tem um cookie do Google, mas desativou qualquer rastreamento usando esse cookie.
  • 2: nenhuma operação válida especificada. Por exemplo, uma solicitação nula foi recebida.
  • 3: o usuário não tem um cookie do Google. O Google não define o cookie pelo serviço de correspondência de cookies.
  • 4: operações conflitantes especificadas. Não é possível especificar as flags google_push e google_cm na mesma solicitação, já que elas têm propósitos conflitantes.
  • 5: um parâmetro google_push inválido foi transmitido em um redirecionamento para um servidor do Google como parte de uma solicitação de correspondência de pixel bidirecional. O redirecionamento precisa definir google_push com o mesmo valor transmitido a você na solicitação inicial de pixel.
  • 6: um NID inválido foi fornecido na tag de correspondência.
  • 7: um cookie inválido foi detectado.
  • 8: uso suspenso. Nenhum cookie encontrado.
  • 9: nenhum cookie encontrado. Uma tentativa de definir um cookie de teste é feita.
  • 10: o parâmetro google_redir foi usado sem que google_hm fosse especificado ou foi usado além de google_cm.
  • 15: a solicitação vem de uma região em que o Google exige que a tabela de correspondência seja hospedada pelo Google. Como resultado, essa resposta não contém um ID de usuário do Google.

Iniciada pelo Google: correspondência de pixel bidirecional

A correspondência de pixel bidirecional é um fluxo de trabalho para o serviço de correspondência de cookie do Google, em que o Google tenta corresponder um ID de usuário do Google a um bidder selecionado por algoritmo que não seja o vencedor do leilão de lances em tempo real. Quando um anúncio é inserido, o Google coloca uma tag de correspondência direcionando o navegador do usuário para carregar um pixel transparente do URL de correspondência de cookies do bidder escolhido. Isso permite que o Google e o bidder preencham uma tabela de correspondências com um determinado usuário. Confira a seguir um exemplo desse fluxo de trabalho.

Etapa 1: o Google coloca uma tag de correspondência

Quando a página de um editor participante é carregada no navegador do usuário e um slot de anúncio nessa página é preenchido pelo Google, uma tag de correspondência pode ser colocada para solicitar um pixel de um bidder selecionado por algoritmo. A tag de correspondência de pixel colocada pelo Google combina o URL de correspondência de cookie do bidder com parâmetros adicionais que o bidder pode usar para preencher a tabela de correspondências. Para um URL de correspondência de cookie especificado como https://ad.network.com/pixel, a estrutura é a seguinte:

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

Os bidders que recebem solicitações de correspondência de pixel precisam responder com um redirecionamento para o serviço de correspondência de cookies do Google, que é estruturado da seguinte forma:

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

O URL de redirecionamento anterior é semelhante ao usado na tag de correspondência do fluxo de trabalho de correspondência de cookies iniciada pelo bidder. Na correspondência de pixel, o parâmetro google_cm é substituído pelo parâmetro google_push, e o valor dele precisa ser igual ao valor fornecido pelo Google na solicitação. Assim como no fluxo de trabalho iniciado pelo bidder, é possível especificar parâmetros adicionais para atender a outros casos de uso.

Etapa 3: o Google processa o redirecionamento e responde com o pixel

O Google registra que uma correspondência foi criada para o usuário e processa outras operações solicitadas por parâmetros de consulta. Por fim, o Google responde com um pixel transparente de 1 x 1.

Diagrama do fluxo de trabalho de correspondência de pixel

Esse fluxo de trabalho é ilustrado no diagrama a seguir, em que solicitações e respostas são representadas por uma seta, e os itens de dados que as acompanham são listados entre parênteses.

Parâmetros de solicitação da tag de correspondência do Google

Parâmetro Descrição
google_gid ID do usuário do Google. Para usuários que não estão em um estado dos EUA com restrições de privacidade, isso sempre será especificado na tag de correspondência do Google.
google_cver A versão do cookie. Isso sempre será especificado na tag de correspondência do Google.
google_push Indica que esta solicitação está iniciando o fluxo de trabalho de correspondência de pixel. O valor precisa ser retornado pelo parâmetro correspondente na resposta de redirecionamento do bidder.
gdpr_consent Uma string de TC que representa o consentimento do usuário final. Para mais detalhes, consulte [Requisitos de consentimento do usuário da UE](/authorized-buyers/rtb/cookie-guide#eu-user-consent-requirements) ou **Como a string de TC será transmitida?** na [documentação da TCF v2.0 da IAB do Authorized Buyers](//support.google.com/authorizedbuyers/answer/9789378).

Parâmetros de redirecionamento de correspondência de pixel do bidder

Parâmetro Descrição
google_nid ID da rede (NID) da conta do bidder. Esse ID pode ser recuperado pelo recurso Bidders.
google_push Indica que esse redirecionamento está concluindo o fluxo de trabalho de correspondência de pixel. O valor da tag de correspondência do Google correspondente precisa ser especificado aqui.
google_hm

Contém dados que o bidder quer armazenar em uma tabela de correspondência hospedada pelo Google.
google_ula Uma string usada para adicionar o usuário a uma lista de usuários. O formato esperado do valor é userlistid[,timestamp]:
  • userlistid: um único ID numérico de lista de usuários.
  • timestamp: um carimbo de data/hora opcional no formato POSIX, indica quando o usuário foi adicionado à lista de usuários.

Esse parâmetro de URL pode ser repetido para adicionar o usuário a várias listas.
gdpr_consent Uma string de TC que representa o consentimento do usuário final. Para mais detalhes, consulte [Requisitos de consentimento do usuário da UE](/authorized-buyers/rtb/cookie-guide#eu-user-consent-requirements) ou **Como a string de TC será transmitida?** na [documentação da TCF v2.0 do IAB do Authorized Buyers](//support.google.com/authorizedbuyers/answer/9789378).

Iniciada pelo Google: correspondência de pixel unidirecional

A correspondência de pixel unidirecional difere do fluxo de trabalho bidirecional porque a tag de correspondência do Google não inclui um parâmetro que especifica o ID do usuário do Google, mas continua preenchendo uma tabela de correspondências hospedada pelo Google. Isso pode ser usado em casos em que o bidder não tem permissão para hospedar IDs de usuário do Google na própria tabela de correspondência. Um exemplo do fluxo de trabalho revisado está resumido nas etapas a seguir.

Etapa 1: o Google coloca uma tag de correspondência

O Google coloca uma tag de correspondência para um bidder selecionado por algoritmo. A tag de correspondência inclui o parâmetro google_push. Veja um exemplo:

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

Etapa 2: o navegador do usuário solicita o pixel do URL de correspondência de cookie do bidder

O navegador do usuário solicita um pixel do URL de correspondência de cookies do bidder, incluindo o cookie do bidder nos cabeçalhos HTTP.

O endpoint de correspondência de cookies do bidder precisa redirecionar para o serviço de correspondência de cookies do Google, incluindo o parâmetro google_hm preenchido com os dados de cookies codificados em base64 e otimizados para a Web. O URL de redirecionamento pode ser semelhante a este:

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

O Google vai receber um redirecionamento com os parâmetros especificados, além do cookie do Google nos cabeçalhos HTTP. Se a operação for bem-sucedida, as impressões desse usuário em solicitações de lances subsequentes vão incluir os dados de correspondência hospedados do bidder em BidRequest.user.buyeruid. Os bidders também podem preencher listas de usuários usando os dados de correspondência hospedados que especificaram.

Por fim, o Google retorna um pixel transparente de 1 x 1 ao navegador do usuário.

O Open Bidding permite que as trocas usem fluxos de trabalho de correspondência de cookie iniciados pelo bidder e iniciados pelo Google para corresponder um ID de usuário do Google ao cookie dele. O Cookie Match Assist (CMA) é um recurso adicional para exchanges que permite criar tabelas de correspondência com os próprios bidders.

  1. Ao veicular um anúncio, o algoritmo do Google seleciona uma troca participante e coloca uma tag do Assistente de correspondência de cookies com a seguinte estrutura:

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

  2. A tag de correspondência da CMA do Google faz com que o URL de correspondência de cookie da troca receba uma solicitação de pixel.

  3. O endpoint de correspondência de cookie da troca recebe a solicitação, e o serviço de correspondência de cookie dela é responsável por associar o ID do usuário a um dos seus bidders. No diagrama a seguir, o serviço de correspondência de cookies da troca responde ao navegador do usuário com um redirecionamento para um dos endpoints do bidder.
  4. O bidder recebe a solicitação, junto com todos os parâmetros especificados pela troca para corresponder o ID do usuário ao cookie.

Restrições

Limitar a frequência de solicitações de correspondências atualizadas

Os bidders são responsáveis por limitar o número de chamadas ao serviço de correspondência de cookies para usuários que têm uma entrada recente na tabela de correspondência hospedada pelo Google. Uma entrada na tabela de correspondência hospedada pode ser considerada expirada em 14 dias, após o que pode ser atualizada.

Responder a todas as solicitações de correspondência de pixel

Os bidders que usam o fluxo de trabalho de correspondência de pixel precisam responder a todas as solicitações de correspondência de pixel recebidas com uma resposta que inclua o parâmetro google_push. Isso permite que o Google aplique políticas monitorando o uso. Se a taxa de resposta de um bidder for menor que 90%, o Google vai limitar o número de solicitações de correspondência do Pixel enviadas para a conta dele.

Usar endpoints HTTPS

É necessário que os endpoints usados em todos os fluxos de trabalho de correspondência de cookies usem HTTPS.

Ao responder a uma solicitação de correspondência exata do Pixel enviada a você por HTTPS, é necessário redirecionar para o serviço de correspondência de cookies por HTTPS. Da mesma forma, um endpoint do Cookie Match Assist que redireciona para os bidders também precisa usar HTTPS. Se você enviar solicitações ao Google por HTTP mais de uma vez a cada dois minutos, o número de solicitações de correspondência enviadas à sua conta será limitado.

As solicitações de correspondência de cookie sujeitas à Política de consentimento de usuários da União Europeia do Google precisam indicar o consentimento do usuário final. Essas solicitações precisam indicar que o consentimento foi coletado usando uma das seguintes formas:

Exemplos

Os exemplos a seguir ilustram como usar o serviço de correspondência de cookies para atingir objetivos específicos. A menos que indicado de outra forma, presume-se que o usuário afetado não seja de um estado dos EUA com restrições de privacidade.

Preencher uma tabela de correspondência hospedada pelo bidder

Um bidder pode usar o fluxo de trabalho de correspondência de cookies para preencher a própria tabela de correspondência fornecendo apenas os parâmetros google_nid e google_cm na tag de correspondência. O resultado será algo como o seguinte:

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

Se o URL de correspondência de cookies do bidder estiver definido como https://ad.network.com/pixel?id=1 e a operação de correspondência de cookies for bem-sucedida, o redirecionamento que o Google envia em resposta à tag de correspondência do bidder poderá ter esta aparência:

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

Se a operação de correspondência de cookies falhar porque o usuário não tem um cookie do Google, a resposta será:

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

O código do erro depende da causa subjacente. Para saber mais sobre possíveis códigos de erro do fluxo de trabalho de correspondência de cookies, consulte os parâmetros de URL de redirecionamento.

Adicionar à lista de um único usuário

O parâmetro google_ula pode ser especificado em uma tag de correspondência de um bidder para adicionar o usuário a uma lista com o ID fornecido. Se a tabela de correspondência hospedada pelo Google ou pelo bidder tiver uma entrada atualizada para o usuário, o bidder poderá inserir uma tag de correspondência, incluindo os parâmetros google_nid e google_ula, para adicionar o usuário à lista especificada sem iniciar o fluxo de trabalho completo de correspondência de cookies. Consulte as restrições ao invocar o serviço de correspondência de cookies para mais detalhes. A tag de correspondência correspondente pode ser semelhante a esta:

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

Para uma resposta bem-sucedida, em que o URL de correspondência de cookies do bidder é https://ad.network.com/pixel, o URL de redirecionamento do Google seria:

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

Se houver um erro geral, por exemplo, não houver um cookie do Google para o usuário, o URL de redirecionamento vai incluir o parâmetro google_error:

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

Se houver um erro específico ao adicionar o usuário à lista, você vai receber google_ula no redirecionamento. Ao contrário do parâmetro de tag de correspondência correspondente, ele substitui o carimbo de data/hora por um código de status para indicar o sucesso da operação. Por exemplo, se a solicitação falhar porque a conta do bidder não tem acesso à lista de usuários especificada, o URL de redirecionamento será:

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

Adicionar a várias listas de usuários

Os bidders podem especificar que um usuário seja adicionado a várias listas de usuários incluindo vários parâmetros google_ula na tag de correspondência. Na prática, isso pode ter a seguinte aparência:

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

O status da operação para cada lista de usuários é informado de maneira semelhante por parâmetros google_ula distintos no redirecionamento:

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

No redirecionamento anterior, podemos ver que a operação foi concluída para a lista de usuários com o ID 45678, mas falhou para o ID 12345 porque o bidder não tinha permissão para acessar.

Para fazer a correspondência de cookies e adicionar o usuário a uma lista de usuários em uma única solicitação, a tag de correspondência de um bidder precisa incluir google_cm e google_ula:

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

O URL de redirecionamento especificado pelo Google incluiria google_gid, google_cver e google_ula. O resultado será algo como o seguinte:

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

Armazenar uma correspondência em uma tabela de correspondência hospedada pelo Google

Se um bidder quiser armazenar os dados de cookies em uma tabela de correspondência hospedada pelo Google e não quiser armazenar a correspondência com o ID do usuário do Google na própria tabela, a tag de correspondência precisará incluir o parâmetro google_hm, cujo valor precisa ser uma string codificada em base64 segura para a Web. Para um usuário em que os dados não codificados do cookie do bidder são Cookie number 1!, o valor codificado seria Q29va2llIG51bWJlciAxIQ==, que seria usado em uma tag de correspondência como esta:

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

Para uma resposta bem-sucedida, em que o URL de correspondência de cookies do bidder é https://cookie-monster.com/pixel, o URL de redirecionamento do Google seria:

https://cookie-monster.com/pixel

O parâmetro google_gid não está no redirecionamento porque a tag de correspondência não incluiu google_cm, e google_hm não é incluído em respostas bem-sucedidas. Em futuras solicitações de lance para impressões desse usuário, o bidder vai receber os dados de correspondência hospedados em BidRequest.user.buyeruid.

Se o bidder usasse uma tag de correspondência em que o valor de google_hm não fosse codificado em base64, como chocolate_chunk!, o URL de redirecionamento poderia ter esta aparência:

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

O URL de redirecionamento anterior inclui um valor google_hm de 2, sugerindo que a operação falhou porque o valor não pôde ser decodificado.

Tabelas de correspondência hospedadas pelo bidder e pelo Google com listas de usuários

Se um bidder hospedar a própria lista de uso além de uma lista de usuários hospedada pelo Google e quiser uma única tag de correspondência para corresponder às duas tabelas e adicionar o usuário a uma determinada lista de usuários, a tag de correspondência precisará incluir os parâmetros google_cm, google_hm e google_ula. Se os dados de cookie do bidder forem Cookie number 1!, o valor codificado será Q29va2llIG51bWJlciAxIQ==, o que vai gerar uma tag de correspondência como esta:

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

Para uma resposta bem-sucedida, em que o URL de correspondência de cookies do bidder é https://cookie-monster.com/pixel, o URL de redirecionamento do Google seria assim:

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

Ao receber o redirecionamento, o bidder pode fazer a correspondência do ID do usuário do Google especificado em google_gid com os dados de cookie na tabela de correspondência. Além disso, eles podem determinar se as operações de tabela de correspondência e lista de usuários hospedadas pelo Google foram bem-sucedidas. Como consequência, qualquer pré-segmentação que o bidder configurou para segmentar o ID da lista de usuários especificado agora fará com que o bidder receba solicitações de lance para impressões do usuário. Da mesma forma, nessas solicitações de lance, o bidder vai receber os dados de correspondência hospedados em BidRequest.user.buyeruid.