Guide de configuration UA Pro

Importer, exporter et charger une configuration distante

Sauvegarder, transférer et rédiger une configuration manuellement, ou la charger depuis une adresse distante.

Version concernée : UA Pro 1.5.0

Ce guide concerne UA Pro 1.5.0. Il explique comment sauvegarder, transférer et rédiger manuellement une configuration, ainsi que la charger depuis une adresse distante. La nouvelle version utilise un instantané complet : le champ version du fichier de configuration vaut 2.

Avant l’importation, exportez une sauvegarde dans le navigateur cible. Chaque importation remplace la règle globale, l’ensemble des règles de domaine, les deux bibliothèques d’UA et le commutateur de repli sur le domaine de la ressource par l’instantané complet du fichier, sans fusion élément par élément. "globalRule": null supprime la règle globale du navigateur cible.

01Exporter la configuration

  1. Cliquez sur l’icône UA Pro dans la barre d’outils du navigateur.
  2. Ouvrez « Plus » → « Importer ou exporter la configuration ».
  3. Cliquez sur « Exporter la configuration » et enregistrez le fichier .json téléchargé.
  4. Le nom du fichier ressemble à ua-switcher-config-2026-11-16.json. La date du nom est générée en UTC et peut différer d’un jour de la date locale.

Le fichier contient la configuration persistante suivante :

  • La règle globale et son état actif ou suspendu.
  • L’ensemble des règles de domaine et leur état actif ou suspendu.
  • Les catégories et éléments d’UA personnalisés.
  • Les catégories et éléments de texte ajouté.
  • Le commutateur « Repli sur le domaine de la ressource ».

Le fichier ne contient pas les règles d’onglet, les associations d’UA aléatoires déjà tirés, les onglets ouverts, la langue de l’interface, le thème ni les paramètres de la fenêtre flottante. Ces éléments ne seront pas restaurés depuis la sauvegarde lors de l’importation. Les règles d’onglet déjà présentes dans le navigateur cible ne sont pas non plus supprimées par l’importation et peuvent donc continuer à primer sur les règles de domaine ou la règle globale.

Le fichier exporté est du JSON en texte clair lisible. Si des UA ou catégories personnalisés contiennent des informations que vous ne souhaitez pas divulguer, conservez la sauvegarde en lieu sûr.

02Importer depuis un fichier local

  1. Dans le navigateur cible, ouvrez UA Pro → « Plus » → « Importer ou exporter la configuration ».
  2. Cliquez d’abord sur « Exporter la configuration » pour conserver la configuration initiale du navigateur cible et pouvoir la restaurer au besoin.
  3. Cliquez sur « Importer la configuration » et sélectionnez le fichier .json.
  4. Lisez l’avertissement de remplacement et les nombres de règles et d’éléments des listes. Cliquez sur « Afficher le contenu de la configuration » pour examiner le JSON complet avant confirmation. « Annuler » n’écrit aucune donnée. Après confirmation, attendez le message « Configuration importée ! ». Si les paramètres changent pendant la confirmation, l’extension demandera de recommencer.
  5. Vérifiez les règles globales et de domaine, les listes personnalisées et le commutateur de repli sur le domaine de la ressource ; vérifiez aussi si des règles d’onglet existantes priment sur eux. Actualisez la page à tester puis vérifiez l’UA.

L’extension vérifie d’abord le fichier, tente ensuite d’installer les règles, puis écrit la configuration persistante. Si l’installation ou l’écriture échoue, elle tente de restaurer les règles actuellement enregistrées dans le navigateur ; si elle indique que la restauration est impossible, vérifiez les paramètres effectifs. En cas de modification simultanée par la synchronisation du navigateur ou une autre fenêtre, ce processus ne doit pas être considéré comme une transaction entre appareils.

03Charger depuis une adresse distante

La configuration distante utilise le même contenu JSON qu’une sauvegarde locale. Son chargement et son importation sont manuels et ponctuels ; ce n’est pas un abonnement à mise à jour automatique.

  1. Exportez d’abord une sauvegarde de la configuration ou préparez un fichier JSON comme indiqué ci-dessous.
  2. Placez le fichier sur un service HTTPS accessible au navigateur cible et obtenez l’adresse complète qui renvoie directement le contenu JSON, par exemple https://example.com/ua-pro/config.json. Cette adresse n’est qu’un exemple : remplacez-la par votre adresse réelle.
  3. Dans UA Pro, ouvrez « Plus » → « Importer ou exporter la configuration », développez « Configuration distante », collez l’adresse, puis cliquez sur « Charger ».
  4. Après chargement et validation du format, l’extension affiche une boîte de confirmation et le nom d’hôte distant. Cliquez sur « Afficher le contenu de la configuration » pour examiner le JSON complet réellement téléchargé. La confirmation met à jour les paramètres selon les mêmes règles qu’une importation locale ; l’annulation n’importe rien.
  5. Si le fichier sur le serveur change et que vous voulez utiliser son nouveau contenu, saisissez à nouveau l’adresse, chargez-la et confirmez. L’adresse n’est pas conservée automatiquement à la réouverture du panneau.

Seuls les liens HTTPS directs sont acceptés : HTTP, les noms d’utilisateur ou mots de passe dans l’adresse et les fragments d’URL sont interdits ; les redirections ne sont pas suivies. La requête ne contient ni cookies du navigateur ni identifiants de connexion, n’envoie pas de Referer et contourne le cache. Un service nécessitant un cookie de connexion ne convient donc pas. UA Pro n’applique pas à cette requête les règles d’UA configurées dans cette extension, mais d’autres extensions ou équipements réseau peuvent encore la modifier. L’adresse peut contenir des paramètres de requête ; protégez celles qui contiennent un jeton d’accès comme un mot de passe. Utilisez une adresse fiable et assurez-vous que la réponse est directement un fichier JSON, et non une page de connexion ou une page HTML affichant du code.

Les fichiers locaux et les réponses distantes sont chacun limités à 128 KiB. La lecture distante est limitée à 10 secondes et le contenu effectivement lu est comptabilisé. Le stockage synchronisé du navigateur impose aussi un quota plus faible par élément : même sous 128 KiB, un fichier peut ne pas être enregistré si les règles ou une bibliothèque sont trop volumineuses. En cas d’erreur, vérifiez que le serveur renvoie le statut 200 et un JSON valide, que le certificat est valide, que l’adresse ne redirige pas et que le réseau est accessible.

04Exemple JSON complet

L’exemple suivant peut être enregistré dans un fichier config.json encodé en UTF-8. Les domaines et valeurs d’UA sont donnés à titre d’exemple ; sauvegardez d’abord votre configuration existante avant de la remplacer. JSON distingue les majuscules des minuscules : utilisez des guillemets doubles droits pour les chaînes, ne mettez pas de virgule après le dernier élément et n’écrivez pas de commentaires dans le 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
  }
}

Cet exemple définit un UA global intégré et quatre règles de domaine. Les règles de sous-domaine plus précises, comme app.example.com, priment sur example.com. Les règles suspendues ne participent pas à la sélection des règles actives ; une règle du domaine parent ou la règle globale peut alors s’appliquer. La reconnaissance de l’UA d’exemple dépend du site réel.

05Champs de premier niveau et remplacement

Champ Exemple Rôle
version 2 Obligatoire. La nouvelle version n’accepte que la valeur numérique 2.
type "ua-switcher-config" Obligatoire. Identifiant du type de configuration ; doit correspondre exactement à cette chaîne.
timestamp "2026-11-16T06:00:00.000Z" Obligatoire. Heure UTC avec millisecondes et Z ; sert uniquement à l’enregistrement et ne détermine pas la prise d’effet des règles.
data { ... } Obligatoire. Objet contenant la configuration complète et tous les champs du tableau suivant.
Champs de data Format correct Comportement à l’importation dans cette version
globalRule Un objet de règle ou null L’objet de règle remplace la règle globale existante ; null la supprime.
domainRules { "域名": 规则对象 } L’objet entier remplace les règles de domaine précédentes ; {} les vide.
userCustomData { "分类": ["UA", ...] } L’objet entier remplace la bibliothèque d’UA personnalisés précédente ; {} la vide.
userAppendData { "分类": ["追加文本", ...] } L’objet entier remplace la bibliothèque de texte ajouté précédente ; {} la vide.
resourceDomainFallback true ou false Booléen JSON : active ou désactive le repli sur le domaine de la ressource.

Les cinq champs sont obligatoires ; null n’est autorisé que pour globalRule. Les champs manquants ou inconnus et les clés JSON dupliquées sont rejetés ; les anciennes versions et les configurations partielles ne sont pas importées non plus. Les règles de domaine et les deux bibliothèques sont remplacées chacune en bloc : par exemple, un domainRules ne contenant qu’un domaine remplace les autres règles de domaine existantes du navigateur cible. Il est conseillé de modifier un fichier réellement exporté par la nouvelle version et de conserver intégralement les éléments nécessaires.

Le repli sur le domaine de la ressource ne peut appliquer une règle selon le domaine cible d’une requête de ressource que si la page principale n’a aucun UA effectif d’onglet, de domaine ou global. Cela ne signifie pas que toutes les ressources interdomaines remplacent la règle de la page principale.

06Rédiger un objet de règle

La règle globale et chaque règle de domaine utilisent la même structure :

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

enabled: true signifie actif et false suspendu. mode détermine les champs de params :

6.1 UA intégré : builtin

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

os et uaKey doivent correspondre exactement aux clés prédéfinies en interne dans cette version de l’extension ; elles ne correspondent pas forcément aux libellés traduits de l’interface. Le plus sûr est de choisir le préréglage dans l’interface, d’exporter la configuration puis de copier les params correspondants. Revérifiez si la liste des préréglages change selon la version.

6.2 UA personnalisé : custom

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

value est la chaîne UA complète. category sert au classement et à la modification dans l’interface ; il est conseillé d’inclure aussi cette valeur dans la catégorie du même nom de userCustomData. La règle active lit son propre value ; l’importation manuelle d’une règle n’ajoute pas automatiquement cette valeur à la bibliothèque personnalisée.

6.3 Texte ajouté : append

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

L’extension ajoute une espace après l’UA d’origine du navigateur actuel, puis ajoute value. Il est conseillé de conserver aussi ce texte dans la catégorie du même nom de userAppendData ; l’importation d’une règle ne remplit pas automatiquement la liste.

6.4 UA aléatoire : random

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

strategy doit valoir "page" (tirage à chaque chargement complet d’une page) ou "tab" (maintien par règle et par onglet). Les tirages peuvent se répéter : deux résultats identiques de suite ne signifient pas nécessairement qu’il n’y a pas eu de nouveau tirage.

Valeurs courantes de pool :

Valeur Source du tirage
all Tous les UA intégrés et personnalisés, ainsi que les UA générés à partir des textes ajoutés
builtin Tous les UA intégrés
builtin_desktop, builtin_mobile, builtin_legacy Catégories intégrées pour ordinateurs, appareils mobiles ou anciens appareils
builtin_gaming, builtin_smarttv, builtin_communication, builtin_social Catégories intégrées correspondantes
custom UA de toutes les catégories personnalisées
custom:分类名 UA de la catégorie indiquée dans userCustomData
append_all UA correspondant à tous les textes ajoutés
append:分类名 UA correspondant aux textes ajoutés de la catégorie indiquée dans userAppendData

Le nom de catégorie après les deux-points doit correspondre à la clé de la bibliothèque. Une règle aléatoire active doit disposer de candidats utilisables, sinon le fichier est rejeté.

07Vérifications lors de la modification manuelle

  • Les clés de domainRules doivent être des noms de domaine, par exemple example.com ou shop.example.com, sans https://, chemin, port ni espace. Les règles de domaine correspondent aussi aux sous-domaines ; dans cette version, *.example.com inclut également example.com lui-même et ne signifie pas « sous-domaines uniquement ».
  • Les noms de catégorie peuvent être en chinois ; ils doivent être des chaînes non vides, sans caractères de contrôle ni caractères de contrôle de texte bidirectionnel dangereux. __proto__, prototype et constructor ne peuvent pas servir de noms de catégorie. Pour les UA et les textes ajoutés, il est recommandé d’utiliser des caractères ASCII imprimables ; n’utilisez pas de sauts de ligne, de tabulations ni d’autres caractères de contrôle. Un UA est limité à 4096 caractères. Les guillemets doubles droits et les barres obliques inverses dans le texte doivent être échappés selon les règles JSON.
  • Chaque catégorie correspond à un tableau de chaînes, par exemple "常用": ["Agent/1.0", "Agent/2.0"]. Conservez les crochets même pour un seul élément. Une catégorie vide peut s’écrire [].
  • Ne mettez pas true, false et null entre guillemets doubles ; "false" est une chaîne, pas un booléen.
  • Le fichier doit être en UTF-8 valide et contenir du JSON valide, sans clés dupliquées. L’extension vérifie aussi la structure, les types des champs, les règles, les noms des préréglages et les pools aléatoires. Une syntaxe correcte ne garantit pas qu’une règle soit utilisable.

Un fichier de configuration peut modifier l’UA envoyé par le navigateur aux sites. HTTPS protège le transport, mais ne garantit pas que la configuration fournie par le serveur corresponde à vos souhaits. N’importez que des fichiers de sources fiables, examinez leur contenu avant confirmation et vérifiez l’effet réel après actualisation de la page cible.

08Questions fréquentes

Symptôme Vérifications
Le format du fichier est signalé comme incorrect Vérifiez UTF-8, la syntaxe JSON, les clés dupliquées, la version, les champs obligatoires et les types de règles ; utilisez comme modèle un fichier exporté par la nouvelle version.
Échec du chargement distant Vérifiez le certificat HTTPS, le lien direct, le réseau et le contenu de la réponse ; les redirections, la connexion par cookie et HTTP ne sont pas autorisés.
Des règles manquent après l’importation Les règles de domaine et les deux bibliothèques sont remplacées chacune en bloc. Restaurez la sauvegarde faite avant l’importation ou ajoutez au nouveau fichier les éléments à conserver.
Après importation d’une règle globale vide, la page utilise toujours un autre UA Vérifiez les règles d’onglet existantes ou les règles de domaine correspondantes ; elles peuvent primer sur la règle globale.
L’opération réussit mais l’UA est incorrect Vérifiez que la règle est active et son contenu valide, que le pool aléatoire contient des éléments utilisables et qu’aucune règle d’onglet ou de domaine prioritaire ne s’applique, puis actualisez la page.
Une erreur de stockage apparaît à l’importation avec beaucoup de données Le fichier et le stockage synchronisé du navigateur ont des limites de taille. Réduisez les règles ou les listes, réessayez et vérifiez la configuration existante.
L’extension ne change pas après modification du fichier distant Le chargement distant est une importation manuelle ponctuelle ; saisissez à nouveau l’adresse, chargez-la et confirmez.