Segmentação por user agent

O cabeçalho User-Agent sempre foi incluído nas solicitações de lance para fornecer dados de segmentação úteis, como o navegador e a plataforma do dispositivo inicial. No entanto, os navegadores geralmente ocultam o User-Agent devido à dificuldade de uso e para proteger melhor a privacidade do usuário. Em resposta a isso, o Google oferece suporte a dicas de cliente do user-agent, que são incluídas em solicitações de lance quando disponíveis para complementar o cabeçalho User-Agent. Essas dicas de cliente (abreviação de "hints") podem ser originadas de cabeçalhos Sec-Ch-UA* ou da API Javascript Client Hints.

O cabeçalho User-Agent é exposto como uma string no campo BidRequest.device.ua.

Uma mensagem UserAgent será preenchida com as dicas de cliente quando elas estiverem disponíveis, mas será preenchida com base nos valores analisados do cabeçalho User-Agent. Isso é exposto no campo BidRequest.device.sua.

Recomendamos que os bidders usem a mensagem UserAgent em vez da string User-Agent.

Como o UserAgent é preenchido

Ao contrário do cabeçalho User-Agent, a mensagem UserAgent representa as informações do user agent divididas em vários campos para informações específicas.

Dependendo se as dicas de cliente estão disponíveis na solicitação de anúncio, a mensagem UserAgent pode ser preenchida das seguintes maneiras:

  • Se a solicitação contiver pelo menos dicas de cliente de baixa entropia (link em inglês), o UserAgent será preenchido com base no conteúdo delas.
  • Se a solicitação tiver apenas o cabeçalho User-Agent, o UserAgent será preenchido com base no que pode ser analisado no cabeçalho.

Exemplo: como preencher UserAgent com base no cabeçalho User-Agent

Suponha que haja uma solicitação de anúncio em que o navegador envia os seguintes cabeçalhos:

User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)
            AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36

Um UserAgent preenchido apenas com base no cabeçalho User-Agent pode ser parecido com este:

browsers: [{ brand: "Mozilla", version: ["5", "0"] },
           { brand: "AppleWebKit", version: ["537", "36"] },
           { brand: "Chrome", version: ["103", "0", "0", "0"] },
           { brand: "Safari", version: ["537", "36"] }],
platform: { brand: "Windows NT", version: ["10", "0"] },
mobile: false,
architecture: "x86",
bitness: "64",
model: "x64",
source: USER_AGENT_STRING

Exemplo: como preencher UserAgent com base nas dicas de cliente

Suponha que haja uma solicitação de anúncio em que o navegador envie os seguintes cabeçalhos:

User-Agent:                 Mozilla/5.0 (Windows NT 10.0; Win64; x64)
                            AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36
Sec-Ch-Ua:                  ".Not/A)Brand";v="99", "Google Chrome";v="103", "Chromium";v="103"
Sec-Ch-Ua-Arch:             x86
Sec-Ch-Ua-Full-Version:     103.0.5060.134
Sec-Ch-Ua-Mobile:           ?0
Sec-Ch-Ua-Platform:         Windows
Sec-Ch-Ua-Platform-Version: 15.0.0

Nos casos em que pelo menos dicas de cliente de baixa entropia são incluídas, o UserAgent será preenchido com base no conteúdo desses cabeçalhos, mesmo que cabeçalhos User-Agent esteja presente. Ele vai ficar assim:

browsers: [{ brand: ".Not/A)Brand", version: ["99", "0", "0", "0"] },
           { brand: "Google Chrome", version: ["103", "0", "5060", "134"] },
           { brand: "Chromium", version: ["103", "0", "5060", "134"] }],
platform: { brand: "Windows", version: ["15", "0", "0"] },
mobile: false,
architecture: "x86",
bitness: "64",
source: CLIENT_HINTS_HIGH_ENTROPY

População com base no cabeçalho User-Agent em vez de dicas de cliente

Alguns campos são preenchidos de maneira diferente, dependendo se eles são baseados no cabeçalho User-Agent ou nas dicas do cliente. Confira a seguir um resumo dessas diferenças:

  • Para navegadores e plataformas idênticos, UserAgent.browsers.brand e UserAgent.platform.brand geralmente diferem entre um UserAgent com base no cabeçalho User-Agent ou nas dicas do cliente. Por exemplo, UserAgent.platform.brand pode aparecer como "Windows NT" se for baseado no cabeçalho User-Agent ou "Windows" se for baseado em dicas de cliente.
  • Algumas entradas UserAgent.browsers são exclusivas do cabeçalho User-Agent ou das dicas de cliente. Por exemplo, "AppleWebKit" apareceria se UserAgent fosse baseado no cabeçalho User-Agent, enquanto "Chromium" só apareceria se fosse baseado em dicas do cliente.
  • Somente um UserAgent com base no cabeçalho User-Agent pode conter valores congelados. Por exemplo, se a plataforma fosse o Windows 11 22H2, UserAgent.platform.brand seria definido como "Windows NT" e UserAgent.platform.version seria definido como [“10”, “0”], porque esse é o valor congelado para qualquer versão do Windows a partir da 10.

Os dados em UserAgent que são baseados em dicas do cliente normalmente não são uma substituição imprecisa para informações congeladas ou excluídas. Se houver alguma inconsistência entre o cabeçalho User-Agent e um UserAgent baseado em dicas de cliente, as informações do UserAgent serão preferidas.

Campos do objeto UserAgent

Esta seção resume cada campo, com foco no comportamento específico do Google RTB e nas práticas recomendadas para uso.

Navegadores

Contém uma lista de entradas de BrandVersion que geralmente são ordenadas por especificidade. Por exemplo, se você listar o conteúdo de browsers, o brand de cada entrada pode aparecer na seguinte ordem:

Brand Significado
Mozilla Compatível com Mozilla
AppleWebKit Baseado no AppleWebKit, um subconjunto do Mozilla.
Chrome Navegador Chrome, um subconjunto de navegadores compatíveis com o AppleWebKit
Safari Variante para computador, em vez de dispositivo móvel.

O UserAgent nem sempre lista os navegadores em uma ordem específica, principalmente se for baseado em dicas do cliente. Confira a seguir outras diferenças que você pode encontrar com base no valor de source:

  • USER_AGENT: o campo version pode ser reduzido a uma versão principal ou congelado (depende da política específica do agente). Não haverá indicação de que o valor está congelado.
  • CLIENT_HINTS_LOW_ENTROPY e CLIENT_HINTS_HIGH_ENTROPY: as entradas não são ordenadas por nenhum critério. Por exemplo, o mesmo navegador pode enviar essas entradas em ordens diferentes em cada solicitação. Eles também podem conter uma entrada GREASE, que precisa ser ignorada.
  • CLIENT_HINTS_HIGH_ENTROPY: todos os campos version encontrados nos navegadores podem ser configurados para versões completas.

Plataforma

Uma entrada BrandVersion que descreve a plataforma. Isso pode não ser compatível com o cabeçalho User-Agent e as dicas do cliente. Portanto, a segmentação de algumas plataformas pode exigir o teste de dois nomes. Por exemplo, o sistema operacional Macintosh da Apple é marcado como "Macintosh" no cabeçalho User-Agent, mas como "macOS" nas dicas do cliente. Confira a seguir outras diferenças que podem aparecer com base no valor de source:

  • USER_AGENT: o campo version pode ser reduzido a uma versão principal ou congelado. Não haverá indicação de que o valor está congelado.
  • CLIENT_HINTS_LOW_ENTROPY: o campo version não será preenchido.
  • CLIENT_HINTS_HIGH_ENTROPY: o campo version pode ser definido como a versão completa.

Dispositivo móvel

Indica se o conteúdo, como anúncios, precisa ser otimizado para telas pequenas e/ou entrada por toque. Isso não é necessariamente um indicador do tipo de dispositivo, já que os navegadores para dispositivos móveis podem ser configurados para solicitar um "site para computador".

Arquitetura

Identifica a arquitetura da plataforma, como "x86" ou "arm".

Para um UserAgent baseado em dicas do cliente, ele só será preenchido quando source estiver definido como CLIENT_HINTS_HIGH_ENTROPY.

Bitness

Identifica o bitness da plataforma, como se ela tem uma CPU de 32 bits ou de 64 bits. O campo é uma string de número inteiro que fornece informações adicionais sobre a arquitetura. Por exemplo, uma arquitetura "x86" pode ter um bitness definido como "32" ou "64".

Para um UserAgent baseado em dicas do cliente, ele só será preenchido quando source estiver definido como CLIENT_HINTS_HIGH_ENTROPY.

Modelo

Identifica o modelo do dispositivo. Para dispositivos móveis, ou seja, não laptops ou computadores, esse campo será preenchido com um nome de modelo, como "Pixel 6 Pro".

Confira a seguir as diferenças que você pode notar com base no valor de source:

  • USER_AGENT
    • Dispositivos não móveis: o campo model geralmente contém um valor combinado de arquitetura e bitness, como "x64" para Windows. Esse valor não é compatível com várias plataformas. Por exemplo, o Linux pode usar "x86_64" para o mesmo hardware.
    • Dispositivos móveis: esse campo não inclui arquitetura e bitness. Se você tiver interesse nesses valores, consulte UserAgent.architecture e UserAgent.bitness.
  • CLIENT_HINTS_LOW_ENTROPY: o campo model não será preenchido.
  • CLIENT_HINTS_HIGH_ENTROPY: o campo model só será preenchido para o modelo de dispositivo de dispositivos móveis. Nenhum valor é definido para plataformas de computador.

Origem

Identifica quais cabeçalhos foram usados para criar o UserAgent. Para as dicas do cliente, isso também distingue os dois casos a seguir:

  • CLIENT_HINTS_LOW_ENTROPY: apenas as dicas de cliente básicas estão disponíveis.
  • CLIENT_HINTS_HIGH_ENTROPY: as dicas de cliente estão disponíveis, incluindo pelo menos um campo classificado como alta entropia.