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 do usuário do Google específico do bidder correspondente, além de criar listas de usuários que podem ajudar você a fazer escolhas de lances mais eficazes. Neste guia, descrevemos os conceitos usados na correspondência de cookie, além dos diferentes fluxos de trabalho correspondentes e as variações em casos de uso específicos.
conceitos
O que é 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 os usuários no domínio. Mesmo que dois proprietários de domínio concordem em trocar esses dados, o modelo de segurança dos navegadores da Internet impede que um deles leia 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 bidders que participam dos lances em tempo real podem ter o próprio domínio, em que identificam algum conjunto de usuários para mostrar anúncios. A correspondência de cookie permite que o bidder associe os cookies aos do Google para determinar se uma impressão enviada em uma solicitação de lance está associada a um dos usuários segmentados. Esse usuário vai receber os próprios dados de cookies ou um ID do usuário do Google específico do bidder que é uma forma criptografada do cookie doubleclick.net na solicitação de lance.
O serviço de correspondência de cookie descrito neste guia facilita a criação e a manutenção da associação entre o cookie de um bidder e o ID do usuário do Google, além de permitir o preenchimento de listas de usuários.
Tabelas de correspondências
Uma tabela de correspondências pode ser usada para mapear um ID ou outros dados de um domínio para outro. Os bidders podem usar o Serviço de correspondência de cookie para preencher as próprias tabelas de correspondência mapeando o cookie de um determinado usuário para o ID do usuário do Google do usuário ou para preencher uma tabela de correspondências hospedada pelo Google. As tabelas de correspondências são necessárias para que o aplicativo do bidder do bidder acesse os dados de cookies do usuário que está recebendo a impressão.
Tabelas de correspondências hospedadas pelo Google
Para facilitar a manutenção, as melhorias na latência e o acesso aos dados correspondentes para os usuários em determinadas regiões, é recomendável permitir que o Google hospede sua tabela de correspondências. Isso permite que você especifique uma string codificada em base64 segura para a Web, daqui em diante chamada de dados de correspondência hospedados, que será mapeada para o ID 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: nas solicitações de lance subsequentes para impressões associadas ao usuário, o Google enviará a você os dados de correspondência hospedados que correspondem ao ID de usuário do Google dele. Se o endpoint de lances estiver configurado para usar o protocolo RTB do Google, ele vai ser recebido como bytes decodificados pelo campo
BidRequest.hosted_match_data. Na implementação do OpenRTB do Google,BidRequest.user.buyeruidretornará esses dados como uma string codificada em base64 segura para a Web.Listas de usuários: as 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 que você receba 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 espaço de cookies.
Listas de usuários
As listas de usuários podem ser criadas e gerenciadas com a API de lances em tempo real. Depois de criadas, você pode preencher essas listas com os fluxos de trabalho de correspondência de cookie descritos abaixo ou por meio do serviço de upload em massa.
Vamos começar
Para começar a usar a correspondência de cookie, entre em contato com seu Gerente técnico de contas, que pode ativar fluxos de trabalho específicos e ajudar você a configurar o seguinte:
- ID da rede de correspondência de cookie (NID, 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 solicitações recebidas como parte dos fluxos de trabalho de correspondência de cookie. Os bidders podem incorporar macros nesse URL para controlar a ordem dos parâmetros transmitidos a ele nos fluxos de trabalho de correspondência de cookie.
- Match Tag: a tag que você precisa colocar no navegador de um usuário para o fluxo de trabalho de correspondência de cookie iniciado pelo bidder. Ele pode ser veiculado com anúncios ou colocado em propriedades da Web fora dos anúncios.
- URL do relatório de correspondência de cookie (opcional): no fluxo de trabalho unidirecional de correspondência de cookie, esse é um URL opcional que pode ser fornecido para especificar um endpoint que receberá detalhes de erros caso a correspondência de cookie falhe 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 cookie, mas o proponente pode solicitar que o redirecionamento seja sempre enviado.
- URL de assistência de correspondência de cookie: para trocas que implementam o fluxo de trabalho de assistência de correspondência de cookie, esse é o URL de base do endpoint destinado a responder às solicitações recebidas.
- Cota de assistência de correspondência de cookie: para trocas que implementam o fluxo de trabalho de assistência de correspondência de cookie, esse é o número máximo de solicitações que o URL de correspondência de cookie pode receber a cada segundo. Isso serve para evitar que solicitações de 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 cookie compatíveis, o URL de correspondência de cookie do bidder normalmente tem parâmetros anexados em uma ordem não garantida. Os bidders com integrações que exigem uma ordem consistente dos parâmetros podem colocar macros no URL de correspondência de cookie para garantir o posicionamento.
Macros com suporte
Os bidders podem configurar o URL de correspondência de cookie para incluir uma ou mais macros na forma de %%GOOGLE_<PARAM_NAME>%% ou %%GOOGLE_<PARAM_NAME>_PAIR%%. As macros compatíveis e os valores expandidos delas são:
| Macro | Valor ampliado |
|---|---|
| GOOGLE_GID | GOOGLE_USER_ID |
| GOOGLE_GID_PAIR | &google_gid=GOOGLE_USER_ID |
| GOOGLE_CVER | COOKIE_VERSION_NUMBER |
| GOOGLE_CVER_PAIR | &cver=COOKIE_VERSION_NUMBER |
| GOOGLE_ERROR | ERROR_ID |
| GOOGLE_ERROR_PAIR | &google_error=ERROR_ID |
| GOOGLE_PUSH | PIXEL_MATCH_DATA |
| GOOGLE_PUSH_PAIR | &google_push=PIXEL_MATCH_DATA |
| GOOGLE_ALL_PARAMS | google_gid=GOOGLE_USER_ID&cver=COOKIE_VERSION_NUMBER&google_error=ERROR_ID |
Exemplo de macro
Um bidder tem uma integração de correspondência de cookie com um endpoint hospedado em
https://user.bidder.com.cookies, e a implementação dele exige
parâmetros predefinidos definidos pelo bidder, além de parâmetros de correspondência de pixel
na seguinte ordem: google_push, google_gid, google_cver e
google_error. Para fazer isso, o bidder pode definir o URL de correspondência de cookie como:
https://user.bidder.com/cookies?w=0%%GOOGLE_PUSH_PAIR%%&x=1%%GOOGLE_GID_PAIR%%&y=2%%GOOGLE_CVER_PAIR%%&z=3%%GOOGLE_ERROR_PAIR%%
Posteriormente, quando o Google enviar uma solicitação de correspondência a esse bidder, ela será expandida para algo como:
https://user.bidder.com/cookies?w=0&google_push=PUSH_DATA&x=1&google_gid=GOOGLE_GID&y=2&google_cver=1&z=3
Fluxos de trabalho do Serviço de correspondência de cookie
Atualmente, o Serviço de correspondência de cookie do Google oferece suporte a três fluxos de trabalho para diferentes casos de uso, descritos abaixo.
Iniciado pelo bidder: correspondência de cookie bidirecional
A correspondência bidirecional de cookies se refere a um fluxo de trabalho iniciado pelo bidder, em que ele coloca 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. Abaixo está um exemplo simples desse fluxo de trabalho.
Etapa 1: inserir a Match Tag
Para iniciar esse fluxo, o bidder precisa inserir a tag de correspondência de modo que ela seja renderizada no navegador do usuário. Uma tag de correspondência simples que retorna somente o ID do usuário do Google para o bidder pode ser estruturada da seguinte maneira:
<img src="https://cm.g.doubleclick.net/pixel?google_nid=BIDDER_ACCOUNT_NID&google_cm" />
Existem outros parâmetros que podem ser incluídos na Match Tag 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 fará com que o Serviço de correspondência de cookie do Google receba uma solicitação do navegador do usuário, que emitirá um redirecionamento HTTP 302 para o URL de correspondência de cookie do bidder. O redirecionamento vai incluir parâmetros de consulta que especificam o ID do usuário do Google e o número da versão 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 ter a seguinte aparência:
https://ad.network.com/pixel?google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1
O ID do usuário do Google transmitido pelo parâmetro google_gid é uma string codificada em base64 segura para a Web sem preenchimento. Para proponentes que optarem por hospedar uma tabela de correspondências, é recomendável que eles armazenem a string exata retornada pelo Serviço de correspondência de cookie. Nas solicitações de lance subsequentes, isso corresponderá aos valores especificados por meio de BidRequest.google_user_id no protocolo de RTB do Google ou BidRequest.user.id na implementação do OpenRTB do Google.
A versão especificada em google_cver indica o número da versão numérica do ID de usuário do Google. O ID do usuário do Google de um determinado usuário muda com pouca frequência. Depois disso, ele é aumentado.
Se o Google encontrar um erro ao processar a 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 do cookie, incluindo os parâmetros especificados na primeira etapa e os fornecidos pelo Google na segunda. Além disso, eles também recebem o cookie nos cabeçalhos HTTP. Se a operação for bem-sucedida, um bidder que hospeda a própria tabela de correspondências pode associar o cookie ao ID de usuário do Google incluído na resposta. É recomendável que os bidders armazenem a string exata retornada pelo Serviço de correspondência de cookie.
Se a operação não for bem-sucedida, o proponente 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 neste link.
Se você receber um erro, tente encontrar esse usuário novamente inserindo uma nova tag de correspondência.
O bidder precisa sempre responder veiculando uma imagem de pixel invisível 1 x 1 ou, como alternativa, retornar uma resposta HTTP 204 Sem conteúdo.
Diagrama do fluxo de trabalho da correspondência de cookie
Esse fluxo de trabalho é ilustrado pelo diagrama abaixo, em que as solicitações e as 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 |
É o ID da rede (NID) da conta do bidder. Esse ID pode ser recuperado por meio do recurso Bidders. |
google_cm |
Indica ao Serviço de correspondência de cookie do Google que ele deve realizar a correspondência de cookie. O valor do parâmetro é ignorado e pode ser omitido. |
google_sc |
Esse parâmetro foi descontinuado. Define o cookie do Google para o usuário se não houver um. O valor do parâmetro é ignorado e pode ser omitido. A omissão do parâmetro resultará em um erro se não houver cookies. |
google_no_sc |
Esse parâmetro foi descontinuado. Isso indica que o Serviço de correspondência de cookie do Google não deve definir um cookie para o usuário se não houver um disponível. 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 (preenchimento opcional). Os dados brutos precisam ter até 40 bytes. Por exemplo, |
google_redir |
Uma string codificada em URL que um bidder pode especificar se quiser que o Google envie o redirecionamento HTTP 302 ao URL codificado da tag de correspondência. Isso permite que o Google seja colocado em primeiro plano em uma chamada encadeada para parceiros. Isso vai resultar em um erro se especificado sem
google_hm ou com google_cm. |
google_ula |
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 |
Indica que a solicitação está sujeita às restrições do GDPR sobre uso de dados. Para mais detalhes, consulte
Requisitos de consentimento de usuários da UE abaixo ou Impacto na qualificação da
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 os requisitos de consentimento dos usuários 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: |
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_ vão ser ignorados porque são reservados pelo Google para desenvolvimento futuro. Além disso, a preservação da ordem dos parâmetros não é garantida. Uma tag de correspondência que inclui parâmetros definidos pelo bidder pode ter esta aparência:
<img src="https://cm.g.doubleclick.net/pixel?google_nid=BIDDER_ACCOUNT_NID&google_cm&extra1=xx&extra2=yy" />
Parâmetros de URL de redirecionamento
O URL de redirecionamento é criado com base no URL básico de correspondência de cookie configurado na conta do bidder, incluindo google_ e parâmetros definidos pelo bidder, dependendo dos especificados na tag de correspondência. Os seguintes parâmetros de resposta google_ são definidos:
| Parâmetro | Descrição |
|---|---|
google_gid |
ID do usuário do Google. Definido se google_cm for especificado na solicitação e ela for bem-sucedida. |
google_cver |
Versão do cookie. Definido se google_cm for especificado na solicitação e ela for bem-sucedida. |
google_error |
Um valor inteiro que indica o erro geral da solicitação. Quando
recebido, nenhuma operação foi realizada e que nenhum outro
parâmetro de resposta
|
google_hm |
Vai aparecer somente 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 caso vários Por exemplo: A operação
|
Cenários de exemplo do fluxo de trabalho de correspondência de cookie
Os cenários a seguir descrevem como é a correspondência de cookie para um usuário típico navegando em uma página da Web.
Cenário 1: o usuário limpa os cookies e navega em um site
Jane limpa o cache de todos os cookies. Depois, ele acessa a página inicial de ExampleNews.com.
Veja o que acontece:
- ExampleNews.com é renderizado e chama anúncios do Google (Ad Manager).
- Como o bloco de anúncios está qualificado para alocação dinâmica, o Google envia solicitações de lance para FinestDSP e outros bidders por meio do serviço de lances em tempo real.
- O aplicativo proponente de FinestDSP recebe e processa a solicitação de lance e envia a resposta do lance.
- O Google recebe respostas de lance dos bidders, incluindo a resposta de FinestDSP que especifica um anúncio com uma tag de correspondência (pixel).
- FinestDSP vence o leilão. O Google veicula o anúncio de FinestDSP e a match tag para Jane.
- A Match Tag chama o Serviço de correspondência de cookie 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_user_idegoogle_cverdefinidos. - O navegador de Jane carrega o redirecionamento para o URL de correspondência de cookie de 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 deles para Jane nos cabeçalhos HTTP. FinestDSP agora pode armazenar o mapeamento do cookie para o
google_user_idna tabela de correspondências. - FinestDSP responde ao redirecionamento com um pixel 1 x 1 invisível.
Cenário 2: usuário com mapeamento atual
Uma semana após o Cenário 1, Jane acessa ExampleNews.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.
- FinestDSP recebe a solicitação de lance, incluindo indicadores como o
google_user_id. - FinestDSP pesquisa o
google_user_idna tabela de correspondências e encontra o cookie associado a Jane que foi criado uma semana antes (cenário 1). - Com base nas informações associadas ao cookie, a lógica de lances de FinestDSP faz um lance na impressão e vence o leilão.
- Jane pode ver um anúncio adaptado aos interesses dela, com base nas informações que FinestDSP possui.
Iniciado pelo bidder: correspondência de cookie unidirecional
A correspondência unidirecional de cookies é semelhante ao fluxo de trabalho bidirecional, mas é alterada de modo que apenas o Google hospeda e preencha uma tabela de correspondências. Isso pode ser usado nos 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. Para usar esse fluxo, os bidders precisam permitir que o Google hospede a tabela de correspondências, não podem mais especificar google_cm em solicitações para o Serviço de correspondência de cookie do Google e, consequentemente, não recebem google_gid para preencher a própria tabela de correspondências. Depois que o Google estabelecer uma correspondência para um usuário, os bidders poderão 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: inserir a match tag direcionada ao URL de correspondência de cookie do bidder
Para iniciar esse fluxo, um bidder precisa colocar uma tag de correspondência para que ela
seja renderizada no navegador do usuário. Diferentemente do fluxo de trabalho para usuários de um estado dos EUA com restrições de privacidade, a tag de correspondência precisa direcionar o navegador do usuário para o URL de correspondência de cookie. Por exemplo, com um URL de correspondência de cookie configurado como https://ad.network.com/pixel, ele teria esta aparência:
<img src="https://ad.network.com/pixel" />
Ao carregar no navegador do usuário, ele solicita um pixel do URL de correspondência de cookie do bidder. Essa solicitação contém o cookie no cabeçalho HTTP, que precisa ser extraído para a próxima etapa.
Etapa 2: redirecionar para o Serviço de correspondência de cookie do Google
O endpoint de correspondência de cookie do bidder precisa redirecionar para o serviço de correspondência de cookie do Google, incluindo o parâmetro google_hm preenchido com os dados de cookies codificados em base64 e seguros para a Web. O URL de redirecionamento pode ser semelhante ao
seguinte:
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 cookie do Google
O Google receberá um redirecionamento contendo os parâmetros especificados, além do cookie do Google nos cabeçalhos HTTP.
Etapa 4: o Google veicula o pixel em caso de êxito ou erro de redirecionamento se o URL do relatório for especificado
Se a operação de correspondência de cookie for bem-sucedida, ou se nenhum URL do Relatório de correspondência de cookie tiver sido especificado para a conta do bidder, o Google veiculará um pixel transparente 1 x 1 por padrão, e o fluxo de trabalho terminará aqui.
As impressões desse usuário nas solicitações de lance subsequentes vão incluir os dados de correspondência hospedados pelo bidder em BidRequest.hosted_match_data para o protocolo do Google ou BidRequest.user.buyeruid para a implementação do OpenRTB do Google. Os bidders também podem preencher listas de usuários com os dados de correspondência hospedados especificados.
Caso contrário, se ocorrer um erro, o Google vai enviar um redirecionamento para o URL do Relatório de correspondência de cookie do bidder com a causa do erro especificada no parâmetro google_error. Se o URL do Relatório de correspondência de cookie do bidder fosse https://ad.network.com/report, o URL de redirecionamento seria assim:
<img src="https://ad.network.com/report?google_error=ERROR_ID" />
Etapa 5: o navegador do usuário redireciona para o URL do Relatório de correspondência de cookie do bidder
O navegador do usuário vai redirecionar o usuário 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 como interpretar o código do erro, consulte a descrição do parâmetro.
Etapa 6: o proponente veicula um pixel transparente 1 x 1
O bidder precisa responder veiculando um pixel transparente de 1 x 1 para o navegador do usuário.
Diagrama do fluxo de trabalho de correspondência de cookie para usuários de estados dos EUA com restrições de privacidade
O fluxo de trabalho padrão para usuários nos 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.
Os parâmetros de URL do proponente redirecionam para o Serviço de correspondência de cookie do Google
| Parâmetro | Descrição |
|---|---|
google_nid |
É o ID da rede (NID) da conta do bidder. Esse ID pode ser recuperado por meio do recurso Bidders. |
google_sc |
Esse parâmetro foi descontinuado. Define o cookie do Google para o usuário se não houver um. O valor do parâmetro é ignorado e pode ser omitido. A omissão do parâmetro resultará em um erro se não houver cookies. |
google_no_sc |
Esse parâmetro foi descontinuado. Isso indica que o Serviço de correspondência de cookie do Google não deve definir um cookie para o usuário se não houver um disponível. 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ências hospedada pelo Google. |
google_redir |
Um URL codificado para o qual você quer que o Google envie um redirecionamento HTTP 302. O URL especificado receberá redirecionamentos com o parâmetro google_error para erros e operações bem-sucedidas. |
google_ula |
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 |
Indica que a solicitação está sujeita às restrições do GDPR sobre uso de dados. Para mais detalhes, consulte
Requisitos de consentimento de usuários da UE abaixo ou Impacto na qualificação da
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 os requisitos de consentimento dos usuários 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: |
Os parâmetros de URL do Google redirecionam 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, 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 do Serviço de correspondência de cookie do Google em que o Google tenta fazer a correspondência de um ID de usuário do Google com um bidder selecionado por algoritmos que não seja o vencedor do leilão de lances em tempo real. Quando um anúncio é inserido, o Google coloca uma tag de correspondência direcionando o navegador do usuário para carregar um pixel transparente do URL de correspondência de cookie do bidder escolhido. Assim, o Google e o bidder podem preencher uma tabela de correspondências com um determinado usuário. Veja abaixo um exemplo simples desse fluxo de trabalho.
Etapa 1: o Google coloca uma Match Tag
Quando a página de um editor participante é carregada no navegador do usuário, e um espaço de anúncio nessa página é preenchido pelo Google, uma tag de correspondência pode ser colocada que solicita um pixel de um bidder selecionado por algoritmos. A tag de correspondência de pixel inserida 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. Para um URL de correspondência de cookie especificado como https://ad.network.com/pixel, ele é 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 bidder precisa responder com redirecionamento para o URL do Serviço de correspondência de cookie do Google
Os bidders que recebem solicitações de correspondência de pixel precisam responder com um redirecionamento para o Serviço de correspondência de cookie do Google, estruturado da seguinte forma:
https://cm.g.doubleclick.net/pixel?google_nid=GOOGLE_NID&google_push=PUSH_DATA
O URL de redirecionamento acima é semelhante ao do URL usado na tag de correspondência para o fluxo de trabalho de correspondência de cookie 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 fornecido pelo Google na solicitação. Também semelhante ao fluxo de trabalho iniciado pelo bidder, parâmetros adicionais podem ser especificados para atender a outros casos de uso.
Etapa 3: o Google processa o redirecionamento e responde com pixels
O Google registra que uma correspondência foi criada para o usuário e processa todas as operações adicionais solicitadas por meio de 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 as 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 de um estado fora dos EUA com restrições de privacidade, isso sempre será especificado na Match Tag do Google. |
google_cver |
A versão do cookie. Isso sempre será especificado na match tag do Google. |
google_push |
Indica que esta solicitação está iniciando o fluxo de trabalho de correspondência de pixel. O valor precisa ser retornado por meio do parâmetro correspondente na resposta de redirecionamento do bidder. |
Parâmetros de redirecionamento da correspondência de pixel do bidder
| Parâmetro | Descrição |
|---|---|
google_nid |
É o ID da rede (NID) da conta do bidder. Esse ID pode ser recuperado por meio do 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 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 |
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. |
Iniciada pelo Google: correspondência unidirecional de pixels
A correspondência unidirecional de pixels é diferente do fluxo de trabalho bidirecional, porque a Match Tag do Google não inclui um parâmetro que especifica o ID do usuário do Google, mas continua preenchendo uma tabela de correspondências hospedada pelo Google. Isso pode ser usado em casos em que o bidder não tem permissão para hospedar IDs de usuário do Google na própria tabela de correspondências. Confira um exemplo simples do fluxo de trabalho revisado nas etapas abaixo.
Etapa 1: o Google coloca uma Match Tag
O Google coloca uma tag de correspondência para um proponente selecionado por algoritmos. A tag de correspondência inclui o parâmetro google_push. Confira 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 culinária do bidder
O navegador do usuário solicita um pixel do URL de correspondência de cookie do bidder, incluindo o cookie dele nos cabeçalhos HTTP.
Etapa 3: redirecionar para o Serviço de correspondência de cookie do Google
O endpoint de correspondência de cookie do bidder precisa redirecionar para o serviço de correspondência de cookie do Google, incluindo o parâmetro google_hm preenchido com os dados de cookies codificados em base64 e seguros para a Web. O URL de redirecionamento pode ser semelhante ao
seguinte:
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 receberá um redirecionamento contendo os parâmetros especificados, além do cookie do Google nos cabeçalhos HTTP. Se a operação tiver sido bem-sucedida, as impressões desse usuário nas solicitações de lance subsequentes vão incluir os dados de correspondência hospedados do bidder em BidRequest.hosted_match_data para o protocolo do Google ou BidRequest.user.buyeruid para a implementação do OpenRTB do Google. Eles também podem preencher listas de usuários com os dados de correspondência hospedados especificados.
Finalmente, o Google retorna um pixel transparente 1 x 1 para o navegador do usuário.
Assistência 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 iniciados pelo Google para fazer a correspondência de um ID do usuário do Google com o cookie. O Cookie Match Assist (CMA) é um recurso adicional para trocas que permite criar tabelas de correspondências com os próprios bidders.
Como o Assistente de correspondência de cookie funciona
Ao inserir um anúncio, o Google seleciona algoritmicamente uma troca participante e coloca uma tag do Assistente de correspondência de cookie com a seguinte estrutura:
<img src="https://ob.exchange.com/pixel?google_gid=GOOGLE_GID&google_cver=1"/>
A tag de correspondência 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 cookie da troca recebe a solicitação, em que o próprio serviço de correspondência de cookie é responsável por corresponder o ID do usuário a um dos bidders. No diagrama abaixo, o serviço de correspondência de cookie de troca responde ao navegador do usuário com um redirecionamento para um dos endpoints do bidder.
- O bidder recebe a solicitação e os parâmetros especificados pela troca para fazer a correspondência do ID do usuário com o cookie.
Restrições
Limitar a frequência das solicitações de novas correspondências
Os bidders são responsáveis por limitar o número de chamadas para o serviço de correspondência de cookie para usuários que têm uma nova entrada na tabela de correspondências hospedada pelo Google. Uma entrada na tabela de correspondências hospedada pode ser considerada expirada em 14 dias. Depois desse prazo, ela pode ser atualizada.
Responder a todas as solicitações de correspondência de pixel
Os bidders que usam o fluxo de trabalho de correspondência de pixel precisam responder a todas as solicitações de correspondência de pixel recebidas com uma resposta incluindo o parâmetro google_push. Isso permite que o Google monitore o uso para aplicar políticas. 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 para a conta dele.
Usar endpoints HTTPS
É necessário que os endpoints usados em todos os fluxos de trabalho de correspondência de cookie usem HTTPS.
Ao responder a uma solicitação de correspondência de pixel enviada a você por HTTPS, é necessário redirecionar para o Serviço de correspondência de cookie por HTTPS. Da mesma forma, um endpoint de assistência de correspondência de cookie que redireciona para bidders também precisa usar HTTPS. Se você envia solicitações ao Google por HTTP mais de uma vez a cada dois minutos, o número de solicitações de correspondência enviadas para sua conta é limitado.
Requisitos de consentimento de usuários da UE
As solicitações de correspondência de cookie sujeitas à Política de consentimento de usuários da União Europeia do Google precisam indicar o consentimento do usuário final. Essas solicitações são necessárias para indicar que o consentimento foi obtido de uma das seguintes maneiras:
- TCF v2: inclui os parâmetros
gdpregdpr_consent. Para mais detalhes, consulte a documentação do IAB TCF v2.0 do Authorized Buyers. process_consent: uma declaração de que o bidder recebeu o consentimento necessário do usuário.
Exemplos
Os exemplos abaixo ilustram como usar o Serviço de correspondência de cookie para atingir objetivos específicos. A menos que indicado de outra forma, presume-se que o usuário que está recebendo a ação não é de um estado dos EUA com restrições de privacidade.
Preencher uma tabela de correspondência hospedada pelo bidder
Um bidder pode usar o fluxo de trabalho de correspondência de cookie 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 cookie do bidder estiver definido como https://ad.network.com/pixel?id=1 e a operação de correspondência de cookie for bem-sucedida, o redirecionamento que o Google envia em resposta à tag de correspondência do bidder terá esta aparência:
https://ad.network.com/pixel?id=1&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1
Se a operação de correspondência de 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. Para saber mais sobre possíveis códigos de erro do fluxo de trabalho da correspondência de cookie, consulte os parâmetros de URL de redirecionamento.
Adicionar a uma lista de usuário único
O parâmetro google_ula pode ser especificado na tag de correspondência de um bidder para adicionar o usuário a uma lista com o ID fornecido. Se o Google ou a tabela de correspondências hospedada pelo bidder tiver uma nova entrada para o usuário, o bidder poderá inserir uma tag de correspondência incluindo os parâmetros google_nid e google_ula para adicionar o usuário à lista especificada sem iniciar o fluxo de trabalho completo de correspondência de cookie. Consulte as restrições à invocação do Serviço de correspondência de cookie para mais detalhes. A tag de correspondência correspondente pode ter esta aparência:
<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 cookie do bidder é https://ad.network.com/pixel, o URL de redirecionamento do Google seria:
https://ad.network.com/pixel?google_ula=12345,0
Se houver um erro geral (por exemplo, não houver um cookie do Google para o usuário), o URL de redirecionamento incluirá o parâmetro google_error:
https://ad.network.com/pixel?google_error=3
Se houver um erro especificamente em relação à adição do usuário à lista, você receberá google_ula no redirecionamento. Ao contrário do parâmetro de tag de correspondência correspondente, essa função 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 falhou porque a conta do proponente não tinha acesso à lista de usuários especificada, o URL de redirecionamento será:
https://ad.network.com/pixel?google_ula=12345,2
Adicionar a várias listas de usuários
Os bidders podem especificar que um usuário 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 assim:
<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 é relatado de maneira semelhante por
parâmetros google_ula distintos no redirecionamento:
https://ad.network.com/pixel?google_ula=12345,2&google_ula=45678,0
No redirecionamento acima, a operação foi bem-sucedida para a lista de usuários com o código 45678, mas falhou para o código 12345 porque o proponente não tinha permissão para acessá-la.
Siga o fluxo de trabalho da correspondência de cookie e adicione à lista de usuários
Para realizar 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 do bidder precisa incluir google_cm e google_ula:
<img src="https://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345&google_cm" />
O URL de redirecionamento especificado pelo Google incluiria google_gid, google_cver e google_ula. A aparência será semelhante a esta:
https://ad.network.com/pixel?id=&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1&google_ula=12345,0
Como 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 quiser armazenar a correspondência com o ID do usuário do Google na própria tabela, a tag de correspondência precisará incluir o parâmetro google_hm, em que o valor precisa ser uma string codificada em base64 e otimizada para a Web. Para um usuário em que os dados de cookies não codificados do bidder são Cookie number 1!, o valor codificado seria Q29va2llIG51bWJlciAxIQ==, que seria usado em uma tag de correspondência como esta:
<img src="https://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=Q29va2llIG51bWJlciAxIQ%3D%3D" />
Para uma resposta bem-sucedida, em que o URL de correspondência de cookie do bidder é https://cookie-monster.com/pixel, o URL de redirecionamento do Google seria:
https://cookie-monster.com/pixel
O parâmetro google_gid não está no redirecionamento porque a tag de correspondência não incluía google_cm, e google_hm não está incluído em respostas bem-sucedidas. Em solicitações de lance futuras para impressões
desse usuário, o bidder vai receber os dados de correspondência hospedados em
BidRequest.hosted_match_data para o protocolo de RTB do Google ou
BidRequest.user.buyeruid para a implementação do OpenRTB do Google.
Se, em vez disso, o bidder tiver usado uma tag de correspondência em que o valor de
google_hm não fosse codificado em base64, como
chocolate_chunk!, o URL de redirecionamento vai ficar assim:
https://cookie-monster.com/pixel?google_hm=2
O URL de redirecionamento acima inclui um valor google_hm de 2, sugerindo que a operação falhou porque o valor não pôde ser decodificado.
Tabelas de correspondências hospedadas pelo Google e do bidder com listas de usuários
Se um bidder hospedar a própria lista de uso, além de uma lista de usuários hospedada pelo Google, e quiser 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 vai precisar incluir os parâmetros google_cm, google_hm e google_ula. Se os dados de cookies do bidder forem Cookie number 1!, o valor codificado será Q29va2llIG51bWJlciAxIQ==, o que produziria 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 teria esta aparência:
https://cookie-monster.com/pixel?google_gid=ABCDETC&google_cver=1&google_ula=12345,0
Ao receber o redirecionamento, o bidder pode associar o ID do usuário do Google especificado em google_gid aos dados de cookies na tabela de correspondências. Além disso, eles podem determinar que as operações da tabela de correspondências hospedada pelo Google e da lista de usuários foram bem-sucedidas. Como consequência, qualquer pré-segmentação do bidder configurada para segmentar o ID da lista de usuários especificado vai fazer 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 recebe os dados de correspondência hospedados em
BidRequest.hosted_match_data para o protocolo de RTB do Google ou
BidRequest.user.buyeruid para a implementação do OpenRTB do Google.