O UA Pro permite definir o User-Agent (UA) para todos os sites, domínios específicos ou uma única aba. Primeiro escolha quais páginas a regra afeta e depois como o UA é gerado. Quando há várias regras, a extensão seleciona uma regra para a página principal conforme a prioridade; os recursos comuns da página herdam primeiro o UA da página principal.
01Entendendo o UA e os recursos da página
O UA descreve a identidade enviada pelo navegador aos sites e geralmente informa navegador, sistema operacional e dispositivo. O UA Pro pode modificar o User-Agent das solicitações web comuns e fornecer o valor correspondente para navigator.userAgent nas páginas comuns.
Escolher um UA móvel permite observar o que um site retorna para UAs móveis, mas não transforma um computador em celular e não altera automaticamente o tamanho da tela, o mecanismo do navegador, o IP ou a impressão digital completa do navegador.
Suponha que a barra de endereços mostre https://shop.example.com/product:
| Termo | Significado neste exemplo |
|---|---|
| Página principal | A página do produto aberta na barra de endereços |
| Domínio da página principal | shop.example.com, sem protocolo ou caminho |
| Domínio pai | Em relação a shop.example.com, example.com é um domínio pai |
| Subdomínio | img.shop.example.com é um subdomínio de shop.example.com |
| Recursos da página | Imagens, scripts, estilos, solicitações de API, iframes de rede comuns e outros itens carregados pela página |
| Domínio do recurso | O domínio de destino de uma solicitação de recurso, como cdn.example.net |
Neste guia, «domínio da página principal» significa o nome de host da página na barra de endereços. Não é um domínio de primeiro nível como .com nem necessariamente um domínio registrado como example.com.
02Três conceitos de configuração independentes
| Configuração | Pergunta que responde | Exemplos |
|---|---|---|
| Escopo | Quais páginas usam esta regra? | Global, domínio example.com, aba atual |
| Modo de UA | De onde vem o conteúdo do UA? | UA integrado, personalizado, adicionar texto, UA aleatório |
| Modo aleatório | Quando o modo aleatório é selecionado, quando um novo valor é sorteado? | Em cada carregamento de página, por aba |
Por exemplo, «escopo de domínio + UA aleatório + por aba» significa que cada aba que visita páginas desse escopo armazena seu próprio resultado aleatório para a regra. Isso não significa que todas as abas que visitam o domínio compartilhem um UA permanente.
2.1 Escopo
| Escopo | O que afeta | Duração e relação de substituição |
|---|---|---|
| Global | Páginas comuns de sites sem regra de prioridade maior | A configuração é mantida; regras de domínio ou aba podem prevalecer |
| Domínio | Páginas cujo domínio principal corresponde ao domínio especificado ou a um de seus subdomínios | A configuração é mantida; regras de domínio mais específicas ou de aba podem prevalecer |
| Aba | A aba na qual a regra foi criada | Maior prioridade; continua valendo quando a aba navega para outros sites e termina quando ela é fechada |
«Escopo global + aleatório por aba» continua sendo uma regra global; armazenar resultados aleatórios separadamente não a transforma em uma regra de aba de prioridade máxima.
2.2 Modo de UA
| Modo | Como o UA é gerado | Indicado para |
|---|---|---|
| UA integrado | Escolhe um UA entre navegadores ou dispositivos predefinidos | Usar rapidamente uma identidade predefinida |
| Personalizado | Usa a string completa de UA informada | Usar um UA específico ou salvar sua própria lista de UAs |
| Adicionar texto | Adiciona um espaço e o texto especificado após o UA padrão do navegador | Adicionar um identificador ao UA padrão |
| UA aleatório | Sorteia um UA do conjunto de candidatos selecionado | Atribuir valores aleatórios por carregamento de página ou por aba |
Adicionar texto usa o UA padrão do navegador, não um UA substituído do domínio pai nem o UA global. Por exemplo, se a regra global for um UA personalizado e uma regra de domínio acrescentar MyTest, esse domínio usará «UA padrão do navegador + espaço + MyTest». As regras não são acumuladas.
O conjunto de candidatos aleatórios pode vir de UAs integrados, uma lista personalizada, uma lista de textos a acrescentar ou uma combinação dessas fontes; também é possível escolher categorias específicas. Os textos a acrescentar são primeiro combinados com o UA padrão do navegador e depois entram no sorteio. Se o conjunto estiver vazio ou não tiver conteúdo válido, a regra não poderá ser uma regra válida para a página principal.
03Prioridade das regras da página principal
Regra de aba → regra de domínio válida mais específica → regras de domínios pai, nível por nível → regra global → UA padrão do navegador.
É usada a primeira regra ativada nessa ordem que possa gerar um UA válido; as regras posteriores não são combinadas com ela. Não há prioridade adicional entre modos fixos e aleatórios.
| Ordem de verificação | Exemplo quando a página principal é news.shop.example.com |
|---|---|
| 1 | Regra da aba atual |
| 2 | Regra válida para news.shop.example.com |
| 3 | Regra válida para shop.example.com |
| 4 | Regra válida para example.com |
| 5 | Regra global válida |
| 6 | Nenhuma das anteriores é válida; usar o UA padrão do navegador |
«Válida» exige duas condições: a regra está ativada e pode gerar um UA permitido e não vazio. Regras pausadas, UAs não permitidos e conjuntos vazios de candidatos aleatórios são ignorados.
3.1 Correspondência de domínios
Ao configurar example.com, as seguintes páginas principais correspondem:
| Domínio da página principal | Corresponde? |
|---|---|
example.com |
Sim |
www.example.com |
Sim |
shop.example.com |
Sim |
a.shop.example.com |
Sim |
otherexample.com |
Não |
example.com.other.net |
Não |
example.net |
Não |
Digite example.com no campo de domínio; não digite https://, caminho, parâmetros de consulta ou porta. Atualmente a configuração é por domínio, não por caminho de URL.
A versão 1.4.5 não oferece uma opção para corresponder apenas a esse nome de host exato e excluir todos os subdomínios. Se quiser afetar apenas o ramo shop.example.com, digite shop.example.com, mas os subdomínios dele continuam incluídos.
Na versão atual, a forma de compatibilidade *.example.com também abrange example.com e seus subdomínios, não apenas os subdomínios. Se existirem regras válidas example.com e *.example.com, a primeira tem prioridade; quando ela está pausada, a segunda pode assumir. Novos usuários geralmente precisam apenas da forma simples do domínio.
3.2 Diferença entre pausar e remover
| Ação ou estado | Significado |
|---|---|
| Pausar | Mantém a configuração, mas a exclui temporariamente da correspondência; pode ser retomada |
| Remover | Exclui a regra; recrie-a se necessário |
| Substituída | A regra continua ativada, mas uma regra de maior prioridade se aplica à página atual |
| Inválida | O conteúdo atual não consegue gerar um UA válido; corrija o conteúdo ou o conjunto de candidatos |
Depois de pausar ou remover uma regra, a extensão continua procurando outras regras válidas. Portanto, pausar não é uma regra de exclusão que força a página a usar o UA padrão do navegador.
Suponha que as únicas regras ativadas e válidas sejam UA-G global, UA-P para example.com e UA-C para shop.example.com:
| Ação | Resultado ao abrir shop.example.com |
|---|---|
| As três regras ativadas | UA-C |
| Pausar a regra do subdomínio | UA-P |
| Pausar também a regra do domínio pai | UA-G |
| Pausar também a regra global | UA padrão do navegador |
| Adicionar uma regra de aba válida UA-T | Essa aba usa UA-T |
UA-G, UA-P, UA-C e UA-T são apenas rótulos para diferentes conteúdos de UA.
04Dois modos aleatórios
4.1 Em cada carregamento de página
Um valor é sorteado uma vez para cada carregamento completo da página principal pela rede; os recursos comuns da página reutilizam esse resultado. Atualizar ou fazer uma navegação completa gera novo sorteio; solicitações da página, como imagens, APIs e iframes, não geram cada uma um novo sorteio da página principal.
Por exemplo, suponha que o conjunto de candidatos contenha UA-A, UA-B e UA-C:
| Ação | Um resultado possível |
|---|---|
| Abrir a página pela primeira vez | O documento principal e os recursos comuns usam UA-A |
| A página solicita imagens e APIs em seguida | Continua UA-A |
| Apenas uma âncora ou rota interna de SPA muda | Continua UA-A |
| Atualizar a página | Novo sorteio; pode usar UA-C |
| Navegar completamente para outra página que ainda corresponde a essa regra | Novo sorteio; pode usar UA-B |
«Sortear novamente» não significa necessariamente obter um valor diferente. Da mesma forma, quando o botão de voltar ou avançar do navegador restaura diretamente um documento em cache sem um novo carregamento do documento principal pela rede, isso não pode ser tratado simplesmente como um novo sorteio.
Em redirecionamentos, a regra aplicável continua sendo determinada pela página de destino. Na mesma navegação e regra, cada etapa do redirecionamento não gera sorteios repetidos; se o domínio de destino corresponder a outra regra, essa regra será aplicada.
4.2 Por aba
O resultado aleatório é armazenado por «regra + aba». Enquanto a configuração não mudar e a aba não for fechada, atualizações e navegações completas sob a mesma regra continuarão usando esse resultado.
Por exemplo, configure o modo aleatório «por aba» para example.com:
| Ação | Um resultado possível |
|---|---|
A aba 1 abre example.com |
Esta regra associa UA-A à aba 1 |
A aba 1 atualiza ou acessa shop.example.com, sem regra mais específica |
Continua com UA-A |
A aba 2 abre example.com |
Uma associação é armazenada para a aba 2; pode ser UA-B ou também UA-A |
A aba 1 acessa other.net, que não tem regra, e não há regra global |
Usa o UA padrão do navegador |
A aba 1 retorna a example.com |
Restaura o UA-A original desta regra |
| Fechar a aba 1 e abri-la novamente | A associação original da aba é limpa e pode ser atribuída novamente |
Se houver uma regra shop.example.com separada, mesmo que ambas selecionem o mesmo conjunto de candidatos, elas continuam sendo regras diferentes e armazenam associações aleatórias separadamente. Após mudanças nos parâmetros da regra ou na biblioteca de candidatos, ou após reiniciar o navegador, os resultados aleatórios podem ser reatribuídos.
4.3 Combinações de escopo e modo
A tabela descreve o comportamento depois que uma regra obtém a prioridade da página principal. Modos fixos incluem UA integrado, Personalizado e Adicionar texto.
| Escopo | Modos fixos | Aleatório em cada carregamento de página | Aleatório por aba |
|---|---|---|---|
| Global | Páginas correspondentes usam o UA desta regra | Sorteado a cada carregamento da página principal pela rede | Cada aba armazena sua própria associação para esta regra global |
| Domínio | Páginas do domínio correspondente e de seus subdomínios usam este UA | Sorteado a cada carregamento da página principal pela rede dentro do escopo correspondente | Cada aba armazena sua própria associação para esta regra de domínio |
| Aba | Esta aba usa este UA, inclusive após navegar para outros sites | Esta aba sorteia a cada carregamento da página principal pela rede | Esta aba mantém um resultado aleatório fixo para a regra, preservado em atualizações e navegações entre sites |
Em todas as combinações, os recursos comuns da página herdam primeiro o UA da página principal. O modo aleatório determina a duração do valor e não altera a prioridade das regras.
05Recursos da página e fallback por domínio do recurso
5.1 Os recursos herdam primeiro quando a página principal tem uma regra
Suponha que existam estas regras:
shop.example.com→ UA-Shop.cdn.example.net→ UA-CDN.
Ao abrir shop.example.com e a página carregar cdn.example.net/photo.png, a imagem usa UA-Shop. Mesmo que o domínio de destino do recurso tenha sua própria regra, ela não substitui a regra da página principal. Isso mantém o mesmo UA no documento principal e nos recursos comuns da página.
Se você abrir cdn.example.net diretamente na barra de endereços de uma nova aba, ele passa a ser o domínio da página principal e pode corresponder à própria regra UA-CDN.
5.2 Quando a chave de fallback entra em ação
Alternativa pelo domínio do recurso em «Mais» fica desativada por padrão. É uma chave global independente e se aplica a todos os modos de UA.
Ela só entra em ação quando a página principal não tem UA válido de aba, domínio ou global e permite que os recursos procurem uma regra de domínio válida conforme seu próprio domínio de destino. Os domínios de recursos seguem a mesma lógica: a regra mais específica tem prioridade e, quando uma regra filha está pausada, a regra pai é herdada.
| A página principal tem um UA válido? | Chave | O próprio recurso corresponde a uma regra de domínio válida? | UA dos recursos comuns |
|---|---|---|---|
| Sim | Desativada ou ativada | Sim ou não | Herda o UA da página principal |
| Não | Desativada | Sim ou não | UA padrão do navegador |
| Não | Ativada | Sim | UA gerado pela regra do domínio do recurso |
| Não | Ativada | Não | UA padrão do navegador |
Quando a página principal não tem regra válida, seu documento principal continua usando o UA padrão do navegador; o fallback de recursos nunca atribui um valor à página principal. Uma regra global válida também significa que a página principal tem um UA válido, portanto impede que o fallback assuma os recursos comuns.
5.3 Exemplo de fallback
Abra news.example.org sem regra de aba, de domínio da página principal ou global. Também existe cdn.example.net → UA-CDN:
| Solicitação | Fallback desativado | Fallback ativado |
|---|---|---|
Documento principal news.example.org |
UA padrão | UA padrão |
API news.example.org/api |
UA padrão | UA padrão |
cdn.example.net/app.js |
UA padrão | UA-CDN |
img.cdn.example.net/photo.png |
UA padrão | UA-CDN, herdado da regra do domínio pai do recurso |
other.net/font.woff, sem regra correspondente |
UA padrão | UA padrão |
Se um UA-G global for adicionado, todas as solicitações comuns acima serão regidas pelo UA-G da página principal e o UA-CDN do recurso deixará de assumir.
5.4 Fallback com modos aleatórios
| Modo da regra do domínio do recurso | Como o valor é obtido quando o fallback é permitido |
|---|---|
| Modos fixos | Usa o UA configurado na regra do recurso |
| Aleatório em cada carregamento de página | O resultado é armazenado por «este carregamento da página hospedeira + regra do recurso»; recursos desse carregamento que correspondem à mesma regra o compartilham |
| Aleatório por aba | O resultado é armazenado por «aba hospedeira + regra do recurso»; a mesma aba continua usando-o após atualizações |
Por exemplo, se cdn.example.net usar um modo aleatório e tanto img.cdn.example.net quanto js.cdn.example.net o herdarem, os dois compartilham essa associação. Se img.cdn.example.net tiver sua própria regra válida, ele pertencerá a outra regra e poderá usar um UA diferente.
Outras abas que visitam o domínio do recurso não substituem as associações aleatórias de recursos já armazenadas para a página atual. Ativar o fallback permite que diferentes regras de recursos na mesma página usem UAs diferentes; se quiser manter uma página comum consistente como um todo, normalmente deixe-o desativado (padrão).
06Configurando sua primeira regra
- Abra o site que deseja configurar e clique no ícone do UA Pro na barra de ferramentas.
- Se estiver disponível, clique no botão para configurar uma regra para o site atual ou crie uma nova regra em «Mais».
- Escolha um escopo: «Aba» para um teste temporário apenas na aba atual, «Domínio» para várias abas do mesmo site ou «Global» como padrão para todos os sites.
- Se escolheu Domínio, confira o campo de domínio. Por exemplo, se estiver em
www.example.come quiser incluirshop.example.com, digiteexample.com. - Escolha um modo. Em «Integrado», escolha um navegador ou dispositivo; em «Personalizado», digite um UA completo; em «Adicionar texto», apenas o texto a adicionar; em «Aleatório», escolha um conjunto de candidatos e um modo aleatório.
- Em «Revisar e aplicar», confira o escopo e o conteúdo e clique em «Aplicar» ou «Salvar e aplicar». Aguarde a confirmação «Regra salva e ativada».
- Atualize a página e confira a regra ativa exibida na tela inicial. Páginas existentes precisam ser atualizadas para que tanto o documento principal quanto os scripts adotem o novo UA.
Na lista você pode editar, pausar, retomar ou remover regras. Uma regra substituída por outra continua ativada, mas não tem prioridade no momento; uma regra pausada não participa da correspondência. Se aparecer um aviso de ausência de UA válido, confira o conteúdo personalizado ou o conjunto de candidatos aleatórios.
Um UA personalizado deve ser uma única linha de conteúdo válido para cabeçalho de solicitação, sem quebras de linha ou caracteres de controle. Novos conteúdos personalizados ou textos a acrescentar podem ser salvos em uma lista por categoria para seleção posterior ou uso como candidatos aleatórios.
07Ativar o painel flutuante de UA
Abra Mais e ative Painel flutuante de UA. Ela fica desativada por padrão e pode aparecer em páginas HTTP/HTTPS acessíveis.
UA da página: o valor que o JavaScript da página lê de navigator.userAgent.
UA da solicitação: o User-Agent observado pelo navegador para esta solicitação do documento principal.
Isso mostra o UA da página atual na barra de endereços do navegador. Não inclui o UA de solicitações de imagens, scripts, APIs ou outros recursos, como recursos de CDN.
Se os dois valores estiverem disponíveis e forem exatamente iguais, serão exibidos em uma linha. Caso contrário, serão exibidos separadamente.
Se a janela foi ativada após o carregamento da página, atualize a página para capturar sua solicitação principal. Quando a solicitação não estiver disponível, a janela mostrará esse estado em vez de usar o valor configurado.
Para mover a janela, arraste a alça ou um rótulo. Arraste a borda esquerda ou direita para ajustar a largura e a borda superior ou inferior para ajustar a altura. Clique duas vezes em uma borda para restaurar o tamanho automático apenas nessa dimensão. O botão semicircular ajusta a opacidade do fundo. O botão de fechar desativa a janela em todas as páginas.
Se um User-Agent for longo, o texto continuará automaticamente na linha seguinte em uma janela estreita. A janela aumenta de altura quando necessário. Role dentro da janela se o texto ultrapassar a altura da tela. A largura e a altura definidas manualmente permanecem até serem redefinidas.
A janela tenta manter o mesmo tamanho enquanto carrega os valores de uma nova página. Ela mostra um indicador de carregamento, nunca os valores da página anterior. Uma navegação completa recria a página, então a janela pode desaparecer por instantes.
Alterar uma regra não muda uma página já carregada nem o cabeçalho enviado com a solicitação original. Atualize para conferir a nova regra. Um proxy ou servidor pode alterar os cabeçalhos após a observação pelo navegador. A janela não aparece em páginas protegidas do navegador ou lojas de extensões.
O menu Mais também contém Guia para novos usuários; clique em UA Pro na parte inferior desse menu para abrir o site.
08Configurando objetivos comuns
| Objetivo | Como configurar | Observações |
|---|---|---|
| Testar um UA móvel apenas na aba atual | Aba + UA móvel integrado | Continua valendo quando essa aba acessa outros sites; termina ao ser fechada |
| Usar um UA fixo em um site inteiro | Domínio example.com + UA integrado ou personalizado |
Inclui todos os subdomínios e também vale para outras abas |
| Usar um UA diferente para uma seção de loja | Mantenha a regra pai e adicione uma regra shop.example.com |
Sem uma regra de prioridade maior, a regra filha tem prioridade; quando ela é pausada, a regra pai pode assumir |
| Usar um UA padrão para todos os sites com uma exceção | Defina UA-G globalmente e UA-D no domínio de destino | Onde nenhuma outra regra de prioridade maior se aplica, o domínio de destino usa UA-D e as demais páginas usam UA-G |
| Sortear novamente o UA de um site a cada atualização | Domínio + UA aleatório + em cada carregamento de página | Os recursos desse carregamento compartilham o valor; um sorteio pode se repetir |
| Manter o UA de um site estável em cada aba | Domínio + UA aleatório + por aba | Cada regra armazena uma associação separada em cada aba |
| Definir UAs somente para recursos externos pelo domínio de destino | Crie uma regra de domínio do recurso e ative o fallback de recursos | A página hospedeira não pode ter UA válido de aba, domínio ou global |
| Desativar temporariamente uma regra de subdomínio | Clique em «Pausar» | A página usa a regra válida restante de maior prioridade, como uma regra de aba, outra regra de domínio correspondente ou a regra global. Se nenhuma se aplicar, usa o UA padrão do navegador |
09Backup e migração
As funções de importação e exportação em «Mais» podem fazer backup ou migrar regras globais e de domínio, a biblioteca personalizada, a biblioteca de textos a acrescentar e a chave de fallback por domínio do recurso.
Regras de aba e associações aleatórias já sorteadas não fazem parte dessa exportação de configuração persistente. A importação não recria as abas originais nem seu estado aleatório.
Você pode importar um arquivo local de configuração ou carregar um endereço remoto de configuração e confirmar a importação. Exporte um backup antes. Um objeto fornecido de regra global, regras de domínio, biblioteca personalizada ou biblioteca de textos adicionados substitui a seção correspondente; seções ausentes ou null mantêm os valores existentes. Em particular, uma regra global null não apaga uma regra global existente. A alternativa pelo domínio do recurso só é ativada quando seu campo é true; com qualquer outro valor, inclusive campo ausente ou null, fica desativada após a importação.
Na versão 1.4.5, o modo aleatório antigo domain é tratado como «Em cada carregamento de página»; regras aleatórias antigas sem estratégia aleatória especificada são tratadas como «Por aba». Após a migração, confira na interface o modo aleatório necessário.
10Perguntas frequentes e limites de uso
| Pergunta | Explicação |
|---|---|
| Por que a página ainda mostra o UA antigo logo após salvar? | Documentos existentes não são recarregados; atualize após salvar com sucesso. Confira também se uma regra de maior prioridade a substitui |
| Por que um UA personalizado ainda é usado depois que pausei a regra filha? | Uma regra de aba válida ainda pode ter prioridade. Caso contrário, outra regra de domínio correspondente ou a regra global pode assumir. Após alterar a regra, atualize a página e confira a regra ativa |
| Por que minha regra de domínio do recurso não funciona? | Confira primeiro se a página principal já tem um UA válido, depois se o fallback de recursos está ativado e, por fim, se a regra de domínio do recurso é válida |
| Por que o valor aleatório não muda após uma atualização? | O modo por aba o mantém por definição; o modo a cada carregamento também pode sortear o mesmo valor novamente |
| Por que abas abertas ao mesmo tempo têm o mesmo UA? | Valores aleatórios podem se repetir; primeiras navegações simultâneas também podem compartilhar um valor reserva sorteado antecipadamente |
| Por que a página ainda parece a versão para computador depois de mudar para um UA móvel? | Os sites também podem usar tamanho da tela, Client Hints ou outras informações; alterar apenas o UA não garante um layout diferente |
As primeiras navegações simultâneas preservam a navegação nativa do navegador: quando várias abas novas abrem uma URL diretamente ao mesmo tempo e o primeiro pacote é enviado antes da instalação da regra específica, elas podem usar o mesmo UA sorteado antecipadamente; depois cada aba armazena sua própria associação. A extensão não adiciona um intermediário de navegação nem altera POSTs nativos de formulários para outro método de navegação.
Páginas HTTP/HTTPS comuns e seus recursos são o principal alvo deste recurso. Solicitações de Service Workers compartilhados nem sempre podem ser atribuídas a uma única aba; a sincronização do UA para Client Hints, navigator em Workers e iframes com documentos sem carregamento de rede não está totalmente implementada nesta versão. A preservação do Server-Timing original de um site também ainda não está implementada nesta alteração. Não considere a modificação do UA uma falsificação completa da impressão digital do navegador.
A versão 1.4.5 usa as permissões webRequest e webNavigation para acompanhar a navegação da página principal e o UA realmente enviado. Ela não usa permissões de bloqueio de solicitações nem de depuração.
11Verificação de versão e referências
O ambiente de verificação final da versão 1.3.0 foi um perfil de teste isolado no Windows Edge 157.0.4341.42 com sites HTTP/HTTPS locais. A execução HTTPS completa passou em 128 casos com 2527 asserções; a regressão dos limites HTTP passou em 5 casos com 441 asserções. Esses testes verificam as combinações de regras descritas e o limite de concorrência informado; não significam que todas as versões de navegadores e sites tenham sido cobertas.
A janela da versão 1.4.5 foi testada em perfis isolados do Chrome e Edge com páginas HTTPS locais. Os testes cobriram navegação, combinação de UAs idênticos da página e da solicitação em uma linha, redimensionamento e leituras atrasadas. Eles não cobrem todos os sites.
Os registros detalhados dos testes são mantidos nos materiais do projeto. Confira a versão instalável na Chrome Web Store ou na página de download offline; as versões disponíveis podem ser diferentes da deste guia.