Este guia se aplica ao UA Pro 1.5.0 e explica como fazer backup, migrar e criar configurações manualmente e carregá-las de um endereço remoto. A nova versão usa um formato de instantâneo completo: o version do arquivo de configuração é 2.
Antes de importar, exporte um backup no navegador de destino. Cada importação substitui a regra global, todo o conjunto de regras de domínio, as duas bibliotecas de UA e o controle de alternativa pelo domínio do recurso pelo instantâneo completo do arquivo; as entradas não são mescladas individualmente. "globalRule": null significa que a regra global do navegador de destino será limpa.
01Exportar configuração
- Clique no ícone do UA Pro na barra de ferramentas do navegador.
- Abra “Mais” → “Importar ou exportar configuração”.
- Clique em “Exportar configuração” e salve o arquivo
.jsonbaixado. - O nome do arquivo é semelhante a
ua-switcher-config-2026-11-16.json. A data no nome é gerada em UTC e pode diferir da data local em um dia.
O arquivo contém as seguintes configurações persistentes:
- A regra global e seu estado ativado ou pausado.
- Todo o conjunto de regras de domínio e seus estados ativados ou pausados.
- Categorias e itens de UA personalizados.
- Categorias e itens de texto acrescentado.
- O controle “Alternativa pelo domínio do recurso”.
O arquivo não inclui regras de aba, vinculações de UA aleatório já selecionadas, abas abertas no momento, idioma da interface, tema nem configurações da sobreposição. Esses itens não serão restaurados do backup após a importação; as regras de aba já existentes no navegador de destino também não são removidas pela importação e podem continuar prevalecendo sobre regras de domínio ou globais.
O arquivo exportado é JSON legível em texto simples. Guarde o backup com segurança se os UAs personalizados ou as categorias contiverem informações que você não deseja divulgar.
02Importar de um arquivo local
- No navegador de destino, abra UA Pro → “Mais” → “Importar ou exportar configuração”.
- Primeiro clique em “Exportar configuração” para preservar a configuração original do navegador de destino, caso seja necessário restaurá-la.
- Clique em “Importar configuração” e selecione o arquivo
.json. - Leia o aviso de substituição e as quantidades de regras e listas. Clique em “Ver conteúdo da configuração” para examinar o JSON completo antes de confirmar. Escolher “Cancelar” não grava nada. Após confirmar, aguarde a mensagem “Configuração importada!”. Se as configurações mudarem durante a confirmação, a extensão solicitará que você repita a operação.
- Verifique as regras globais e de domínio, as listas personalizadas e o controle de alternativa pelo domínio do recurso; verifique também se alguma regra de aba existente prevalece sobre elas. Atualize as páginas que deseja testar e confirme o UA.
A extensão primeiro verifica o arquivo, depois tenta instalar as regras e, por fim, grava a configuração persistente. Se a instalação ou gravação falhar, ela tenta restaurar as regras atualmente salvas no navegador. Se informar que não foi possível restaurá-las, verifique as configurações reais. Quando a sincronização do navegador ou outra janela altera a configuração ao mesmo tempo, esse processo não deve ser entendido como uma transação entre dispositivos.
03Carregar de um endereço remoto
A configuração remota usa o mesmo conteúdo JSON de um backup local. É um carregamento e uma importação manuais pontuais, não uma assinatura atualizada automaticamente.
- Primeiro exporte um backup da configuração ou prepare um arquivo JSON conforme descrito abaixo.
- Coloque o arquivo em um serviço HTTPS acessível ao navegador de destino e obtenha um endereço completo que retorne diretamente o conteúdo JSON, por exemplo
https://example.com/ua-pro/config.json. Esse endereço é apenas um exemplo; substitua-o pelo seu endereço real. - No UA Pro, abra “Mais” → “Importar ou exportar configuração”, expanda “Configuração remota”, cole o endereço e clique em “Carregar”.
- Depois que o carregamento e a verificação do formato forem concluídos, a extensão exibirá uma caixa de confirmação e o nome do host remoto. Clique em “Ver conteúdo da configuração” para examinar o JSON completo efetivamente baixado. A confirmação atualiza as configurações pelas mesmas regras da importação local; cancelar não importa.
- Depois que o arquivo for alterado no servidor, digite novamente o endereço, carregue e confirme para usar o novo conteúdo. O endereço não é mantido automaticamente quando o painel é reaberto.
São aceitos apenas links HTTPS diretos; HTTP, nomes de usuário ou senhas no endereço e fragmentos de URL não são aceitos, e redirecionamentos não são seguidos. A solicitação não inclui cookies do navegador nem credenciais de login, não envia Referer e ignora o cache; portanto, serviços que exigem cookie de login não são adequados. O UA Pro não aplica a essa solicitação as regras de UA configuradas nesta extensão, mas outras extensões ou dispositivos de rede ainda podem modificá-la. O endereço pode conter parâmetros de consulta; proteja endereços com token de acesso como senhas. Use um endereço confiável e certifique-se de que a resposta seja diretamente um arquivo JSON, não uma página de login ou uma página HTML que exiba código.
Arquivos locais e respostas remotas têm limite de 128 KiB cada; a leitura remota tem prazo de 10 segundos e contabiliza o conteúdo efetivamente lido. O armazenamento sincronizado do navegador também tem uma cota menor por item, portanto um arquivo abaixo de 128 KiB ainda pode não ser salvo se as regras ou uma biblioteca individual forem grandes demais. Em caso de erro, verifique se o servidor retorna status 200 e JSON válido, se o certificado é válido, se o endereço redireciona e se a rede está acessível.
04Exemplo JSON completo
O exemplo abaixo pode ser salvo como config.json codificado em UTF-8. Os domínios e valores de UA do exemplo são apenas ilustrativos; faça backup da configuração atual antes de substituí-la. JSON diferencia maiúsculas de minúsculas: use aspas duplas nas strings, não coloque vírgula após o último item e não escreva comentários no JSON.
{
"version": 2,
"type": "ua-switcher-config",
"timestamp": "2026-11-16T06:00:00.000Z",
"data": {
"globalRule": {
"enabled": true,
"mode": "builtin",
"params": {
"os": "Windows",
"uaKey": "Edge 125 (Latest)"
}
},
"domainRules": {
"example.com": {
"enabled": true,
"mode": "custom",
"params": {
"category": "手机示例",
"value": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1"
}
},
"app.example.com": {
"enabled": true,
"mode": "append",
"params": {
"category": "测试标记",
"value": "MyApp/1.0"
}
},
"random.example.com": {
"enabled": true,
"mode": "random",
"params": {
"pool": "custom:随机示例",
"strategy": "page"
}
},
"paused.example.com": {
"enabled": false,
"mode": "custom",
"params": {
"category": "测试",
"value": "ExampleAgent/1.0"
}
}
},
"userCustomData": {
"手机示例": [
"Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1"
],
"随机示例": [
"ExampleAgent/1.0",
"ExampleAgent/2.0"
],
"测试": [
"ExampleAgent/1.0"
]
},
"userAppendData": {
"测试标记": [
"MyApp/1.0"
]
},
"resourceDomainFallback": false
}
}
Este exemplo define um UA global integrado e quatro regras de domínio. Regras de subdomínio mais específicas, como app.example.com, têm prioridade sobre example.com. Regras pausadas não participam da correspondência ativa, portanto uma regra do domínio pai ou global ainda pode entrar em vigor. O reconhecimento do UA de exemplo por um site real depende do próprio site.
05Campos de nível superior e substituição
| Campo | Exemplo | Função |
|---|---|---|
version |
2 |
Obrigatório. A nova versão aceita apenas o valor numérico 2. |
type |
"ua-switcher-config" |
Obrigatório. Identificador do tipo de configuração; deve corresponder exatamente a esta string. |
timestamp |
"2026-11-16T06:00:00.000Z" |
Obrigatório. Horário UTC com milissegundos e Z; serve apenas para registro e não determina quando as regras entram em vigor. |
data |
{ ... } |
Obrigatório. Objeto que contém a configuração completa, incluindo todos os campos da tabela abaixo. |
Campos em data |
Formato correto | Comportamento da importação nesta versão |
|---|---|---|
globalRule |
Um objeto de regra ou null |
Um objeto de regra substitui a regra global existente; null a limpa. |
domainRules |
{ "域名": 规则对象 } |
O objeto inteiro substitui as regras de domínio anteriores; {} as limpa. |
userCustomData |
{ "分类": ["UA", ...] } |
O objeto inteiro substitui a biblioteca anterior de UA personalizado; {} a limpa. |
userAppendData |
{ "分类": ["追加文本", ...] } |
O objeto inteiro substitui a biblioteca anterior de texto acrescentado; {} a limpa. |
resourceDomainFallback |
true ou false |
Valor booleano JSON: ativa ou desativa a alternativa pelo domínio do recurso. |
Todos os cinco campos são obrigatórios; null não pode ser usado, exceto em globalRule. Campos ausentes ou desconhecidos e chaves JSON duplicadas são rejeitados; configurações parciais ou de versões antigas também não são importadas. As regras de domínio e as duas bibliotecas são substituídas por conjuntos completos: por exemplo, um domainRules com apenas um domínio substituirá as demais regras de domínio existentes no navegador de destino. Recomendamos editar um arquivo realmente exportado pela nova versão e manter integralmente os itens necessários.
A alternativa pelo domínio do recurso só pode aplicar uma regra pelo domínio de destino da solicitação do recurso quando a página principal não tem UA ativo de aba, domínio ou global. Isso não significa que todos os recursos de outros domínios prevaleçam sobre a regra da página principal.
06Como escrever objetos de regra
A regra global e cada regra de domínio usam a mesma estrutura:
{
"enabled": true,
"mode": "custom",
"params": {
"category": "常用",
"value": "ExampleAgent/1.0"
}
}
enabled: true significa ativada e false significa pausada. mode determina os campos de params:
6.1 UA integrado: builtin
{
"enabled": true,
"mode": "builtin",
"params": { "os": "Windows", "uaKey": "Edge 125 (Latest)" }
}
os e uaKey devem corresponder exatamente às chaves internas predefinidas desta versão da extensão; elas não são necessariamente iguais aos textos traduzidos exibidos na interface. O mais seguro é selecionar a predefinição na interface, exportar a configuração e copiar o params correspondente. Confira novamente quando a lista de predefinições mudar entre versões.
6.2 UA personalizado: custom
{
"enabled": true,
"mode": "custom",
"params": { "category": "常用", "value": "ExampleAgent/1.0" }
}
value é a string completa do UA. category é usado para classificação e edição na interface; recomendamos incluir também o valor na categoria de mesmo nome em userCustomData. Quando entra em vigor, a regra lê seu próprio value; importar uma regra manualmente não adiciona o valor automaticamente à biblioteca personalizada.
6.3 Acrescentar texto: append
{
"enabled": true,
"mode": "append",
"params": { "category": "应用标记", "value": "MyApp/1.0" }
}
A extensão adiciona um espaço após o UA original do navegador atual e acrescenta value. Recomendamos manter também esse texto na categoria de mesmo nome em userAppendData; importar a regra não preenche a lista automaticamente.
6.4 UA aleatório: random
{
"enabled": true,
"mode": "random",
"params": { "pool": "custom:随机示例", "strategy": "page" }
}
strategy deve ser "page" (selecionado a cada carregamento completo de página) ou "tab" (mantido por regra e aba). Seleções aleatórias podem se repetir; dois resultados iguais consecutivos não significam necessariamente que não houve nova seleção.
Valores comuns de pool:
| Valor | Origem aleatória |
|---|---|
all |
Todos os UAs integrados, personalizados e gerados a partir de texto acrescentado |
builtin |
Todos os UAs integrados |
builtin_desktop, builtin_mobile, builtin_legacy |
Categorias integradas de desktop, dispositivos móveis ou antigos |
builtin_gaming, builtin_smarttv, builtin_communication, builtin_social |
A categoria integrada correspondente |
custom |
UAs de todas as categorias personalizadas |
custom:分类名 |
UAs da categoria especificada em userCustomData |
append_all |
UAs correspondentes a todos os textos acrescentados |
append:分类名 |
UAs correspondentes ao texto acrescentado na categoria especificada em userAppendData |
O nome da categoria após os dois-pontos deve corresponder a uma chave da biblioteca. Uma regra aleatória ativada deve ter candidatos disponíveis; caso contrário, o arquivo será rejeitado.
07Verificações na edição manual
- Use nomes de domínio como chaves de
domainRules, por exemploexample.comoushop.example.com; não incluahttps://, caminhos, portas ou espaços. Regras de domínio também correspondem a subdomínios. Nesta versão,*.example.comtambém inclui o próprioexample.com; não significa “somente subdomínios”. - Nomes de categoria podem conter caracteres chineses e devem ser strings não vazias, sem caracteres de controle nem controles bidirecionais perigosos;
__proto__,prototypeeconstructornão podem ser nomes de categoria. Recomendamos usar caracteres ASCII imprimíveis para UAs e texto acrescentado. Não inclua quebras de linha, tabulações nem outros caracteres de controle. Cada UA pode ter até 4096 caracteres. Aspas duplas e barras invertidas no texto devem ser escapadas conforme as regras JSON. - Cada categoria corresponde a uma matriz de strings, por exemplo
"常用": ["Agent/1.0", "Agent/2.0"]. Mantenha os colchetes mesmo com apenas um item. Uma categoria vazia pode ser escrita como[]. - Não coloque aspas duplas em
true,falseounull;"false"é uma string, não um booleano. - O arquivo deve ser UTF-8 e JSON válidos, sem chaves duplicadas. A extensão também verifica estrutura, tipos de campo, regras, nomes predefinidos e conjuntos aleatórios; sintaxe correta não garante que uma regra possa ser usada.
Um arquivo de configuração pode alterar o UA que o navegador envia aos sites. HTTPS protege a transmissão, mas não garante que a configuração fornecida pelo servidor corresponda ao que você deseja. Importe apenas arquivos de fontes confiáveis, examine o conteúdo antes de confirmar e verifique o efeito real após atualizar a página de destino.
08Perguntas frequentes
| Problema | O que verificar |
|---|---|
| Formato do arquivo informado como inválido | Verifique UTF-8, sintaxe JSON, chaves duplicadas, versão, campos obrigatórios e tipos de regra. Use como modelo um arquivo exportado pela nova versão. |
| Falha no carregamento remoto | Verifique o certificado HTTPS, o link direto, a rede e o conteúdo da resposta. Redirecionamentos, login por cookie e HTTP não são permitidos. |
| Faltam regras após a importação | As regras de domínio e as duas bibliotecas são substituídas por conjuntos completos. Restaure o backup anterior à importação ou inclua no novo arquivo todos os itens que deseja manter. |
| Uma regra global vazia foi importada, mas a página continua usando outro UA | Verifique regras de aba existentes ou regras de domínio correspondentes; elas podem ter prioridade sobre a regra global. |
| A importação foi bem-sucedida, mas o UA está incorreto | Verifique se a regra está ativada, se o conteúdo é válido, se o conjunto aleatório tem itens disponíveis e se há regras de aba ou domínio de prioridade maior; depois atualize a página. |
| Erro de armazenamento ao importar muitos dados | O arquivo e o armazenamento sincronizado do navegador têm limites de tamanho. Reduza as regras ou listas e tente novamente; confira a configuração existente. |
| A extensão não muda depois que o arquivo remoto é alterado | O carregamento remoto é uma importação manual pontual. Digite novamente o endereço, carregue e confirme. |