Segmentação por user agent

O cabeçalho User-Agent sempre foi incluído em solicitações de lances para fornecer dados de segmentação úteis, como o navegador e a plataforma do dispositivo iniciador. No entanto, os navegadores geralmente ocultam muito 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 HTTP do user agent, que são incluídas em solicitações de lances quando disponíveis para complementar o cabeçalho do user agent. Essas dicas de cliente (para abreviar) podem ser originadas dos 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 dicas de cliente quando estiverem disponíveis, mas será preenchida com base nos valores analisados do cabeçalho User-Agent. Isso é exposto no campo BidRequest.device.sua.

É altamente recomendável 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 da disponibilidade das dicas de cliente 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, o UserAgent será preenchido com base no conteúdo delas.
  • Se a solicitação contiver apenas o cabeçalho User-Agent, o UserAgent será preenchido com base no que pode ser analisado do cabeçalho.

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

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

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

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: preencher UserAgent com base em dicas de cliente HTTP

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 os cabeçalhos do user agent estejam presentes. Ele vai aparecer 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

Preenchimento com base no cabeçalho do user agent x dicas de cliente HTTP

Alguns campos são preenchidos de maneira diferente dependendo se são baseados no cabeçalho User-Agent ou em dicas de cliente. Confira 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 de 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 de 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 de cliente.
  • Somente um UserAgent baseado no cabeçalho User-Agent pode conter valores congelados. Por exemplo, se a plataforma fosse Windows 11 22H2, UserAgent.platform.brand seria definido como "Windows NT" e UserAgent.platform.version seria definido como [“10”, “0”] porque esse é o valor fixo para qualquer versão do Windows 10 ou superior.

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

Campos do objeto UserAgent

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

Navegadores

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

Marca 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 de cliente. Confira abaixo 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 há 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 deve ser ignorada.
  • CLIENT_HINTS_HIGH_ENTROPY: todos os campos version encontrados em navegadores podem ser definidos como 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. Por isso, 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 de 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. Não há 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, deve ser otimizado para telas pequenas e/ou entrada por toque. Isso não é necessariamente um indicador do tipo de dispositivo, já que navegadores 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 de cliente, observe que ele só será preenchido quando source for definido como CLIENT_HINTS_HIGH_ENTROPY.

Bitness

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

Para um UserAgent baseado em dicas de cliente, observe que ele só será preenchido quando source for definido como CLIENT_HINTS_HIGH_ENTROPY.

Modelo

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

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

  • USER_AGENT
    • Dispositivos não móveis: o campo model geralmente contém uma arquitetura combinada e um valor de bitness, como "x64" para Windows. Esse valor não é multiplataforma. Por exemplo, o Linux pode usar "x86_64" para o mesmo hardware.
    • Dispositivos móveis: esse campo não inclui arquitetura e bits. 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 móvel. Nenhum valor é definido para plataformas de computador.

Origem

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

  • CLIENT_HINTS_LOW_ENTROPY: apenas 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 de alta entropia.