Correspondência de cookie

Os tópicos a seguir explicam como o Serviço de correspondência de cookie ajuda você a fazer escolhas de lances mais eficientes.

  1. O que é correspondência de cookie?
  2. Contexto
  3. Benefícios das tabelas de correspondências hospedadas
  4. Como a correspondência de cookie funciona
  5. Como usar o Serviço de correspondência de cookie
  6. Correspondência de pixel
  7. Restrições
  8. Especificações da API
  9. Como migrar da Cookie Matching Service v1 API
  10. Exemplos
Importante: este documento descreve a versão mais recente da Cookie Matching Service API, a V2. Se seu aplicativo usa a V1, consulte a especificação da V1.

O que é correspondência de cookie?

Com o Serviço de correspondência de cookie, um comprador pode associar dois tipos de dados:

  1. o cookie que identifica um usuário dentro do domínio do comprador e
  2. o cookie doubleclick.net que identifica o usuário para o Google. Compartilhamos um ID de usuário do Google criptografado específico para o comprador para a correspondência de compradores.

A estrutura de dados que o comprador usa para manter essas associações é chamada de Tabela de correspondência. Embora o comprador seja responsável por criar e manter tabelas de correspondências, o Google pode hospedá-las.

Com um aplicativo RTB, o comprador pode dar um lance para impressões em que o usuário possui um ID de usuário do Google específico e pode usar informações associadas ao ID de usuário do Google como critérios em um lance para uma impressão de anúncios. Se o Google hospedar a tabela de correspondências, isso poderá simplificar a integração, diminuir a latência e permitir melhorias futuras.

Voltar ao início

Contexto

Geralmente, um cookie de navegador é definido pela parte proprietária do domínio ao qual o cookie pertence. O cookie identifica um usuário nesse domínio. O modelo de segurança do navegador restringe para uma parte a leitura do cookie definido por outra parte, mesmo que ambas as partes acabem concordando com uma troca assim.

O comprador costuma identificar usuários com cookies pertencentes ao domínio de uma rede de anúncios de terceiros. O comprador pode indexar um banco de dados das informações de usuário com esses cookies.

Para ele próprio, o Google identifica usuários com cookies pertencentes ao domínio doubleclick.net no qual o Google veicula anúncios. Para os compradores, o Google identifica usuários usando um ID de usuário do Google específico do comprador, que é uma versão criptografada do cookie doubleclick.net, derivada do cookie, mas não equivalente a ele. O Google passa o ID do usuário do Google para o comprador (cookies brutos do DoubleClick jamais são enviados).

Ao receber determinado ID de usuário do Google pela primeira vez, o comprador não tem conhecimento sobre o usuário associado ao ID de usuário do Google a não ser o que a solicitação revelar. O comprador pode associar o ID de usuário do Google com um cookie de comprador e, subsequentemente, considerar as informações de usuário associadas com o cookie de comprador para tomar decisões sobre os usuários identificados pelo ID de usuário do Google. Isso pode ser útil em campanhas de remarketing e para refinar a segmentação ou lances para impressões, à medida que elas ficarem disponíveis em tempo real.

O Serviço de correspondência de cookie fornece a informação de que uma rede de comprador precisa manter uma associação entre o cookie de comprador e o ID de usuário do Google, na forma de uma estrutura de dados chamada de Tabela de correspondências. Além disso, o comprador pode fornecer dados ao Google a serem armazenados e adicionados a solicitações de lance futuras.

Voltar ao início

Benefícios das tabelas de correspondências hospedadas

Importante: entre em contato com o representante da conta para ter acesso a esse serviço.

Compradores que optam por ter o Google hospedando suas tabelas de correspondências continuam recebendo os seguintes benefícios:

  • Menos infraestrutura de suporte
  • Mapeamento do ID de usuário do Google para uma forma útil não exige mais uma pesquisa de tabela
  • Durante a pré-segmentação, há a opção de filtrar a existência ou não de uma correspondência de cookie, o que pode reduzir solicitações de lance não desejadas

Voltar ao início

Como a correspondência de cookie funciona

Para criar uma associação na tabela de correspondências, o comprador precisa veicular uma tag fornecida pelo Google, chamada de Match Tag. A Match Tag pode ser veiculada com os anúncios do comprador ou pode ser colocada em suas propriedades da Web fora dos anúncios. Ela é estruturada da seguinte forma:

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

Aqui, 1234 seria substituído pelo identificador do comprador fornecido pelo Google.

O comprador só deverá veicular essa tag se ele ainda não tiver uma correspondência para o usuário (ou se a entrada for obsoleta).

Recebendo a solicitação para a tag do navegador do usuário, o Google emite um redirecionamento 302 para o comprador. Esse redirecionamento 302 inclui o ID de usuário do Google e um número de versão no URL, além do cookie do comprador, nos cabeçalhos de solicitação. O comprador fornece o URL base, e o Google adiciona parâmetros de URL adicionais.

Por exemplo, se o comprador fornecer este URL base:

http://ad.network.com/pixel

O Google redirecionará para um URL como este:

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

O ID de usuário do Google passado pelo parâmetro google_gid é uma string codificada em base64 segura para Web sem preenchimento. Recomendamos o armazenamento da string exata retornada pelo Serviço de correspondência de cookie na tabela de correspondências.

Observação: o campo google_user_id no buffer de protocolo BidRequest corresponde ao ID de usuário do Google retornado pelo Serviço de correspondência de cookie.

O parâmetro google_cver indica uma versão numérica do ID de usuário do Google. O Google pode alterar sem frequência o esquema de cookie obsoleto, quando o valor google_cver verá aumentado.

O comprador recebe esse redirecionamento, que inclui o cookie de comprador nos cabeçalhos das solicitações e atualiza a Match Table com a associação entre esse cookie de comprador e o ID de usuário do Google. O comprador deverá veicular um pixel de imagem invisível de 1x1 para o navegador do usuário ou retornar uma resposta 204 Sem conteúdo.

As entradas são adicionadas à tabela de correspondências com a taxa na qual as Match Tags são veiculadas para usuários únicos.

Esse processo é ilustrado pelo diagrama abaixo. Cada solicitação ou resposta é representada por uma seta e os itens de dados que acompanham a solicitação ou resposta são listados entre parêntesis.

Você pode escolher definir parâmetros de URL extras na solicitação, e eles são passados para seu servidor no redirecionamento:

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

Todos os parâmetros que não começarem com o parâmetro google_ são copiados no URL de redirecionamento. A ordem em que os parâmetros são passados para o Serviço de correspondência de cookie não é importante. Da mesma forma, a ordem na qual parâmetros extras são passados no URL de redirecionamento não é garantida.

http://ad.network.com/pixel?google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1&extra1=xx&extra2=yy

Você pode usar esses parâmetros para passar informações adicionais sobre a impressão. Os parâmetros extras não devem ter mais de um kilobyte.

Também é possível fazer solicitações https em vez de http para o serviço de correspondência de cookie. Nesse caso, o protocolo do URL de redirecionamento será https e não http.

Cenários de exemplo

Como seria a correspondência de cookie para um usuário da Web típica, e o que está acontecendo nos bastidores? Vejamos dois cenários.

Cenário 1: cookies limpos

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

Veja o que acontece:

  1. ExampleNews.com renderiza e chama anúncios do Google (DoubleClick for Publishers).
  2. Como o bloco de anúncios é qualificado para a alocação dinâmica, o Ad Exchange envia solicitações de lance para FinestDSP (entre outros DSPs).
  3. FinestDSP processa a solicitação de lance em seu mecanismo de lance e envia sua resposta de lance para o Ad Exchange
  4. FinestDSP vence o leilão e envia um anúncio e uma match tag (pixel) para o Ad Exchange.
  5. O Ad Exchange veicula o anúncio do FinestDSP e a match tag para Jane, além de também definir o cookie da DoubleClick de Jane.
  6. A match tag chama o Serviço de correspondência de cookie do Google.
  7. O Serviço de correspondência de cookie lê o cookie da DoubleClick de Jane e envia um redirecionamento para FinestDSP com google_user_id definido.
  8. O navegador carrega o URL de FinestDSP.
  9. FinestDSP gera um cookie, que o armazena no google_user_id de Jane em sua tabela de correspondências.
  10. FinestDSP descarta seu cookie no navegador de Jane e responde ao redirecionamento com um pixel invisível de 1x1.

Cenário 2: cookies do comprador e da DoubleClick

Uma semana depois do Cenário I, Jane visita ExampleNews.com novamente. Agora que Jane tem cookies do comprador e da DoubleClick em sua máquina, vejamos como funciona a correspondência.

  1. A página da Web é renderizada, executando a chamada do código HTML para anúncios do Google.
  2. Durante o leilão de anúncios, o DoubleClick Ad Exchange envia uma solicitação de lance para um comprador de RTB, FinestDSP, oferecendo a esse comprador a opção de definir lances para a impressão.
  3. O comprador recebe a solicitação de lance com informações da impressão e o google_user_id.
  4. FinestDSP pesquisa o google_user_id em sua tabela de correspondências para encontrar o cookie criado uma semana antes (cenário I).
  5. Com base nas informações associadas a seu cookie, FinestDSP decide definir um lance e ganha a impressão.
  6. Jane pode ver um anúncio personalizado segundo seus interesses com base nas informações de FinestDSP.

Voltar ao início

Como usar o Serviço de correspondência de cookie

Esta seção explica como compradores podem usar o Serviço de correspondência de cookie.

Pré-requisitos

Para poder usar o Serviço de correspondência de cookie, você deve ter:

  • uma conta do Ad Exchange e
  • um proponente em tempo real ativo e em funcionamento

Em seguida, você precisa fornecer ao Google seu URL de redirecionamento. Esse é o URL para o qual o Serviço de correspondência de cookie deve redirecionar a solicitação de sua match tag. Essa solicitação vem do navegador do usuário, conforme descrito em Como a correspondência de cookie funciona acima.

Você pode fornecer ao Google o URL de redirecionamento pelo representante de conta do Ad Exchange. Ou, se tiver acesso à REST API de comprador do Ad Exchange, você poderá definir o URL usando um dos métodos para atualizar um Recurso de contas.

Veiculação da match tag do cookie

Você deve ter a possibilidade de colocar a tag do pixel de correspondência fornecida pelo Google no navegador do usuário. Convém optar por colocar esse pixel com anúncios veiculados, ou em propriedades da Web, sob seu controle.

Veiculação de pixels

Seus servidores precisam reconhecer o URL de redirecionamento e veicular um pixel vazio de 1x1 para o navegador do usuário em tempo hábil. Durante o processamento de solicitações recebidas para o URL de redirecionamento, seus servidores também devem analisar o URL para extrair o ID de usuário do Google e os códigos de erro, além de atualizar a tabela de correspondências.

Tratamento de erros

O Serviço de correspondência de cookie comunica erros no parâmetro de URL especial google_error no redirecionamento. O valor desse parâmetro é numérico e identifica o erro ocorrido especialmente. Você ainda deverá responder com um pixel vazio de 1x1 se o parâmetro de URL google_error estiver presente.

Se receber um erro, você poderá mostrar uma match tag para o cookie do comprador relacionado novamente.

Voltar ao início

Correspondência de pixel

Na correspondência de cookie, o comprador que vence o leilão para uma impressão pode associar um cookie com um ID de usuário do Google. Em outro componente do código de correspondência de cookie do Google, chamado de correspondência de pixel, o Google seleciona por algoritmos um comprador adicional cujo cookie pode ser correspondido com o ID de usuário do Google. Em seguida, o Google coloca uma match tag na impressão e inclui o URL do comprador escolhido na match tag.

Isso prepara o cenário para a interação a seguir:

  1. Quando a página é carregada no navegador do usuário, a match tag gera uma solicitação de pixel para o comprador.
    • Se você for o comprador escolhido:
      1. Você recebe seu próprio cookie junto com o ID de usuário do Google, permitindo a associação os dois em sua tabela de correspondências, e
      2. Você precisa redirecionar a solicitação de volta para o Google.
  2. O comprador escolhido responde com um redirecionamento.
  3. O Google recebe o redirecionamento e armazena a correspondência entre o usuário e o comprador.
  4. O Google veicula o pixel no navegador.

A correspondência de pixel não funciona nas propriedades de editores que desativaram a correspondência adicional.

Como trabalhar com a correspondência de pixel

O Google coloca a Match Tag na página, que combina um URL fornecido pelo comprador com o ID de usuário do Google (o parâmetro google_gid) e um novo parâmetro google_push. A Match Tag é estruturada desta forma:

  • <img src=”http://ad.network.com/pixel?google_gid=abcdef&google_cver=1&google_push=abcd” />

A Match Tag faz com que o comprador receba uma solicitação para o pixel (consulte o item 1 no diagrama abaixo). Ao receber a solicitação, o comprador faz um redirecionamento para um URL estruturado desta forma:

  • http://cm.g.doubleclick.net/pixel?google_nid=1234&google_push=abcd

Esse URL é semelhante ao usado na correspondência de cookie iniciada pelo comprador, exceto que o parâmetro google_push substitui o parâmetro google_cm. O comprador também tem a opção de adicionar parâmetros como google_ula ou google_hm.

Observação: os parâmetros google_push e google_cm nunca podem aparecer na mesma solicitação.

A resposta que o comprador envia para o navegador é retratadas pelo item 2 no diagrama abaixo, e o redirecionamento que o navegador envia para o Google é retratado pelo item 3.

Ao receber o redirecionamento, o Google retorna um pixel invisível (item 4 no diagrama). Em seguida, o Google registra que uma correspondência foi criada para o usuário. O Google também trata todas as outras operações solicitadas, como armazenar dados hospedados ou adicionar o usuário a uma lista de usuários. O Google aguarda 14 dias, até a correspondência usuário-comprador expirar, antes de introduzir a correspondência novamente.

No diagrama abaixo, cada solicitação ou resposta é representada por uma seta e os itens de dados que acompanham a solicitação ou resposta são listados entre parêntesis.

Voltar ao início

Restrições

Esta seção descreve as restrições impostas pelo Google para poder proteger a privacidade do usuário e assegurar uma experiência do usuário agradável.

Como assegurar a privacidade do usuário

O Serviço de correspondência de cookie protege a privacidade do usuário respeitando os seguintes princípios:

  • O Google não aceita informações de usuário fornecidas pelo comprador (como o cookie, as informações demográficas do usuário etc.)
  • O Google proíbe vários compradores de ingressar nas tabelas de correspondências.
  • O Serviço de correspondência de cookie não expõe o cookie da DoubleClick do Google.
  • A finalidade da tabela de correspondências é permitir que os compradores usem as informações próprias sobre o usuário na transação com o Google. Sob nenhuma circunstância, o Serviço de correspondência de cookie deve ser usado com a finalidade da colheita de dados, conforme especificado em contratos e políticas do Ad Exchange.

Os proponentes devem oferecer suporte aos princípios acima, além de proteger a privacidade do usuário em suas implementações.

Limite de frequência

Você, como o comprador, é responsável pelo limite de frequência do Serviço de correspondência de cookie para que ele não seja usado para servidores que já tenham uma entrada atualizada na tabela de correspondências. Você não deve veicular a tag da correspondência de cookie a menos que a tabela de correspondências não tenha uma entrada para o usuário em questão, ou a entrada seja obsoleta. Depois de 14 dias, convém considerar a entrada de correspondência expirada e atualizá-la.

O Google não aplica o limite de frequência durante a veiculação. No entanto, ele monitora periodicamente se você está respeitando a política do limite de frequência, além de reservar o direito de interromper o serviço em caso de violação.

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

Ao se inscrever para usar o serviço de correspondência de pixel, esperamos que você responda a todas as solicitações de correspondência de pixel. Assim, podemos monitorar várias políticas que abordam o modo como você está usando esse serviço. Se sua taxa de resposta ficar abaixo de 90%, limitaremos o número solicitações de correspondência de pixel que enviamos para sua conta.

Como respeitar o máximo para a taxa de solicitação

Quando você se inscreve no Serviço de correspondência do cookie, o Google fornece uma taxa de solicitação máxima. O Google monitora suas transações para garantir que você respeite essa taxa de solicitação.

Voltar ao início

Especificações da API

Match Tag

A Match Tag precisa conter o ID do comprador (passado por meio do parâmetro google_nid), assim como o URL do Serviço de correspondência de cookie. O protocolo pode ser http ou https. Veja exemplos de URLs de Match Tag válidos:

http://cm.g.doubleclick.net/pixel?google_nid=my_nid
https://cm.g.doubleclick.net/pixel?google_nid=my_nid
Observação: as solicitações acima não são operacionais porque não foi especificada nenhuma operação.

O Google reserva todos os parâmetros de URL para o Serviço de correspondência com o prefixo google_ para uma expansão de API futura. Todos os outros parâmetros de URL adicionados à Match Tag são passados para o URL de redirecionamento não interpretado.

O Serviço de correspondência de cookie é compatível com várias operações:

  • Realizar correspondência de cookie -- a operação de correspondência de cookie básica descrita acima.
  • Adicionar o usuário a uma lista de usuários -- adiciona o usuário a uma lista de usuários, o que evita a necessidade de uma tag separada.
  • Definir cookie se não encontrado -- normalmente, o Serviço de correspondência de cookie não define um cookie doubleclick.net no navegador do usuário se ainda não houver um presente. Quando essa opção é definida, o Serviço de correspondência de cookie define o cookie doubleclick.net.

Essas operações são suportadas por meio dos parâmetros de URL a seguir:

Parâmetro Descrição
google_nid ID da rede. Trata-se do ID de um comprador. Aqui, "network" refere-se ao comprador típico, uma rede de anúncios. O parâmetro nid da correspondência de cookie v1 possui a mesma função.
google_cm Realize a correspondência de cookie. O valor no qual o parâmetro é definido é ignorado e pode ser omitido.
google_sc Define o cookie caso ele não esteja presente. O valor do parâmetro é ignorado e pode ser omitido. A omissão do parâmetro resulta em um erro se nenhum cookie doubleclick estiver presente.
google_no_sc Não define o cookie se ele estiver presente. O valor do parâmetro é ignorado e pode ser omitido.
google_ula Adiciona à lista de usuários. O valor está no formato userlistid[,timestamp]
  • userlistid: um ID da lista de usuário numérica.
  • timestamp: uma marca de data e hora opcional no formato POSIX, indica quando o usuário foi adicionado à lista de usuários.
Esse parâmetro de URL pode ser representado para adicionar o usuário a várias listas.

Todos os outros parâmetros que começam com o prefixo google_ são ignorados pelo Serviço de correspondência de cookie e não são passados para o URL de redirecionamento. Os parâmetros que não começam com o prefixo google_ são adicionados ao URL de redirecionamento junto com os parâmetros de resposta google_ (consulte a seção Formato do URL de redirecionamento existente abaixo).

A ordem dos parâmetros não é importante. Consulte a seção Exemplos para ilustrações de URLs válidos e inválidos.

Observação: o parâmetro google_hm está documentado na seção Tabelas de correspondências hospedadas.

Voltar ao início

URL de redirecionamento

Todos os parâmetros de URL que começam com o prefixo google_ são reservados para a expansão futura da API.

O URL de redirecionamento é formado por várias partes:

  • O protocolo, http ou https, conforme determinado pelo protocolo com o qual a Match Tag foi chamada.
  • O URL de redirecionamento base fornecido a você pelo Google (inclusive todos os parâmetros de URL codificados).
  • Parâmetros de resposta google_ (dependendo dos parâmetros de solicitação google_ fornecidos por você na Match Tag).
  • Os parâmetros de URL extras enviados na Match Tag que não começam pelo prefixo google_.

Definição dos parâmetros de resposta google_:

Parâmetro Descrição
google_error Erro de solicitação geral. Nenhuma operação foi realizada e nenhum parâmetro de resposta google_ será definido. Os códigos de erro são valores integrais. Os valores possíveis são:
  • 1 - O usuário tem um cookie do Google, mas desativou o acompanhamento usando esse cookie. Ele corresponde a E1 na Cookie Matching service v1 API.
  • 2 - Nenhuma operação válida especificada, por exemplo, uma solicitação sem operação foi recebida.
  • 3 - O usuário não tem um cookie do Google. O Google não será definido por meio do Serviço de correspondência de cookie. Isso corresponde a E0 na Cookie Matching service v1 API.
  • 4 - Conflito nas operações especificadas. Você não tem permissão para especificar os sinalizadores google_push e google_cm na mesma solicitação, pois eles têm finalidades conflitantes.
google_gid ID de usuário do Google. Definido caso google_cm seja especificado na solicitação e esta seja bem-sucedida.
google_cver Versão do cookie, definida caso google_cm seja especificado na solicitação e esta seja bem-sucedida. Isso corresponde a cver na Cookie Matching service V1 API.
google_ula

Status da operação de adição da lista de usuários, repetido caso vários google_ula tenham sido especificados na solicitação. O formato é:
<userlistid>,<status code>

Por exemplo: google_ula=1234567890,0

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

  • 0 - Sem 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 fornecida.
  • 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 fornecida está fechado.
  • 10 - Erro interno. O Serviço de correspondência de cookie encontrou um erro interno. Você pode realizar a correspondência com o usuário novamente.

Tabelas de correspondências hospedadas

Você pode escolher hospedar sua tabela de correspondências no Google. Isso pode melhorar os relatórios do tamanho da tabela e das taxas de correspondência e reduzir a quantidade de infraestrutura que precisa ser compatível.

Uma tabela de correspondências hospedada pelo Google oferece um mecanismo por meio do qual os dados que você passa para o Google para armazenamento são depois passados de volta em solicitações de lance. Normalmente, se você tiver colocado uma Match Tag para um usuário identificado com seu próprio ID de cookie interno, você inclui esse ID de cookie na solicitação de correspondência de cookie enviada para o Google. O Google hospeda os dados enviados e os inclui nas solicitações de lance subsequentes para impressões visualizadas pelo mesmo usuário. Assim, você pode:

  • Ignorar a etapa de armazenar o mapeamento entre o ID de usuário do Google e seu espaço de cookie
  • Optar por receber solicitações somente quando o usuário estiver incluído na tabela de correspondências

O parâmetro google_hm serve como um contêiner para os dados que você passa para o Google na solicitação de correspondência de cookie. Quando o Google responde com o redirecionamento 302, o parâmetro google_hm pode estar presente com um código de erro.

Quando o Google precisar passar os dados de volta para você, ele faz isso no campo hosted_match_data da solicitação de lance. Consulte o arquivo realtime-bidding-proto para uma descrição do campo hosted_match_data.

google_hm como um parâmetro da solicitação de correspondência de cookie

Parâmetro Descrição
google_hm Contém os dados que o comprador quer que o Google armazene na tabela de correspondências hospedada. O valor é uma string base64 segura para URL (preenchimento opcional).

google_hm com um parâmetro do redirecionamento

Parâmetro Descrição
google_hm Só aparece se a tentativa de gravar dados na tabela de correspondências hospedada falhar. Quando isso acontece, seu valor é um dos códigos de status a seguir:
  • 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 - Carga útil muito longa: o valor do parâmetro decodificado em mais de 24 bytes de dados.
  • 4 - Erro interno: houve um erro interno no armazenamento dos dados.
  • 5 - TReduzido: essa gravação não foi processada devido à redução.

Consulte os exemplos abaixo.

Voltar ao início

Como migrar da Cookie Matching Service v1 API

Importante: este documento descreve a versão mais recente da Cookie Matching Service API, a V2. Se você quiser migrar da v1 da API para a v2, siga as etapas na ordem exata descrita, terminando cada etapa antes de continuar para a próxima.

Etapa 1: como tratar os novos parâmetros de URL

Modifique seu servidor para aceitar os parâmetros de URl de redirecionamento do google_ da v2. O servidor deve tratar pelo menos:

  • google_error
  • google_gid
  • google_cver

Tratar esses parâmetros do URL de redirecionamento é importante para uma transição suave da v1 para a v2.

Se você quiser adicionar usuários a listas de usuários por meio da Match Tag, também é necessário modificar seu servidor para tratar o parâmetro do URL de redirecionamento google_ula.

Etapa 2: modificação da Match Tag

Assim que as alterações feitas no servidor forem implantadas, você poderá modificar a Match Tag para usar os novos parâmetros do URL de solicitação:

  • Modifique o parâmetro do URL de solicitação nid para google_nid.
  • Adicione o parâmetro do URL de solicitação google_cm para acionar a correspondência de cookie.
  • Defina o parâmetro do URL de solicitação google_no_sc se você não quiser que um cookie doubleclick seja criado, caso ele não exista. Se o cookie doubleclick não existir e você usar o parâmetro google_no_sc, nenhuma correspondência ocorrerá.
  • Defina o parâmetro do URL de solicitação google_ula se você quiser que a Match Tag adicione o usuário a uma lista de usuários.

Como exemplo, se você já tiver usado o URL a seguir como a origem da Match Tag como:

http://cm.g.doubleclick.net/pixel?nid=ad_network_xyz 

gora você usaria (como opção, adicionaria &google_sc):

http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm
Observação: o parâmetro do URL de solicitação google_nid aciona a v2 API. Você deve definir google_nid em vez de nid se, e somente se, tiver modificado seu servidor para tratar os novos URLs de redirecionamento e se também estiver adicionando google_cm aos parâmetros do URL de solicitação.

Etapa 3: (opcional) modifique seu URL de redirecionamento configurado

Suponhamos que seu URL de redirecionamento configurado fosse antes:

http://ad.network.com/pixel?id=

O parâmetro de URL id não é mais necessário (porque o cookie sempre será definido usando-se o parâmetro google_gid). Você pode modificar seu URL configurado para ser:

http://ad.network.com/pixel 

Seu servidor não recebe mais o parâmetro de URL id, que é desnecessário, e não recomendamos usá-lo mais.

Entre em contato com seu gerente da conta técnico caso você queira alterar o URL de redirecionamento configurado.

Voltar ao início

Macros de correspondência de cookie

Agora você pode configurar opcionalmente seus URLs com uma ou mais macros na forma de %%GOOGLE_GID%% ou %%GOOGLE_GID_PAIR%%. O %%GOOGLE_GID%% será substituído para o valor google_gid diretamente, enquanto o %%GOOGLE_GID_PAIR%% será substituído com um valor google_gid=.

As macros suportadas são:

Macro Se expande para
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>

Voltar ao início

Exemplos

Solicitação simples

A forma mais simples de uma solicitação de correspondência de cookie é aquela que não tem nenhum parâmetro adicional. O URL da Match Tag nesse caso seria:

  • Na v1: http://cm.g.doubleclick.net/pixel?nid=ad_network_xyz
  • Na v2: http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm

Pressupondo que seu URL de redirecionamento configurado seja:

  • http://ad.network.com/pixel?id=

Um exemplo de uma resposta bem-sucedida é:

  • Na v1: http://ad.network.com/pixel?id=dGhpcyBpcyBhbiBleGFtGxl&cver=1
  • Na v2: http://ad.network.com/pixel?id=&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1

Caso o usuário não tenha um cookie doubleclick.net, a resposta será:

  • Na v1: http://ad.network.com/pixel?id=E0
  • Na v2: http://ad.network.com/pixel?id=&google_error=3

No caso em que o usuário tivesse um cookie doubleclick.net, mas deixado a segmentação por comportamento, os códigos de erro seriam E1 e 1 nos exemplos acima.

Voltar ao início

Parâmetros extras na Match Tag

Se você usar parâmetros extras na Match Tag que não comecem com google_, eles serão passados para seu servidor. Por exemplo, vamos usar os dois parâmetros extras p1=v1 e p2=v2.

O URL da Match Tag nesse caso será:

  • Na v1: http://cm.g.doubleclick.net/pixel?nid=ad_network_xyz&p1=v1&p2=v2
  • Na v2: http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm&p1=v1&p2=v2

Um exemplo de uma resposta bem-sucedida é:

  • Na v1: http://ad.network.com/pixel?id=dGhpcyBpcyBhbiBleGFtGxl&cver=1&p1=v1&p2=v2
  • Na v2: http://ad.network.com/pixel?id=&p1=v1&p2=v2&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1
Observação: os parâmetros extras não têm garantia de serem exibidos ao final como na v2, e a ordem dos parâmetros não é garantida.

Uma resposta de erro adicionaria os parâmetros extras de maneira semelhante durante o relatório do erro no exemplo simples.

Voltar ao início

Parâmetros extras no URL de redirecionamento configurado

Suponha que seu URL configurado seja:

  • http://ad.network.com/pixel?id=&p1=v1&p2=v2

E você usa a versão simples do URL da Match Tag:

  • Na v1: http://cm.g.doubleclick.net/pixel?nid=ad_network_xyz
  • Na v2: http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm

Um exemplo de uma resposta bem-sucedida é:

  • Na v1: http://ad.network.com/pixel?id=dGhpcyBpcyBhbiBleGFtGxl&cver=1&p1=v1&p2=v2
  • Na v2: http://ad.network.com/pixel?id=&p1=v1&p2=v2&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1

Uma resposta de erro adicionaria os parâmetros extras de maneira semelhante durante o relatório do erro no exemplo simples.

Voltar ao início

Como usar parâmetros google_

Se você passar um parâmetro extra no URL da Match Tag ou no URL de redirecionamento configurado começando por google_, o parâmetro não será passado no redirecionamento para seu servidor na v2.

Por exemplo, se você usar estes dois URLs de Match Tag com o URL de redirecionamento configurado simples:

  • Na v1: http://cm.g.doubleclick.net/pixel?nid=ad_network_xyz&google_p1=v1&p2=v2
  • Na v2: http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_cm&google_p1=v1&p2=v2

Um exemplo de uma resposta bem-sucedida é:

  • Na v1: http://ad.network.com/pixel?id=dGhpcyBpcyBhbiBleGFtGxl&cver=1&google_p1=v1&p2=v2
  • Na v2: http://ad.network.com/pixel?id=&p2=v2&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1

A v1 API passa o parâmetro google_p1 e a v2 API não.

Uma resposta de erro adicionaria os parâmetros extras de maneira semelhante (ambos em v1, e apenas p2 em v2) durante o relatório do erro no exemplo simples.

Voltar ao início

Como usar o parâmetro google_ula

Pressupondo que seu URL de redirecionamento configurado seja:

  • http://ad.network.com/pixel?id=

E você usa o seguinte URL da Match Tag:

  • http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345

Diante do sucesso, o usuário é redirecionado para

  • http://ad.network.com/pixel?id=&google_ula=12345,0

Se houver um erro geral (por exemplo, um usuário não tem o cookie doubleclick.net), o URL de redirecionamento será:

  • http://ad.network.com/pixel?id=&google_error=3

Você também pode especificar uma marca de data e hora:

  • http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345,7654321

O URL de redirecionamento diante do êxito seria o mesmo.

O URL de redirecionamento em caso de erro é semelhante, mas o código de status seria diferente. Suponhamos que você não tenha permissão para adicionar usuários à lista de usuários 12345, o URL de redirecionamento seria:

  • http://ad.network.com/pixel?id=&google_ula=12345,2

Você também pode especificar várias listas usando vários parâmetros de solicitação google_ula. Você pode especificar uma marca de data e hora de maneira independente:

  • http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345,7654321&google_ula=45678

O status de cada operação é informado separadamente no URL de redirecionamento:

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

Aqui, o usuário foi adicionado à lista 45678, mas houve um erro de permissão para a lista 12345.

Você pode combinar os parâmetros de solicitação google_ula e google_cm para realizar a correspondência de cookie e adicionar o usuário a uma lista de usuários em uma única solicitação:

  • http://ad.network.com/pixel?id=&google_ula=12345&google_cm

O URL de redirecionamento será:

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

Voltar ao início

Como usar os parâmetros google_sc e google_no_sc

google_no_sc
O parâmetro de solicitação google_no_sc impede que o Serviço de correspondência de cookie defina o cookie doubleclick.net se o usuário não o tiver definido no momento. O comportamento padrão é definir o cookie.
google_sc

O parâmetro de solicitação google_sc faz com que o Serviço de correspondência de cookie defina o cookie doubleclick.net se o usuário não o tiver definido no momento.

Esses parâmetros não modificam o resultado da solicitação de outra forma. O Serviço de correspondência de cookie nem sempre define o cookie com sucesso se, por exemplo, o usuário tiver proibido cookies em geral ou o cookie doubleclick.net em particular.

Se o Serviço de correspondência de cookie precisar definir um cookie, ele verifica se o navegador do usuário aceitou o cookie emitindo um redirecionamento automático com o cabeçalho Set-Cookie. Se o navegador do usuário não enviar o cookie no redirecionamento automático, considera-se que ele não aceita o cookie doubleclick.net e o redirecionamento para você conterá google_error=3.

Pressupondo que seu URL de redirecionamento configurado seja:

  • http://ad.network.com/pixel?id=

E você usa o seguinte URL da Match Tag:

  • http://cm.g.doubleclick.net/pixel?google_nid=ad_network_xyz&google_ula=12345

Se o usuário não tiver o cookie doubleclick.net e você usar google_no_sc, o URL de redirecionamento será:

  • http://ad.network.com/pixel?id=&google_error=3

Se, em vez disso, você especificar o parâmetro de solicitação google_cm e o cookie for definido com sucesso, o URL de redirecionamento será:

  • http://ad.network.com/pixel?id=&google_gid=dGhpcyBpcyBhbiBleGFtGxl&google_cver=1
Observação: não há como saber se o cookie doubleclick.net acabou de ser definido ou se o usuário já tinha um antes.

Se o cookie não puder ser definido, o URL de redirecionamento será idêntico ao URL de redirecionamento de erro regular:

  • http://ad.network.com/pixel?id=&google_error=3

Voltar ao início

Tabelas de correspondências hospedadas: gravação bem-sucedida

Valores a serem usados no exemplo:

  • para o parâmetro google_hm, "Cookie number 1!" codificado em base64 segura para URL como Q29va2llIG51bWJlciAxIQ==
  • para o URL de redirecionamento configurado, http://cookie-monster.com/pixel?id=

A Solicitação de correspondência de cookie será:

http://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=Q29va2llIG51bWJlciAxIQ%3D%3D

O redirecionamento 302 será:

  • http://cookie-monster.com/pixel?id=

Como o parâmetro google_hm foi definido com o valor codificado "Cookie number 1!", as solicitações de lance subsequentes para impressões visualizadas pelo mesmo usuário contêm esse calor no campo hosted_match_data:

BidRequest <
  ...
  hosted_match_data: "Cookie number 1!"

>

Veja o que acontece:

  • Como google_cm não foi definido na solicitação, google_gid não está na resposta.
  • Como a gravação hospedada foi bem-sucedida, google_hm não está na resposta.
  • Como a gravação foi bem-sucedida, os dados hospedados se tornam disponíveis nas solicitações de lance subsequentes.

Voltar ao início

Tabelas de correspondências hospedadas: decodificar erro

Para este exemplo, suponha que o URL de redirecionamento configurado seja:

  • http://cookie-monster.com/pixel?id=

A Solicitação de correspondência de cookie será:

http://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=chocolate_chunk!

O comprador adicionou o parâmetro google_hm, mas não codificou seu valor. Em vez disso, ele tentou definir o parâmetro com o valor não codificado chocolate_chunk!.

O redirecionamento 302 será:

  • http://cookie-monster.com/pixel?id=&google_hm=2

Veja o que acontece:

  • Como google_cm não foi definido na solicitação, google_gid não está na resposta.
  • O Serviço de correspondência de cookie tenta decodificar o valor do parâmetro google_hm como base64 segura para URL, mas o chocolate_chunk! não pode ser decodificado com sucesso como base64, e isso provoca uma falha na gravação hospedada.
  • Como ocorre falha na gravação hospedada, o google_hm aparece na resposta com o código de erro 2—um erro de decodificação.
  • Como a gravação não foi bem-sucedida, nenhum dado de correspondência hospedada fica disponível nas solicitações de lance (embora dados antigos ainda sejam enviados).

Voltar ao início

Tabelas de correspondências hospedadas: erro sem cookie

Por diversos motivos, nem todo usuário possui um cookie doubleclick.net a todo momento.

Para este exemplo, suponha que não há cookie doubleclick.net no navegador do usuário. Também suponha que o URL de redirecionamento configurado seja:

  • http://cookie-monster.com/pixel?id=

A Solicitação de correspondência de cookie será:

http://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_hm=chocolate_chunk!

O comprador adicionou o parâmetro google_hm, mas não codificou seu valor. Em vez disso, ele tentou definir o parâmetro com o valor não codificado chocolate_chunk!.

O redirecionamento 302 será:

  • http://cookie-monster.com/pixel?id=&google_error=3

Veja o que acontece:

  • A ausência de um cookie provoca falha na solicitação geral. Assim, google_error é definido na resposta.
  • Embora o comprador tenha definido o google_hm com um valor não codificado, que falharia quando o Serviço de correspondência de cookie tentasse decodificá-lo, não há tentativa de decodificar google_hm, pois a falha da solicitação geral é um erro de nível maior que tem precedência. Portanto, google_hm não é definido com um erro de decodificação na resposta.
  • Como a gravação não foi bem-sucedida, nenhum dado de correspondência hospedada fica disponível nas solicitações de lance (embora dados antigos ainda sejam enviados).

Voltar ao início

Tabelas de correspondências hospedadas: combinação das ferramentas

Valores a serem usados no exemplo:

  • para o parâmetro google_hm, "Cookie number 1!" codificado em base64 como Q29va2llIG51bWJlciAxIQ==
  • para o parâmetro google_ula, o valor 12345
  • para o URL de redirecionamento configurado, http://cookie-monster.com/pixel?id=
  • para o parâmetro extra my_extra_param, nenhum valor
  • para o parâmetro extra my_other_extra_param, o valor 7

A Solicitação de correspondência de cookie será:

http://cm.g.doubleclick.net/pixel?google_nid=cookie-monster&google_cm&google_hm=Q29va2llIG51bWJlciAxIQ%3D%3D&google_ula=12345&my_extra_param=&my_other_extra_param=7

O redirecionamento 302 será:

  • http://cookie-monster.com/pixel?id=&my_extra_parameter=&my_other_extra_param=7&google_gid=ABCDETC&google_cver=1&google_ula=12345,0

Veja o que acontece:

  • Os parâmetros extras são passados intactos antes.
  • O parâmetro google_ula contém o status da tentativa de adicionar à lista de usuários (0: OK).
  • Como a gravação na tabela de correspondências hospedadas foi bem-sucedida, os dados de correspondência hospedada se tornam disponíveis nas solicitações de lance subsequentes.
  • Como o parâmetro google_hm foi definido com o valor codificado "Cookie number 1!", as solicitações de lance subsequentes para impressões visualizadas pelo mesmo usuário contêm esse calor no campo hosted_match_data:
BidRequest <
  ...
  hosted_match_data: "Cookie number 1!"

>

Voltar ao início

Como usar macros de correspondência de cookie

Sem macros

Normalmente, o usuário nos fornece um URL de correspondência de cookie base ao qual anexamos os parâmetros de correspondência de cookie.

Ele nos fornece o URL a seguir para armazenar as chaves de RTB (lance em tempo real):

http://user.buyer.com/cookies?x=0&y=1

Anexamos alguns parâmetros ao chamá-lo:

http://user.buyer/cookies?x=0&y=1&google_push=456&google_gid=1&google_cver=1

Com macros

Se o comprador precisar dos parâmetros em uma ordem específica, ele pode fornecer o URL a seguir para chaves de RTB:

http://user.buyer.com/cookies?w=0%%GOOGLE_PUSH_PAIR%%&x=1%%GOOGLE_GID_PAIR&y=2%%GOOGLE_CVER_PAIR%%&z=3%%GOOGLE_ERROR_PAIR%%

Expandimos a macro e anexamos o restante dos parâmetros:

http://user.buyer.com/cookies?w=0&google_push=456&x=1&google_gid=1&y=2&google_cver=1&z=3

Como a macro de estilo '_PAIR' foi usada, a expansão da macro também incluiu o nome do parâmetro. O URL a seguir produziria o mesmo resultado:

http://user.buyer.com/cookies?w=0&google_push=%%GOOGLE_PUSH%%&x=1&google_gid=%%GOOGLE_GID%%&y=2&google_cver=%%GOOGLE_CVER%%&z=3%%GOOGLE_ERROR_PAIR%%

Voltar ao início

Enviar comentários sobre…

DoubleClick Ad Exchange Real-Time Bidding Protocol