UA Pro: Konfigurationsanleitung

Konfiguration importieren, exportieren und remote laden

Konfigurationen sichern, übertragen und manuell erstellen sowie von einer Remote-Adresse laden.

Für UA Pro 1.5.0

Diese Anleitung gilt für UA Pro 1.5.0. Sie beschreibt das Sichern, Übertragen und manuelle Erstellen von Konfigurationen sowie das Laden von einer Remote-Adresse. Die neue Version verwendet vollständige Snapshots; version der Konfigurationsdatei ist 2.

Exportieren Sie vor dem Import eine Sicherung im Zielbrowser. Jeder Import ersetzt die globale Regel, den gesamten Satz von Domänenregeln, beide UA-Bibliotheken und den Schalter für den Rückfall auf Ressourcendomänen durch den vollständigen Snapshot aus der Datei. Es erfolgt keine Zusammenführung einzelner Einträge. "globalRule": null löscht die globale Regel im Zielbrowser.

01Konfiguration exportieren

  1. Klicken Sie in der Browser-Symbolleiste auf das UA-Pro-Symbol.
  2. Öffnen Sie „Mehr“ → „Konfiguration importieren/exportieren“.
  3. Klicken Sie auf „Konfiguration exportieren“ und speichern Sie die heruntergeladene .json-Datei.
  4. Der Dateiname sieht beispielsweise so aus: ua-switcher-config-2026-11-16.json. Das Datum im Dateinamen wird nach UTC erzeugt und kann um einen Tag vom lokalen Datum abweichen.

Die Datei enthält folgende dauerhaft gespeicherte Konfiguration:

  • Die globale Regel und ihren aktivierten oder pausierten Zustand.
  • Den gesamten Satz von Domänenregeln und deren aktivierten oder pausierten Zustand.
  • Benutzerdefinierte UA-Kategorien und -Einträge.
  • Kategorien und Einträge für angehängten Text.
  • Den Schalter „Rückfall auf Ressourcendomäne“.

Die Datei enthält keine Tab-Regeln, bereits gezogene zufällige UA-Bindungen, aktuell geöffnete Tabs, Oberflächensprache, Design oder Overlay-Einstellungen. Diese Elemente werden beim Import nicht aus der Sicherung wiederhergestellt. Bereits vorhandene Tab-Regeln im Zielbrowser werden durch den Import auch nicht gelöscht und können daher weiterhin Domänen- oder globale Regeln übersteuern.

Die exportierte Datei ist lesbarer JSON-Klartext. Bewahren Sie die Sicherung sicher auf, falls benutzerdefinierte UAs oder Kategorien Informationen enthalten, die Sie nicht veröffentlichen möchten.

02Aus lokaler Datei importieren

  1. Öffnen Sie im Zielbrowser UA Pro → „Mehr“ → „Konfiguration importieren/exportieren“.
  2. Klicken Sie zunächst auf „Konfiguration exportieren“, um die ursprüngliche Konfiguration des Zielbrowsers bei Bedarf wiederherstellen zu können.
  3. Klicken Sie auf „Konfiguration importieren“ und wählen Sie die .json-Datei aus.
  4. Lesen Sie den Überschreibhinweis und die Anzahl der Regeln und Listeneinträge. Mit „Konfigurationsinhalt anzeigen“ können Sie vor der Bestätigung das vollständige JSON prüfen. „Abbrechen“ schreibt keine Daten. Warten Sie nach der Bestätigung auf „Konfiguration importiert!“. Ändern sich die Einstellungen während der Bestätigung, verlangt die Erweiterung eine erneute Durchführung.
  5. Prüfen Sie globale und Domänenregeln, benutzerdefinierte Listen und den Schalter für den Rückfall auf Ressourcendomänen. Prüfen Sie auch, ob vorhandene Tab-Regeln diese übersteuern. Laden Sie die zu testende Webseite neu und prüfen Sie den UA.

Die Erweiterung prüft zuerst die Datei, versucht dann die Regeln zu installieren und schreibt zuletzt die dauerhafte Konfiguration. Scheitert die Installation oder das Schreiben, versucht sie die aktuell im Browser gespeicherten Regeln wiederherzustellen. Wird gemeldet, dass dies nicht möglich ist, prüfen Sie die tatsächlichen Einstellungen. Bei gleichzeitigen Änderungen durch Browsersynchronisierung oder andere Fenster ist dieser Vorgang nicht als geräteübergreifende Transaktion zu verstehen.

03Von einer Remote-Adresse laden

Die Remote-Konfiguration verwendet denselben JSON-Inhalt wie eine lokale Sicherung. Sie wird einmalig manuell geladen und importiert; es handelt sich nicht um ein automatisch aktualisiertes Abonnement.

  1. Exportieren Sie zuerst eine Konfigurationssicherung oder erstellen Sie eine JSON-Datei wie unten beschrieben.
  2. Legen Sie die Datei auf einem HTTPS-Dienst ab, den der Zielbrowser erreichen kann, und ermitteln Sie die vollständige Adresse, die den JSON-Inhalt direkt zurückgibt, z. B. https://example.com/ua-pro/config.json. Diese Adresse ist nur ein Beispiel; ersetzen Sie sie durch Ihre eigene.
  3. Öffnen Sie in UA Pro „Mehr“ → „Konfiguration importieren/exportieren“, klappen Sie „Remote-Konfiguration“ auf, fügen Sie die Adresse ein und klicken Sie auf „Laden“.
  4. Nach erfolgreichem Laden und Prüfen des Formats zeigt die Erweiterung einen Bestätigungsdialog mit dem Remote-Hostnamen. Mit „Konfigurationsinhalt anzeigen“ prüfen Sie das tatsächlich heruntergeladene vollständige JSON. Die Bestätigung aktualisiert die Einstellungen nach denselben Regeln wie beim lokalen Import; beim Abbrechen erfolgt kein Import.
  5. Wenn sich die Datei auf dem Server ändert, müssen Sie die Adresse erneut eingeben, laden und bestätigen, um den neuen Inhalt zu verwenden. Beim erneuten Öffnen des Panels bleibt die Adresse nicht automatisch erhalten.

Nur direkte HTTPS-Links werden akzeptiert; HTTP, Benutzernamen oder Passwörter in der Adresse und URL-Fragmente sind nicht zulässig. Weiterleitungen werden nicht verfolgt. Die Anfrage enthält weder Browser-Cookies noch Anmeldedaten, sendet keinen Referer und umgeht den Cache. Dienste, die ein Anmelde-Cookie benötigen, sind daher ungeeignet. UA Pro wendet die in dieser Erweiterung konfigurierten UA-Regeln nicht auf diese Anfrage an; andere Erweiterungen oder Netzwerkgeräte können sie dennoch verändern. Die Adresse darf Abfrageparameter enthalten; behandeln Sie Adressen mit Zugriffstoken wie Passwörter. Verwenden Sie eine vertrauenswürdige Adresse und stellen Sie sicher, dass die Antwort direkt eine JSON-Datei ist, keine Anmeldeseite oder HTML-Seite mit angezeigtem Code.

Lokale Dateien und Remote-Antworten sind jeweils auf 128 KiB begrenzt. Für das Remote-Lesen gelten 10 Sekunden; gezählt wird der tatsächlich gelesene Inhalt. Der Synchronisierungsspeicher des Browsers hat zudem eine kleinere Quote pro Eintrag: Auch eine Datei unter 128 KiB kann sich nicht speichern lassen, wenn Regeln oder eine einzelne Bibliothek zu groß sind. Prüfen Sie bei Fehlern, ob der Server Status 200 und gültiges JSON zurückgibt, das Zertifikat gültig ist, die Adresse weiterleitet und das Netzwerk erreichbar ist.

04Vollständiges JSON-Beispiel

Das folgende Beispiel kann als UTF-8-kodierte Datei config.json gespeichert werden. Beispieldomänen und UA-Werte dienen nur zur Veranschaulichung; sichern Sie Ihre bestehende Konfiguration vor dem Ersetzen. JSON unterscheidet Groß- und Kleinschreibung. Verwenden Sie für Zeichenfolgen gerade doppelte Anführungszeichen, setzen Sie nach dem letzten Element kein Komma und schreiben Sie keine Kommentare in 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
  }
}

Dieses Beispiel legt einen integrierten globalen UA und vier Domänenregeln fest. Spezifischere Subdomänenregeln wie app.example.com haben Vorrang vor example.com. Pausierte Regeln nehmen nicht an der aktiven Zuordnung teil; stattdessen kann eine Regel der übergeordneten Domäne oder die globale Regel greifen. Ob eine reale Website den Beispiel-UA erkennt, hängt von der Website ab.

05Felder der obersten Ebene und Überschreibverhalten

Feld Beispiel Zweck
version 2 Erforderlich. Die neue Version akzeptiert nur den Zahlenwert 2.
type "ua-switcher-config" Erforderlich. Kennung des Konfigurationstyps; muss genau dieser Zeichenfolge entsprechen.
timestamp "2026-11-16T06:00:00.000Z" Erforderlich. UTC-Zeit mit Millisekunden und Z; dient nur der Aufzeichnung und bestimmt nicht den Zeitpunkt des Wirksamwerdens der Regeln.
data { ... } Erforderlich. Objekt mit der vollständigen Konfiguration und allen Feldern der folgenden Tabelle.
Felder in data Gültiges Format Verhalten beim Import in dieser Version
globalRule Ein Regelobjekt oder null Das Regelobjekt ersetzt die vorhandene globale Regel; null löscht sie.
domainRules { "域名": 规则对象 } Das gesamte Objekt ersetzt die bisherigen Domänenregeln; {} leert sie.
userCustomData { "分类": ["UA", ...] } Das gesamte Objekt ersetzt die bisherige benutzerdefinierte UA-Bibliothek; {} leert sie.
userAppendData { "分类": ["追加文本", ...] } Das gesamte Objekt ersetzt die bisherige Bibliothek für angehängten Text; {} leert sie.
resourceDomainFallback true oder false JSON-Boolescher Wert: schaltet den Rückfall auf Ressourcendomänen ein oder aus.

Alle fünf Felder sind erforderlich; außer bei globalRule ist null nicht zulässig. Fehlende oder unbekannte Felder und doppelte JSON-Schlüssel werden abgelehnt; ältere Versionen oder Teilkonfigurationen werden ebenfalls nicht importiert. Domänenregeln und beide Bibliotheken werden jeweils vollständig ersetzt: Enthält domainRules beispielsweise nur eine Domäne, ersetzt dies die anderen vorhandenen Domänenregeln im Zielbrowser. Bearbeiten Sie vorzugsweise eine tatsächlich aus der neuen Version exportierte Datei und erhalten Sie alle benötigten Einträge vollständig.

Der Rückfall auf Ressourcendomänen kann nur dann Regeln anhand der Zieldomäne einer Ressourcenanfrage anwenden, wenn die Hauptseite keinen wirksamen Tab-, Domänen- oder globalen UA hat. Dies bedeutet nicht, dass alle domänenübergreifenden Ressourcen die Regel der Hauptseite übersteuern.

06Regelobjekte erstellen

Die globale Regel und jede Domänenregel verwenden dieselbe Struktur:

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

enabled: true bedeutet aktiviert, false pausiert. mode bestimmt die Felder von params:

6.1 Integrierter UA: builtin

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

os und uaKey müssen exakt den internen voreingestellten Schlüsseln dieser Erweiterungsversion entsprechen; sie müssen nicht mit den übersetzten Anzeigetexten übereinstimmen. Am sichersten wählen Sie die Voreinstellung in der Oberfläche, exportieren die Konfiguration und kopieren die zugehörigen params. Prüfen Sie dies erneut, wenn sich die Liste der Voreinstellungen zwischen Versionen ändert.

6.2 Benutzerdefinierter UA: custom

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

value ist die vollständige UA-Zeichenfolge. category dient der Kategorisierung und Bearbeitung in der Oberfläche. Es wird empfohlen, diesen Wert auch in der gleichnamigen Kategorie von userCustomData zu führen. Für die aktive Regel wird deren eigener Wert value gelesen; ein manueller Regelimport fügt ihn nicht automatisch der benutzerdefinierten Bibliothek hinzu.

6.3 Angehängter Text: append

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

Die Erweiterung fügt nach dem ursprünglichen UA des aktuellen Browsers ein Leerzeichen und anschließend value an. Es wird empfohlen, diesen Text auch in der gleichnamigen Kategorie von userAppendData zu führen; der Import der Regel füllt die Liste nicht automatisch.

6.4 Zufälliger UA: random

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

strategy muss "page" (Auswahl bei jedem vollständigen Laden einer Seite) oder "tab" (Bindung je Regel und Tab) sein. Zufällige Auswahlen dürfen sich wiederholen; zwei gleiche Ergebnisse hintereinander bedeuten nicht zwingend, dass keine neue Auswahl stattfand.

Häufige Werte für pool:

Wert Quelle der Zufallsauswahl
all Alle integrierten und benutzerdefinierten UAs sowie aus angehängtem Text erzeugte UAs
builtin Alle integrierten UAs
builtin_desktop, builtin_mobile, builtin_legacy Integrierte Kategorien für Desktop-, Mobil- oder ältere Geräte
builtin_gaming, builtin_smarttv, builtin_communication, builtin_social Die entsprechenden integrierten Kategorien
custom UAs aus allen benutzerdefinierten Kategorien
custom:分类名 UAs der in userCustomData angegebenen Kategorie
append_all UAs zu allen angehängten Texten
append:分类名 UAs zu den angehängten Texten der in userAppendData angegebenen Kategorie

Der Kategoriename nach dem Doppelpunkt muss mit dem Schlüssel in der Bibliothek übereinstimmen. Eine aktivierte Zufallsregel muss verfügbare Kandidaten haben, sonst wird die Datei abgelehnt.

07Prüfung bei manueller Bearbeitung

  • Verwenden Sie als Schlüssel von domainRules Domänennamen wie example.com oder shop.example.com, ohne https://, Pfad, Port oder Leerzeichen. Domänenregeln erfassen auch untergeordnete Subdomänen; *.example.com umfasst in dieser Version ebenfalls example.com selbst und nicht nur Subdomänen.
  • Kategorienamen dürfen chinesische Zeichen enthalten und müssen nichtleere Zeichenfolgen ohne Steuerzeichen oder gefährliche bidirektionale Textsteuerzeichen sein. __proto__, prototype und constructor sind als Kategorienamen nicht zulässig. Für UAs und angehängten Text werden druckbare ASCII-Zeichen empfohlen; verwenden Sie keine Zeilenumbrüche, Tabulatoren oder andere Steuerzeichen. Ein einzelner UA darf höchstens 4096 Zeichen enthalten. Gerade doppelte Anführungszeichen und umgekehrte Schrägstriche im Text müssen nach JSON-Regeln maskiert werden.
  • Jede Kategorie entspricht einem Array von Zeichenfolgen, z. B. "常用": ["Agent/1.0", "Agent/2.0"]. Behalten Sie die eckigen Klammern auch bei nur einem Eintrag bei. Eine leere Kategorie kann als [] angegeben werden.
  • true, false und null dürfen nicht in doppelte Anführungszeichen gesetzt werden; "false" ist eine Zeichenfolge, kein boolescher Wert.
  • Die Datei muss gültiges UTF-8 und JSON enthalten; doppelte Schlüssel sind unzulässig. Die Erweiterung prüft auch Struktur, Feldtypen, Regeln, Namen der Voreinstellungen und Zufallspools. Korrekte Syntax allein garantiert nicht, dass eine Regel verwendbar ist.

Eine Konfigurationsdatei kann den UA ändern, den der Browser an Websites sendet. HTTPS schützt die Übertragung, garantiert aber nicht, dass die vom Server bereitgestellte Konfiguration Ihren Absichten entspricht. Importieren Sie nur Dateien aus vertrauenswürdigen Quellen, prüfen Sie den Inhalt vor der Bestätigung und kontrollieren Sie die tatsächliche Wirkung nach dem Neuladen der Zielseite.

08Häufige Fragen

Problem Prüfung
Ungültiges Dateiformat wird gemeldet Prüfen Sie UTF-8, JSON-Syntax, doppelte Schlüssel, Version, Pflichtfelder und Regeltypen; verwenden Sie eine aus der neuen Version exportierte Datei als Vorlage.
Remote-Laden schlägt fehl Prüfen Sie HTTPS-Zertifikat, direkten Link, Netzwerk und Antwortinhalt. Weiterleitungen, Cookie-Anmeldung und HTTP sind nicht zulässig.
Nach dem Import fehlen Regeln Domänenregeln und beide Bibliotheken werden jeweils vollständig ersetzt. Stellen Sie die Sicherung vor dem Import wieder her oder ergänzen Sie in der neuen Datei die zu erhaltenden Einträge.
Nach Import einer leeren globalen Regel verwendet die Webseite weiterhin einen anderen UA Prüfen Sie vorhandene Tab-Regeln oder passende Domänenregeln; sie können Vorrang vor der globalen Regel haben.
Erfolg wird angezeigt, aber der UA ist falsch Prüfen Sie, ob die Regel aktiviert und ihr Inhalt gültig ist, ob der Zufallspool verfügbare Einträge hat und ob Tab- oder Domänenregeln mit höherer Priorität bestehen. Laden Sie dann die Seite neu.
Bei vielen Daten meldet der Import einen Speicherfehler Datei und Browser-Synchronisierungsspeicher haben Größenbegrenzungen. Reduzieren Sie Regeln oder Listen, versuchen Sie es erneut und prüfen Sie die bestehende Konfiguration.
Nach Änderung der Remote-Datei ändert sich die Erweiterung nicht Das Remote-Laden ist ein einmaliger manueller Import. Geben Sie die Adresse erneut ein, laden und bestätigen Sie.