Correspondência de cookie

A correspondência de cookie é um recurso que permite associar seu cookie (por exemplo, um ID de um usuário que navegou no seu site) a um ID de usuário do Google específico do bidder e criar listas de usuários para fazer escolhas de lances mais eficazes. Este guia descreve os conceitos usados na correspondência de cookies, bem como diferentes fluxos de trabalho de correspondência de cookies e todas as variações que eles podem ter para determinados casos de uso.

Conceitos

Os proprietários de domínio normalmente definem o conteúdo dos cookies para os usuários que navegam no site, 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 da Internet restringe a leitura de um cookie definido por outro domínio.

No contexto da publicidade digital, o Google identifica usuários com cookies que pertencem ao domínio doubleclick.net, e os participantes do leilão em tempo real podem ter o próprio domínio em que identificam um conjunto de usuários para veicular anúncios. A correspondência de cookie permite que o bidder faça a correspondência dos próprios cookies com os do Google. Assim, ele pode 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 do usuário do Google específico do bidder, que é um formulário criptografado 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 e também permite preencher listas de usuários.

Tabelas de correspondências

Uma tabela de correspondências pode ser usada para mapear um ID ou outros dados de um domínio para outro. Os proponentes podem usar o serviço de correspondência de cookie para preencher as próprias tabelas de correspondências mapeando o cookie de um determinado usuário para o ID do usuário do Google ou para preencher uma tabela de correspondências hospedada pelo Google. As tabelas de correspondência são necessárias para que o aplicativo do proponente acesse os dados de cookie 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 ter acesso aos dados de correspondência de 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, também chamada de dados de correspondência hospedados, que será mapeada para o ID de 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 lance subsequentes para impressões associadas ao usuário, o Google vai enviar os dados de correspondência hospedados que você associou ao ID do usuário do Google. Na implementação do OpenRTB do Google, BidRequest.user.buyeruid especifica isso como uma string codificada em base64 segura para a Web. Se o endpoint de lances estiver configurado para usar o protocolo descontinuado RTB do Google, você vai receber esse valor como bytes decodificados por meio do campo BidRequest.hosted_match_data.

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

  • Pré-segmentação: é possível configurar a pré-segmentação para receber somente 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 cookie.

Listas de usuários

É possível criar e gerenciar listas de usuários com a API Real-Time Bidding. Depois de criadas, é possível preencher essas listas com os fluxos de trabalho de correspondência de cookies descritos abaixo ou pelo Bulk Uploader Service.

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 de rede de correspondência de cookie (NID, na sigla em inglês): é um ID de string que identifica exclusivamente uma conta de bidder para a correspondência de cookie e outras operações relacionadas.
  • URL de correspondência de cookie: é o URL de base para um endpoint que aceita e processa as solicitações recebidas como parte dos fluxos de trabalho de correspondência de cookies. Os bidders podem incorporar macros a esse URL para controlar a ordem dos parâmetros transmitidos a ele nos fluxos de trabalho de correspondência de cookie.
  • Match Tag: a tag que você precisa colocar no navegador do usuário para o fluxo de trabalho de correspondência de cookie iniciado pelo bidder. Eles podem ser veiculados ao lado dos anúncios ou colocados 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, esse é um URL opcional que pode ser fornecido para especificar um endpoint que vai receber 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 o bidder pode solicitar que o redirecionamento seja sempre enviado.
  • URL da assistência de correspondência de cookie: para trocas que implementam o fluxo de trabalho da assistência de correspondência de cookie, esse é o URL de base do endpoint destinado a responder às solicitações recebidas.
  • Quota de assistência de correspondência de cookie: para as 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 a cada segundo. Isso evita que as solicitações da CMA sobrecarreguem os servidores da troca com solicitações.

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 ordenação consistente de parâmetros podem colocar macros no URL de correspondência de cookie para garantir a posição.

Macros com suporte

Os proponentes podem configurar o URL de correspondência de cookies para incluir uma ou mais macros no formato %%GOOGLE_<PARAM_NAME>%% ou %%GOOGLE_<PARAM_NAME>_PAIR%%. As macros compatíveis e os valores expandidos 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 requer parâmetros predefinidos definidos pelo bidder, além dos parâmetros de correspondência de pixel na seguinte ordem: google_push, google_gid, google_cver e google_error. O bidder pode fazer isso definindo o URL de correspondência de cookie para:

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

Depois, quando o Google enviar uma solicitação de correspondência para esse bidder, ela será expandida para algo semelhante ao seguinte:

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

Atualmente, o serviço de correspondência de cookies do Google oferece suporte a três fluxos de trabalho para diferentes casos de uso, conforme descrito abaixo.

A correspondência de cookie bidirecional se refere a um fluxo de trabalho iniciado pelo bidder, em que ele insere uma tag de correspondência no navegador do usuário que a direciona para o Google. Esse fluxo de trabalho permite que o Google e o bidder preencham as tabelas de correspondências. Confira abaixo um exemplo simples desse fluxo de trabalho.

Etapa 1: colocar a tag de correspondência

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

<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 redirecionamento, incluindo 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 vai emitir um redirecionamento HTTP 302 para o URL de correspondência de cookies do bidder. O redirecionamento inclui parâmetros de consulta que especificam o ID do usuário do Google e o número da versão dele no URL, e o bidder também recebe o cookie 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 simples, como mostrado acima, pode ser parecido com o seguinte:

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 não preenchida segura para a Web. Para os bidders que escolherem hospedar uma tabela de correspondência, é recomendável que eles armazenem a string exata retornada pelo serviço de correspondência de cookies. Nas solicitações de lance subsequentes, isso corresponderá aos valores especificados por meio de BidRequest.user.id no OpenRTB ou BidRequest.google_user_id no protocolo RTB do Google descontinuado.

A versão especificada em google_cver indica o número da versão do ID de usuário do Google. O ID do usuário do Google de um determinado usuário muda infrequentemente, depois é 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 pixels

O bidder recebe um redirecionamento para o URL de correspondência de cookie, incluindo os parâmetros especificados na primeira etapa e aqueles fornecidos pelo Google na segunda etapa. Além disso, o cookie também será recebido nos cabeçalhos HTTP. Se a operação for bem-sucedida, um bidder que hospedar a própria tabela de correspondência poderá fazer a correspondência do cookie com o ID do usuário do Google incluído na resposta. É recomendado 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 aqui. Se receber um erro, você poderá tentar fazer a correspondência com esse usuário novamente. Basta inserir uma nova tag de correspondência.

O bidder precisa sempre responder veiculando uma imagem de pixel invisível de 1 x 1 ou retornar uma resposta HTTP 204 No Content.

Esse fluxo de trabalho é ilustrado pelo diagrama abaixo, em que as 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 URL da tag de correspondência

Parâmetro Descrição
google_nid ID de rede (NID, na sigla em inglês) da conta do bidder. Esse ID pode ser recuperado com o recurso Bidders.
google_cm Indica ao serviço de correspondência de cookies do Google que ele precisa fazer a correspondência de cookies. 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, caso não haja um. O valor do parâmetro é ignorado e pode ser omitido. A omissão do parâmetro resulta em erro se não houver cookies.
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 ele 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ências hospedada pelo Google.

O valor é uma string codificada em base64 segura para a Web (o preenchimento é opcional). Os dados brutos precisam ter até 40 bytes. 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 para o URL codificado dessa tag de correspondência. Isso permite que o Google seja colocado na frente de uma chamada encadeada para parceiros. Isso vai resultar em um erro se 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 da lista de usuários.
  • timestamp: um carimbo de data/hora opcional no formato POSIX, que 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 abaixo ou Impacto na qualificação de correspondência de cookies na documentação do IAB TCF v2.0 para compradores autorizados.

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 abaixo ou Como a string de TC será transmitida? na documentação do 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 acima, os bidders podem especificar os próprios parâmetros, que serão anexados como parâmetros ao URL de redirecionamento. Os parâmetros definidos pelo bidder nomeados com o prefixo google_ serão ignorados porque eles são reservados pelo Google para desenvolvimento futuro, e a preservação da ordem dos parâmetros não é garantida. Uma tag de correspondência que inclui parâmetros definidos pelo bidder pode ser parecida com esta:

<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 básico de correspondência de cookie 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 de solicitação. Quando recebido, 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 não operacional foi recebida.
  • 3: o usuário não tem um cookie do Google. O Google não vai definir 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, porque elas têm finalidades 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. Seu redirecionamento precisa definir google_push como o mesmo valor transmitido a você na solicitação inicial do 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 foi encontrado. É feita uma tentativa de definir um cookie de teste.
  • 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ências seja hospedada pelo Google. Como resultado, essa resposta não contém um ID de usuário do Google. No momento, esse recurso está ativado apenas para uma pequena porcentagem do tráfego, mas a ativação total está prevista para junho de 2020.
google_hm

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

  • 1 - Proibido: o cliente ainda não está na lista de permissões para gravar entradas na tabela de correspondências 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 foi decodificado em mais de 24 bytes de dados.
  • 4 – Erro interno: ocorreu um erro interno ao armazenar os dados.
  • 5: limitada. Essa gravação não foi processada devido à limitação.
google_ula

Status da operação de adição da lista de usuários, repetido se vários google_ula forem 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 de usuários especificada.
  • 5: ID da lista de usuários inválido. O ID da lista de usuários fornecida é 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 cookie encontrou um erro interno. Tente fazer a correspondência do usuário novamente.

Os cenários a seguir descrevem como pode ser a correspondência de cookie para um usuário típico que navega 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, ele acessa 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 a alocação dinâmica, o Google envia solicitações de lance para FinestDSP e outros bidders pelo serviço de lances em tempo real.
  3. O aplicativo proponente de FinestDSP recebe e processa a solicitação de lance e envia a resposta de lance.
  4. O Google recebe respostas de lances dos bidders, incluindo a resposta de FinestDSP que especifica um anúncio com uma match tag (pixel).
  5. FinestDSP vence o leilão. O Google veicula o anúncio de FinestDSP e a match tag para Jane.
  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 cookie lê o cookie do Google de Jane e envia ao navegador dela um redirecionamento para o URL de correspondência de cookie de 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 cookie de FinestDSP processa a solicitação de redirecionamento, que inclui parâmetros de URL definidos pelo Google e o cookie para Jane nos cabeçalhos HTTP. A FinestDSP agora pode armazenar o mapeamento do cookie para o google_gid na tabela de correspondências.
  10. O FinestDSP responde ao redirecionamento com um pixel 1x1 invisível.
Cenário 2: usuário com mapeamento

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

  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 FinestDSP.
  3. A FinestDSP recebe a solicitação de lance, incluindo indicadores como google_gid.
  4. O FinestDSP procura 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 do FinestDSP faz um lance na impressão e vence o leilão.
  6. Jane pode receber um anúncio personalizado de acordo com os interesses dela, com base nas informações que a FinestDSP tem.

A correspondência unidirecional de cookies é semelhante ao fluxo de trabalho bidirecional, exceto que é 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ências, não podem mais especificar google_cm nas solicitações ao serviço de correspondência de cookie do Google e, consequentemente, não vão receber google_gid para preencher a própria tabela. Depois que o Google estabelece uma correspondência para um usuário, os bidders podem adicioná-lo às listas de usuários usando os próprios dados de cookies. Da mesma forma, as solicitações de lance para esses usuários excluem o ID do usuário do Google, mas incluem dados de correspondência hospedados. Um exemplo simples do fluxo de trabalho revisado é resumido nas etapas abaixo.

Para iniciar esse fluxo, um bidder precisa colocar uma tag de correspondência para que ela seja renderizada no navegador do usuário. Ao contrário do fluxo de trabalho para usuários que não estão em 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 a seguinte aparência:

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

Ao carregar no navegador do usuário, ele solicita um pixel do URL de correspondência de cookies do proponente. Essa solicitação conterá o cookie no cabeçalho HTTP, que 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 parecido com 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 em um 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 de 1 x 1 por padrão, e o fluxo de trabalho vai terminar aqui. As impressões desse usuário em solicitações de lance subsequentes vão incluir os dados de correspondência hospedados do proponente em BidRequest.user.buyeruid para o OpenRTB ou BidRequest.hosted_match_data para o protocolo RTB do Google, que foi descontinuado. Os bidders também podem preencher listas de usuários usando os dados de correspondência hospedados que especificaram.

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 proponente com a causa do erro especificado no parâmetro google_error. Se o URL do relatório de correspondência de cookie do bidder for https://ad.network.com/report, o URL de redirecionamento vai ser 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 cookie do bidder, incluindo o motivo do erro (se houver) especificado pelo Google no parâmetro google_error. Para saber mais sobre a interpretação do 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 pelo diagrama abaixo, em que as 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 de rede (NID, na sigla em inglês) da conta do bidder. Esse ID pode ser recuperado pelo recurso Bidders.
google_sc Esse parâmetro foi descontinuado. Define o cookie do Google para o usuário, caso não haja um. O valor do parâmetro é ignorado e pode ser omitido. A omissão do parâmetro resulta em um erro se nenhum cookie existir.
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 ele 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 o qual você quer 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 da lista de usuários.
  • timestamp: um carimbo de data/hora opcional no formato POSIX, que 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 abaixo ou Impacto na qualificação de correspondência de cookie na documentação do 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 abaixo ou Como a string de TC será transmitida? na documentação do IAB TCF v2.0 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, 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 não operacional foi recebida.
  • 3: o usuário não tem um cookie do Google. O Google não vai definir 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, porque elas têm finalidades 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 de pixel inicial.
  • 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 foi encontrado. É feita uma tentativa de definir um cookie de teste.
  • 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ências seja hospedada pelo Google. Como resultado, essa resposta não contém um ID de usuário do Google. No momento, esse recurso está ativado apenas para uma pequena porcentagem do tráfego, mas será totalmente ativado em junho de 2020.

Iniciada pelo Google: correspondência bidirecional de pixels

A correspondência bidirecional de pixels é um fluxo de trabalho para o serviço de correspondência de cookies do Google em que ele tenta fazer a correspondência de um ID de usuário do Google com um participante do leilão selecionado algoritmicamente, diferente do vencedor do leilão de lances em tempo real. Quando um anúncio é colocado, o Google coloca uma tag de correspondência que direciona o navegador do usuário para carregar um pixel transparente do URL de correspondência de cookie do bidder escolhido. Isso vai permitir que o Google e o bidder preencham uma tabela de correspondências com um determinado usuário. Confira abaixo um exemplo simples 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 outros parâmetros que o bidder pode usar para preencher a tabela de correspondências. Um URL de correspondência de cookie especificado como https://ad.network.com/pixel é estruturado da seguinte maneira:

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

Os proponentes 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 maneira:

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

O URL de redirecionamento acima é semelhante ao usado na tag de correspondência do fluxo de trabalho de correspondência de cookies iniciado pelo bidder. Na correspondência de pixels, 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. Também semelhante ao fluxo de trabalho iniciado pelo proponente, parâmetros adicionais podem ser especificados 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 todas as operações adicionais solicitadas pelos 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 pixels

Esse fluxo de trabalho é ilustrado pelo diagrama abaixo, em que as 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 são de 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 é especificado na match tag do Google.
google_push Indica que essa 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) abaixo ou **Como a string de TC será transmitida?** na [documentação do TCF v2.0 do IAB do Authorized Buyers](//support.google.com/authorizedbuyers/answer/9789378).

Parâmetros de redirecionamento do Pixel do proponente

Parâmetro Descrição
google_nid ID de rede (NID, na sigla em inglês) 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ências hospedada pelo Google.
google_ula Uma string usada para adicionar o usuário a uma lista de usuários existente. O formato esperado do valor é userlistid[,timestamp]:
  • userlistid: um único ID numérico da lista de usuários.
  • timestamp: um carimbo de data/hora opcional no formato POSIX, que 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) abaixo ou **Como a string de TC será transmitida?** na [documentação do IAB TCF v2.0 para compradores autorizados](//support.google.com/authorizedbuyers/answer/9789378).

Iniciada pelo Google: correspondência unidirecional de pixels

A correspondência de pixel unidirecional é diferente do fluxo de trabalho bidirecional porque a tag de correspondência do Google não inclui um parâmetro que especifique 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ências. Um exemplo simples do fluxo de trabalho revisado está resumido nas etapas abaixo.

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 cozinha 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 parecido com 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 tiver sido concluída, as impressões para esse usuário em solicitações de lance subsequentes vão incluir os dados de correspondência hospedados do bidder em BidRequest.user.buyeruid para o OpenRTB ou BidRequest.hosted_match_data para o protocolo de RTB do Google, que foi descontinuado. 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 para o navegador do usuário.

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

  1. Ao veicular um anúncio, o Google seleciona de forma algorítmica uma troca participante e insere uma tag de assistência 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 cookies da troca recebe a solicitação, em que o próprio serviço de correspondência de cookies é responsável por fazer a correspondência do ID do usuário com um dos bidders. No diagrama abaixo, 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 com todos os parâmetros especificados pela troca para fazer a correspondência entre o ID do usuário e o cookie.

Restrições

Limitar a frequência das solicitações para novas correspondências

Os proponentes são responsáveis por limitar o número de chamadas para o serviço de correspondência de cookies para usuários que têm uma nova entrada na tabela de correspondência hospedada pelo Google. Uma entrada na tabela de correspondências hospedadas pode ser considerada expirada em 14 dias. Depois disso, ela pode ser atualizada.

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

Os anunciantes que usam o fluxo de trabalho de correspondência de pixels 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 ficar abaixo de 90%, o Google limitará o número de solicitações de correspondência de Pixel enviadas à 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 de pixel enviada por HTTPS, você precisa redirecionar para o serviço de correspondência de cookies por HTTPS. Da mesma forma, um endpoint de Cookie Match Assist que redireciona para os bidders também precisa usar HTTPS. Se você enviar solicitações ao Google por HTTP com mais frequência do que 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 cookies que estão 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 de uma das seguintes maneiras:

Exemplos

Os exemplos abaixo 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 que está sendo processado não é de um estado dos EUA com restrições de privacidade.

Preencher uma tabela de correspondências hospedada pelo bidder

Um bidder pode usar o fluxo de trabalho de correspondência de cookies para preencher a própria tabela de correspondências 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 proponente 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 proponente pode ser parecido com este:

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

Se a operação de correspondência de cookie 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 do erro. Para saber mais sobre possíveis códigos de erro do fluxo de trabalho de correspondência de cookies, consulte os parâmetros de redirecionamento de URL.

Adicionar à lista de usuários

O parâmetro google_ula pode ser especificado na tag de correspondência de um bidder para adicionar o usuário a uma lista de usuários com o ID fornecido. Se a tabela de correspondência hospedada pelo Google ou pelo proponente tiver uma nova entrada para o usuário, o proponente poderá inserir uma tag de correspondência que inclua 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 para invocar o serviço de correspondência de cookies e saber mais. 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 será:

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

Se houver um erro geral, por exemplo, se 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 especificamente relacionado à adição do 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 proponentes podem especificar que um usuário deve ser 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 ser algo como:

<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 usando parâmetros google_ula distintos no redirecionamento:

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

No redirecionamento acima, podemos ver que a operação foi bem-sucedida para a lista de usuários com o ID 45678, mas falhou para o ID da lista de usuários 12345 porque o bidder não tinha permissão para acessá-la.

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 inclui google_gid, google_cver e google_ula. O resultado será algo como este:

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ências hospedada pelo Google

Se um bidder quiser armazenar os dados de cookies em uma tabela de correspondências hospedada pelo Google e não pretende 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, em que o valor precisa ser uma string codificada em base64 segura para a Web. Para um usuário em que os dados do cookie não codificado do bidder são Cookie number 1!, o valor codificado será Q29va2llIG51bWJlciAxIQ==, que será 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 será o seguinte:

https://cookie-monster.com/pixel

O parâmetro google_gid não está no redirecionamento porque a tag de correspondência não inclui google_cm, e google_hm não está incluída nas respostas bem-sucedidas. Em solicitações de lance futuras para impressões deste usuário, o bidder vai receber os dados de correspondência hospedados em BidRequest.user.buyeruid para o OpenRTB ou BidRequest.hosted_match_data para o protocolo descontinuado do Google RTB.

Se o bidder usou uma tag de correspondência em que o valor de google_hm não foi codificado em base64, como chocolate_chunk!, o URL de redirecionamento pode ser parecido com este:

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

O URL de redirecionamento acima inclui um valor google_hm de 2, o que sugere que a operação falhou porque o valor não poderia ser decodificado.

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

Se um bidder hospeda a própria lista de uso, além de uma lista de usuários hospedada pelo Google, e quer que uma única tag de correspondência corresponda às duas tabelas e adicione o usuário a uma determinada lista de usuários, a tag de correspondência precisa incluir os parâmetros google_cm, google_hm e google_ula. Se os dados do 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 cookie do bidder é https://cookie-monster.com/pixel, o URL de redirecionamento do Google ficaria 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 do cookie na tabela de correspondência. Além disso, eles podem determinar se as operações da tabela de correspondências hospedada pelo Google e da lista de usuários foram bem-sucedidas. Como consequência, qualquer segmentação antecipada 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 para o OpenRTB ou BidRequest.hosted_match_data para o protocolo descontinuado do RTB do Google.