Guida alla configurazione di UA Pro

Importazione, esportazione e configurazione remota

Salvare, trasferire e scrivere manualmente la configurazione e caricarla da un indirizzo remoto.

Versione: UA Pro 1.5.0

Questa guida riguarda UA Pro 1.5.0 e spiega come salvare, trasferire e scrivere manualmente una configurazione e caricarla da un indirizzo remoto. La nuova versione usa un’istantanea completa: nel file di configurazione version vale 2.

Prima dell’importazione, esporta una copia di backup nel browser di destinazione. Ogni importazione sostituisce la regola globale, l’intero insieme di regole di dominio, entrambe le raccolte UA e l’interruttore della regola alternativa del dominio della risorsa con l’istantanea completa del file, senza unire i singoli elementi. "globalRule": null elimina la regola globale nel browser di destinazione.

01Esportare la configurazione

  1. Fai clic sull’icona UA Pro nella barra degli strumenti del browser.
  2. Apri «Altro» → «Importa o esporta configurazione».
  3. Fai clic su «Esporta configurazione» e salva il file .json scaricato.
  4. Il nome del file è simile a ua-switcher-config-2026-11-16.json. La data nel nome è generata in UTC e può differire di un giorno da quella locale.

Il file contiene la seguente configurazione persistente:

  • La regola globale e il suo stato attivo o sospeso.
  • L’intero insieme delle regole di dominio e il loro stato attivo o sospeso.
  • Categorie e voci UA personalizzate.
  • Categorie e voci di testo aggiunto.
  • L’interruttore «Regola alternativa del dominio della risorsa».

Il file non contiene regole di scheda, associazioni di UA casuali già estratti, schede aperte, lingua dell’interfaccia, tema e impostazioni del pannello flottante. Questi elementi non vengono ripristinati dal backup durante l’importazione. Le regole di scheda già presenti nel browser di destinazione non vengono eliminate e possono quindi continuare ad avere la precedenza sulle regole di dominio o globale.

Il file esportato è JSON leggibile in testo normale. Se UA o categorie personalizzate contengono informazioni che non vuoi rendere pubbliche, conserva il backup con cura.

02Importare da un file locale

  1. Nel browser di destinazione apri UA Pro → «Altro» → «Importa o esporta configurazione».
  2. Fai prima clic su «Esporta configurazione» per conservare la configurazione originale del browser di destinazione e poterla ripristinare.
  3. Fai clic su «Importa configurazione» e seleziona il file .json.
  4. Leggi l’avviso di sostituzione e i numeri di regole e voci degli elenchi; fai clic su «Mostra il contenuto della configurazione» per controllare il JSON completo prima di confermare. «Annulla» non scrive dati. Dopo la conferma attendi «Configurazione importata!». Se le impostazioni cambiano durante la conferma, l’estensione chiederà di ripetere l’operazione.
  5. Controlla le regole globali e di dominio, gli elenchi personalizzati e l’interruttore della regola alternativa del dominio della risorsa; verifica anche se regole di scheda esistenti hanno la precedenza. Aggiorna la pagina da testare e verifica l’UA.

L’estensione controlla prima il file, quindi tenta di installare le regole e infine scrive la configurazione persistente. Se l’installazione o la scrittura fallisce, tenta di ripristinare le regole attualmente salvate nel browser; se segnala che non può ripristinarle, controlla le impostazioni effettive. In caso di modifiche contemporanee da sincronizzazione del browser o altre finestre, il processo non va interpretato come una transazione tra dispositivi.

03Caricare da un indirizzo remoto

La configurazione remota usa lo stesso contenuto JSON di un backup locale. Il caricamento e l’importazione sono manuali e una tantum, non un abbonamento aggiornato automaticamente.

  1. Esporta prima un backup della configurazione oppure prepara un file JSON come descritto sotto.
  2. Colloca il file su un servizio HTTPS raggiungibile dal browser di destinazione e ottieni l’indirizzo completo che restituisce direttamente il contenuto JSON, ad esempio https://example.com/ua-pro/config.json. L’indirizzo è solo un esempio: sostituiscilo con quello effettivo.
  3. In UA Pro, apri «Altro» → «Importa o esporta configurazione», espandi «Configurazione remota», incolla l’indirizzo e fai clic su «Carica».
  4. Dopo il caricamento e il controllo del formato, l’estensione mostra una finestra di conferma e il nome host remoto. Fai clic su «Mostra il contenuto della configurazione» per controllare il JSON completo effettivamente scaricato. La conferma aggiorna le impostazioni secondo le stesse regole dell’importazione locale; annullando non si importa nulla.
  5. Quando il file sul server cambia, per usare il nuovo contenuto devi inserire di nuovo l’indirizzo, caricare e confermare. Riaprendo il pannello, l’indirizzo non viene conservato automaticamente.

Sono accettati solo collegamenti HTTPS diretti; non sono ammessi HTTP, nomi utente o password nell’indirizzo e frammenti URL, né vengono seguiti reindirizzamenti. La richiesta non include cookie del browser o credenziali di accesso, non invia Referer e ignora la cache; i servizi che richiedono cookie di accesso non sono quindi adatti. UA Pro non applica alla richiesta le regole UA configurate in questa estensione, ma altre estensioni o dispositivi di rete possono modificarla. L’indirizzo può contenere parametri di query; proteggi gli indirizzi con token di accesso come password. Usa un indirizzo affidabile e assicurati che la risposta sia direttamente un file JSON, non una pagina di accesso o una pagina HTML che mostra codice.

I file locali e le risposte remote sono limitati ciascuno a 128 KiB; la lettura remota è limitata a 10 secondi e viene contato il contenuto effettivamente letto. L’archiviazione sincronizzata del browser ha anche una quota inferiore per singolo elemento: anche sotto 128 KiB il file potrebbe non essere salvato se le regole o una raccolta sono troppo grandi. In caso di errore, controlla che il server restituisca stato 200 e JSON valido, che il certificato sia valido, che l’indirizzo non reindirizzi e che la rete sia raggiungibile.

04Esempio JSON completo

L’esempio seguente può essere salvato come config.json con codifica UTF-8. Domini e valori UA sono solo esemplificativi; esegui prima un backup della configurazione esistente. JSON distingue maiuscole e minuscole: usa virgolette doppie diritte per le stringhe, non mettere una virgola dopo l’ultimo elemento e non scrivere commenti nel JSON.

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
  }
}

Questo esempio imposta un UA globale integrato e quattro regole di dominio. Le regole di sottodominio più specifiche, come app.example.com, hanno precedenza su example.com. Le regole sospese non partecipano alla selezione attiva; può invece applicarsi una regola del dominio padre o quella globale. Il riconoscimento dell’UA di esempio dipende dal sito effettivo.

05Campi principali e sostituzione

Campo Esempio Funzione
version 2 Obbligatorio. La nuova versione accetta solo il valore numerico 2.
type "ua-switcher-config" Obbligatorio. Identificatore del tipo di configurazione; deve corrispondere esattamente alla stringa.
timestamp "2026-11-16T06:00:00.000Z" Obbligatorio. Ora UTC con millisecondi e Z; serve solo come registrazione e non determina quando le regole diventano effettive.
data { ... } Obbligatorio. Oggetto contenente la configurazione completa e tutti i campi della tabella seguente.
Campi in data Formato corretto Comportamento all’importazione in questa versione
globalRule Un oggetto regola oppure null L’oggetto regola sostituisce la regola globale esistente; null la elimina.
domainRules { "域名": 规则对象 } L’intero oggetto sostituisce le precedenti regole di dominio; {} le svuota.
userCustomData { "分类": ["UA", ...] } L’intero oggetto sostituisce la precedente raccolta UA personalizzata; {} la svuota.
userAppendData { "分类": ["追加文本", ...] } L’intero oggetto sostituisce la precedente raccolta di testo aggiunto; {} la svuota.
resourceDomainFallback true oppure false Valore booleano JSON: attiva o disattiva la regola alternativa del dominio della risorsa.

Tutti e cinque i campi sono obbligatori; null è consentito solo per globalRule. Campi mancanti o sconosciuti e chiavi JSON duplicate vengono rifiutati; non vengono importate nemmeno versioni precedenti o configurazioni parziali. Le regole di dominio e le due raccolte vengono sostituite ciascuna per intero: ad esempio, un domainRules con un solo dominio sostituisce le altre regole di dominio già presenti nel browser di destinazione. Si consiglia di modificare un file realmente esportato dalla nuova versione e conservare integralmente gli elementi necessari.

La regola alternativa del dominio della risorsa può applicare una regola in base al dominio di destinazione della richiesta della risorsa solo se la pagina principale non ha un UA effettivo di scheda, dominio o globale. Non significa che tutte le risorse tra domini diversi prevalgano sulla regola della pagina principale.

06Scrivere un oggetto regola

La regola globale e ogni regola di dominio usano la stessa struttura:

JSON
{
  "enabled": true,
  "mode": "custom",
  "params": {
    "category": "常用",
    "value": "ExampleAgent/1.0"
  }
}

enabled: true indica attiva e false sospesa. mode determina i campi di params:

6.1 UA integrato: builtin

JSON
{
  "enabled": true,
  "mode": "builtin",
  "params": { "os": "Windows", "uaKey": "Edge 125 (Latest)" }
}

os e uaKey devono corrispondere esattamente alle chiavi predefinite interne di questa versione dell’estensione; non coincidono necessariamente con le etichette tradotte nell’interfaccia. Il metodo più sicuro è scegliere il valore predefinito nell’interfaccia, esportare la configurazione e copiare i relativi params. Ricontrolla quando l’elenco dei valori predefiniti cambia tra versioni.

6.2 UA personalizzato: custom

JSON
{
  "enabled": true,
  "mode": "custom",
  "params": { "category": "常用", "value": "ExampleAgent/1.0" }
}

value è la stringa UA completa. category serve per classificazione e modifica nell’interfaccia; si consiglia di includere il valore anche nella categoria omonima di userCustomData. La regola attiva legge il proprio value; importare manualmente una regola non aggiunge automaticamente il valore alla raccolta personalizzata.

6.3 Testo aggiunto: append

JSON
{
  "enabled": true,
  "mode": "append",
  "params": { "category": "应用标记", "value": "MyApp/1.0" }
}

L’estensione aggiunge uno spazio dopo l’UA originale del browser corrente, seguito da value. Si consiglia di conservare il testo anche nella categoria omonima di userAppendData; l’importazione della regola non popola automaticamente l’elenco.

6.4 UA casuale: random

JSON
{
  "enabled": true,
  "mode": "random",
  "params": { "pool": "custom:随机示例", "strategy": "page" }
}

strategy deve essere "page" (estrazione a ogni caricamento completo della pagina) oppure "tab" (mantenuto per regola e scheda). Le estrazioni casuali possono ripetersi: due risultati uguali consecutivi non indicano necessariamente che non sia avvenuta una nuova estrazione.

Valori comuni di pool:

Valore Origine casuale
all Tutti gli UA integrati e personalizzati e gli UA generati dai testi aggiunti
builtin Tutti gli UA integrati
builtin_desktop, builtin_mobile, builtin_legacy Categorie integrate per desktop, dispositivi mobili o meno recenti
builtin_gaming, builtin_smarttv, builtin_communication, builtin_social Categorie integrate corrispondenti
custom UA di tutte le categorie personalizzate
custom:分类名 UA della categoria specificata in userCustomData
append_all UA corrispondenti a tutti i testi aggiunti
append:分类名 UA corrispondenti ai testi aggiunti della categoria specificata in userAppendData

Il nome della categoria dopo i due punti deve corrispondere alla chiave nella raccolta. Una regola casuale attiva deve avere candidati disponibili, altrimenti il file viene rifiutato.

07Controlli per la modifica manuale

  • Come chiavi di domainRules usa nomi di dominio, ad esempio example.com o shop.example.com, senza https://, percorsi, porte o spazi. Le regole di dominio corrispondono anche ai sottodomini; in questa versione *.example.com include anche example.com stesso e non significa «solo sottodomini».
  • I nomi delle categorie possono essere in cinese; devono essere stringhe non vuote senza caratteri di controllo o caratteri pericolosi di controllo del testo bidirezionale. __proto__, prototype e constructor non possono essere nomi di categoria. Per gli UA e il testo aggiunto si consiglia di usare caratteri ASCII stampabili; non usare ritorni a capo, tabulazioni o altri caratteri di controllo. Ogni UA può avere al massimo 4096 caratteri. Le virgolette doppie diritte e le barre inverse nel testo devono essere sottoposte a escape secondo le regole JSON.
  • Ogni categoria corrisponde a un array di stringhe, ad esempio "常用": ["Agent/1.0", "Agent/2.0"]. Mantieni le parentesi quadre anche con un solo elemento. Una categoria vuota può essere scritta come [].
  • true, false e null non vanno racchiusi tra virgolette doppie; "false" è una stringa, non un booleano.
  • Il file deve essere UTF-8 e JSON validi, senza chiavi duplicate. L’estensione controlla anche struttura, tipi dei campi, regole, nomi dei valori predefiniti e pool casuali. Una sintassi corretta non garantisce che una regola sia utilizzabile.

Un file di configurazione può modificare l’UA inviato dal browser ai siti. HTTPS protegge il trasporto, ma non garantisce che la configurazione fornita dal server corrisponda alle tue intenzioni. Importa solo file da fonti affidabili, controlla il contenuto prima di confermare e verifica l’effetto effettivo dopo aver aggiornato la pagina di destinazione.

08Domande frequenti

Problema Verifica
Viene segnalato un formato file non valido Controlla UTF-8, sintassi JSON, chiavi duplicate, versione, campi obbligatori e tipi di regola; usa come modello un file esportato dalla nuova versione.
Caricamento remoto non riuscito Controlla certificato HTTPS, collegamento diretto, rete e contenuto della risposta; non sono ammessi reindirizzamenti, accesso tramite cookie o HTTP.
Dopo l’importazione mancano regole Le regole di dominio e le due raccolte vengono sostituite ciascuna per intero; ripristina il backup precedente all’importazione oppure aggiungi al nuovo file gli elementi da conservare.
Dopo l’importazione di una regola globale vuota la pagina usa ancora un altro UA Controlla le regole di scheda esistenti o le regole di dominio corrispondenti; possono avere precedenza sulla regola globale.
Operazione riuscita ma UA errato Controlla che la regola sia attiva e il contenuto valido, che il pool casuale contenga elementi disponibili e che non vi siano regole di scheda o dominio più prioritarie; poi aggiorna la pagina.
Con molti dati l’importazione segnala un errore di archiviazione Il file e l’archiviazione sincronizzata del browser hanno limiti di dimensione; riduci regole o elenchi, riprova e controlla la configurazione esistente.
L’estensione non cambia dopo la modifica del file remoto Il caricamento remoto è un’importazione manuale una tantum; inserisci di nuovo l’indirizzo, carica e conferma.