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
O que é a correspondência de cookie?
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.buyeruidespecifica 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 campoBidRequest.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.
Macros de correspondência de cookie
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
Fluxos de trabalho do serviço de correspondência de cookie
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.
Iniciada pelo bidder: correspondência de cookie bidirecional
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.
Diagrama do fluxo de trabalho de correspondência de cookies
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, |
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]:
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_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 ( Exemplo: |
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_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:
|
google_ula |
Status da operação de adição da lista de usuários, repetido se vários Por exemplo: A operação
|
Cenários de exemplo do fluxo de trabalho da correspondência de cookie
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:
- O ExampleNews.com renderiza e chama anúncios do Google (Ad Manager).
- 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.
- O aplicativo proponente de FinestDSP recebe e processa a solicitação de lance e envia a resposta de lance.
- O Google recebe respostas de lances dos bidders, incluindo a resposta de FinestDSP que especifica um anúncio com uma match tag (pixel).
- FinestDSP vence o leilão. O Google veicula o anúncio de FinestDSP e a match tag para Jane.
- A tag de correspondência chama o serviço de correspondência de cookies do Google, especificando os parâmetros
google_nidegoogle_cm. - 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_gidegoogle_cverdefinidos. - O navegador de Jane carrega o redirecionamento para o URL de correspondência de cookie da FinestDSP.
- 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_gidna tabela de correspondências. - 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.
- A página da Web é renderizada, fazendo com que o Google (Ad Manager) solicite anúncios que serão renderizados na página.
- Durante o leilão de anúncios, o Google envia uma solicitação de lance para os bidders aplicáveis, incluindo FinestDSP.
- A FinestDSP recebe a solicitação de lance, incluindo indicadores como
google_gid. - O FinestDSP procura o
google_gidna tabela de correspondências e encontra o cookie associado a Jane, que foi criado uma semana antes (no cenário 1). - 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.
- Jane pode receber um anúncio personalizado de acordo com os interesses dela, com base nas informações que a FinestDSP tem.
Iniciada pelo proponente: correspondência de cookie unidirecional
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.
Etapa 1: colocar a tag de correspondência direcionada ao URL de correspondência de cookie do proponente
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.
Etapa 2: redirecionar para o serviço de correspondência de cookies do Google
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
Etapa 3: o navegador do usuário é redirecionado para o serviço de correspondência de cookies do Google
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" />
Etapa 5: o navegador do usuário é redirecionado para o URL do relatório de correspondência de cookie do bidder
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.
Diagrama do fluxo de trabalho de correspondência de cookies para usuários de estados dos EUA com restrições de privacidade
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âmetros de URL para redirecionamento do proponente ao serviço de correspondência de cookies do Google
| 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]:
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_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 ( Exemplo: |
Parâmetros de URL para redirecionamento do Google para o URL do relatório de correspondência de cookie do bidder
| 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
|
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" />
Etapa 2: o proponente precisa responder com um redirecionamento para o URL do serviço de correspondência de cookies do Google
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]:
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.
Etapa 3: redirecionar para o serviço de correspondência de cookies do Google
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
Etapa 4: o navegador do usuário é redirecionado para o serviço de correspondência de cookie do Google
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.
Assistente de correspondência de cookie
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.
Como funciona o Cookie Match Assist
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"/>
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.
- 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.
- 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.
Requisitos de consentimento dos usuários da UE
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:
- TCFv2: isso inclui os parâmetros
gdpregdpr_consent. Para mais detalhes, consulte a documentação do TCF v2.0 do IAB para Authorized Buyers. process_consent: uma declaração de que o proponente obteve o consentimento necessário do usuário.
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.
Conferir o fluxo de trabalho de correspondência de cookies e adicionar à lista de usuários
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.