Estratégias para migrar seu site da dependência da string do user agent para as novas dicas de cliente HTTP do user agent.
Publicado em: 19 de maio de 2021
A string do user agent é uma superfície de impressão digital passiva significativa em navegadores, além de ser difícil de processar. No entanto, há todos os tipos de motivos válidos para coletar e processar dados de user agent. Portanto, o que é necessário é um caminho para uma solução melhor. As dicas de cliente HTTP do user agent oferecem uma maneira explícita de declarar sua necessidade de dados do user agent e métodos para retornar os dados em um formato fácil de usar.
Neste artigo, vamos mostrar como auditar seu acesso aos dados do user agent e migrar o uso da string do user agent para as dicas de cliente HTTP do user agent.
Auditar a coleta e o uso de dados do user agent
Como em qualquer forma de coleta de dados, você precisa entender por que está coletando esses dados. A primeira etapa, independentemente de você realizar ou não alguma ação, é entender onde e por que você está usando dados de user agent.
Se você não sabe se ou onde os dados do user agent estão sendo usados, pesquise
no código de front-end o uso de navigator.userAgent e no código de back-end o
uso do cabeçalho HTTP User-Agent. Verifique também se o código de front-end
usa recursos já descontinuados, como navigator.platform e
navigator.appVersion.
Do ponto de vista funcional, pense em qualquer lugar do código em que você esteja gravando ou processando:
- Nome ou versão do navegador
- Nome ou versão do sistema operacional
- Marca ou modelo do dispositivo
- Tipo de CPU, arquitetura ou número de bits (por exemplo, 64 bits)
Também é provável que você esteja usando uma biblioteca ou um serviço de terceiros para processar o user agent. Nesse caso, verifique se eles estão sendo atualizados para oferecer suporte às dicas de cliente HTTP do user agent.
Você está usando apenas dados básicos do user agent?
O conjunto padrão de dicas de cliente HTTP do user agent inclui:
Sec-CH-UA: nome do navegador e versão principal / significativaSec-CH-UA-Mobile: valor booleano que indica um dispositivo móvel.Sec-CH-UA-Platform: nome do sistema operacional
A versão reduzida da string de user agent proposta também vai manter
essas informações básicas de maneira compatível com versões anteriores. Por exemplo, em vez de
Chrome/90.0.4430.85, a string incluiria Chrome/90.0.0.0.
Se você estiver verificando apenas o nome do navegador, a versão principal ou o sistema operacional na string do user agent, seu código vai continuar funcionando, mas é provável que você veja avisos de descontinuação.
Embora seja possível e recomendável migrar para as dicas de cliente HTTP do user agent, talvez você tenha código legado ou restrições de recursos que impeçam isso. A redução de informações na string do user agent de forma compatível com versões anteriores tem como objetivo garantir que, embora o código atual receba informações menos detalhadas, ele ainda mantenha a funcionalidade básica.
Estratégias
Há várias estratégias que você pode adotar para migrar o uso da string do user agent para as dicas de cliente HTTP do user agent.
API JavaScript do lado do cliente on demand
Se você estiver usando navigator.userAgent, mude para
navigator.userAgentData antes de voltar a analisar a
string do user agent.
if (navigator.userAgentData) {
// use new hints
} else {
// fall back to user-agent string parsing
}
Se você estiver verificando se o dispositivo é um smartphone ou computador, use o valor booleano mobile:
const isMobile = navigator.userAgentData.mobile;
userAgentData.brands é uma matriz de objetos com as propriedades brand e version, em que o navegador pode listar a compatibilidade com essas marcas. É possível acessá-lo diretamente como uma matriz ou usar uma chamada
some() para verificar se uma entrada específica está presente:
function isCompatible(item) {
// In real life you most likely have more complex rules here
return ['Chromium', 'Google Chrome', 'NewBrowser'].includes(item.brand);
}
if (navigator.userAgentData.brands.some(isCompatible)) {
// browser reports as compatible
}
Se você precisar de um dos valores de user agent de alta entropia mais detalhados,
especifique-o e verifique o resultado no Promise retornado:
navigator.userAgentData.getHighEntropyValues(['model'])
.then(ua => {
// requested hints available as attributes
const model = ua.model
});
Também é possível usar essa estratégia se você quiser migrar do processamento do lado do servidor para o processamento do lado do cliente. A API JavaScript não requer acesso aos cabeçalhos da solicitação HTTP, então os valores de user agent podem ser solicitados a qualquer momento.
Cabeçalho estático do lado do servidor
Se você estiver usando o cabeçalho da solicitação User-Agent no servidor e suas necessidades
para esses dados forem relativamente consistentes em todo o site, será possível
especificar as dicas de cliente HTTP como um conjunto estático nas respostas. Essa é uma
abordagem relativamente simples, já que geralmente só é preciso configurá-la em um
local. Por exemplo, ele pode estar na configuração do servidor da Web, se você já
adiciona cabeçalhos lá, na configuração de hospedagem ou na configuração de nível superior do
framework ou da plataforma que você usa para seu site.
Considere essa estratégia se você estiver transformando ou personalizando as respostas com base nos dados do user agent.
Os navegadores ou outros clientes podem fornecer dicas padrão diferentes. Por isso, é recomendável especificar tudo o que você precisa, mesmo que geralmente seja fornecido por padrão.
Por exemplo, os padrões atuais do Chrome seriam representados como:
⬇️ Cabeçalhos de resposta
Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA
Se você também quiser receber o modelo do dispositivo nas respostas, envie:
⬇️ Cabeçalhos de resposta
Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Model, Sec-CH-UA-Platform, Sec-CH-UA
Ao processar isso do lado do servidor, primeiro verifique se o cabeçalho Sec-CH-UA desejado foi enviado e, em seguida, use a análise do cabeçalho User-Agent como substituto se ele não estiver disponível.
Delegar dicas para solicitações entre origens
Se você estiver solicitando sub-recursos entre origens ou entre sites que exigem o envio de dicas de cliente HTTP do user agent nas solicitações, será necessário especificar explicitamente as dicas desejadas usando uma política de permissões.
Por exemplo, digamos que https://blog.site hospede recursos em
https://cdn.site, que pode retornar recursos otimizados para um dispositivo específico.
https://blog.site pode solicitar a dica Sec-CH-UA-Model, mas precisa
delegá-la explicitamente a https://cdn.site usando o cabeçalho
Permissions-Policy. A lista de dicas controladas por política está disponível no rascunho da infraestrutura de dicas de cliente HTTP (link em inglês).
⬇️ Resposta de blog.site delegando a dica
Accept-CH: Sec-CH-UA-Model
Permissions-Policy: ch-ua-model=(self "https://cdn.site")
⬆️ As solicitações para sub-recursos em cdn.site incluem a dica delegada
Sec-CH-UA-Model: "Pixel 5"
É possível especificar várias dicas para várias origens, não apenas do intervalo ch-ua:
⬇️ Resposta de blog.site delegando várias dicas para várias origens
Accept-CH: Sec-CH-UA-Model, DPR
Permissions-Policy: ch-ua-model=(self "https://cdn.site"),
ch-dpr=(self "https://cdn.site" "https://img.site")
Delegar dicas para iframes
Os iframes entre origens funcionam de maneira semelhante aos recursos entre origens, mas você especifica as dicas que quer delegar no atributo allow.
⬇️ Resposta de blog.site
Accept-CH: Sec-CH-UA-Model
↪️ HTML para blog.site
<iframe src="https://widget.site" allow="ch-ua-model"></iframe>
⬆️ Solicitação para widget.site
Sec-CH-UA-Model: "Pixel 5"
O atributo allow no iframe vai substituir qualquer cabeçalho Accept-CH que o widget.site possa enviar. Portanto, especifique tudo o que o site do iframe vai precisar.
Dicas dinâmicas do lado do servidor
Se você tiver partes específicas da jornada do usuário em que precisa de uma seleção maior de dicas do que no restante do site, solicite essas dicas sob demanda, em vez de estaticamente em todo o site. Isso é mais complexo de gerenciar, mas, se você já definir cabeçalhos diferentes por rota, talvez seja viável.
O importante é lembrar que cada instância do cabeçalho Accept-CH
vai substituir o conjunto atual. Portanto, se você estiver definindo o cabeçalho de forma dinâmica, cada página precisará solicitar o conjunto completo de dicas necessárias.
Por exemplo, talvez você queira fornecer ícones e controles que correspondam ao sistema operacional do usuário em uma seção do seu site. Para isso, talvez seja necessário
extrair também Sec-CH-UA-Platform-Version para exibir os sub-recursos
adequados.
⬇️ Cabeçalhos de resposta para /blog
Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA
⬇️ Cabeçalhos de resposta para /app
Accept-CH: Sec-CH-UA-Mobile, Sec-CH-UA-Platform, Sec-CH-UA-Platform-Version, Sec-CH-UA
Abordar as dicas do lado do servidor necessárias na primeira solicitação
Pode haver casos em que você precise de mais do que o conjunto padrão de dicas na primeira solicitação. No entanto, isso é raro, então verifique se você revisou o raciocínio.
A primeira solicitação realmente significa a primeira solicitação de nível superior para essa origem enviada nessa sessão de navegação. O conjunto padrão de dicas inclui o nome do navegador com a versão principal, a plataforma e o indicador de dispositivo móvel. A pergunta a ser feita aqui é: você precisa de dados estendidos no carregamento inicial da página?
Para mais dicas sobre a primeira solicitação, há duas opções. Primeiro, use o cabeçalho Critical-CH. Ele tem o mesmo formato de Accept-CH,
mas informa ao navegador que ele precisa repetir imediatamente a solicitação se a primeira
tiver sido enviada sem a dica crítica.
⬆️ Solicitação inicial
[With default headers]
⬇️ Cabeçalhos de resposta
Accept-CH: Sec-CH-UA-Model
Critical-CH: Sec-CH-UA-Model
🔃 O navegador tenta novamente a solicitação inicial com o cabeçalho extra
[With default headers + …]
Sec-CH-UA-Model: Pixel 5
Isso gera a sobrecarga da nova tentativa na primeira solicitação, mas o custo de implementação é relativamente baixo. Envie o cabeçalho extra, e o navegador vai fazer o resto.
Para situações em que você realmente precisa de mais dicas no primeiro carregamento de página, a proposta de confiabilidade das dicas de cliente HTTP (link em inglês) está definindo um caminho para especificar dicas nas configurações de conexão. Isso usa a extensão Configurações de protocolo da camada de aplicativo (ALPS, na sigla em inglês) para TLS 1.3 para permitir essa transmissão antecipada de dicas em conexões HTTP/2 e HTTP/3. Isso ainda está em um estágio inicial, mas se você gerencia ativamente suas próprias configurações de TLS e conexão, este é o momento ideal para contribuir.
Suporte do Stackdriver legado
Talvez você tenha um código legado ou de terceiros no seu site que dependa de
navigator.userAgent, incluindo partes da string do user agent que serão
reduzidas. Planeje a migração para as chamadas
navigator.userAgentData equivalentes, mas há uma solução temporária.
O retrofill de UA-CH é uma pequena
biblioteca que permite substituir navigator.userAgent por uma nova string
criada com base nos valores de navigator.userAgentData solicitados.
Por exemplo, este código gera uma string de user agent que também inclui a dica "model":
import { overrideUserAgentUsingClientHints } from './uach-retrofill.js';
overrideUserAgentUsingClientHints(['model'])
.then(() => { console.log(navigator.userAgent); });
A string resultante mostraria o modelo Pixel 5, mas ainda mostra o 92.0.0.0 reduzido, já que a dica uaFullVersion não foi solicitada:
Mozilla/5.0 (Linux; Android 10.0; Pixel 5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/92.0.0.0 Mobile Safari/537.36
Mais suporte
Se essas estratégias não resolverem seu caso de uso, inicie uma discussão no repositório privacy-sandbox-dev-support para que possamos analisar o problema juntos.