This guide applies to UA Pro 1.5.0. It explains how to back up, migrate and write configurations by hand, and load them from a remote address. The new version uses a complete snapshot format: the configuration file’s version is 2.
Export a backup in the target browser before importing. Every import replaces the global rule, the entire set of domain rules, both UA libraries and the resource domain fallback switch with the complete snapshot in the file; it does not merge individual entries. "globalRule": null means the target browser’s global rule will be cleared.
01Export a configuration
- Click the UA Pro icon in the browser toolbar.
- Open “More” → “Import/Export Config”.
- Click “Export Config” and save the downloaded
.jsonfile. - The file name resembles
ua-switcher-config-2026-11-16.json. Its date is generated in UTC and may differ from the local date by one day.
The file contains the following persistent settings:
- The global rule and whether it is enabled or paused.
- The entire set of domain rules and whether each is enabled or paused.
- Custom UA categories and entries.
- Append-text categories and entries.
- The “Resource domain fallback” switch.
The file does not include tab rules, existing random UA selections bound to rules and tabs, currently open tabs, interface language, theme or overlay settings. These items will not be restored from the backup after import. Existing tab rules in the target browser are not cleared by an import, so they may continue to override domain or global rules.
The exported file is readable JSON in plain text. Keep the backup secure if custom UAs or categories contain information you do not want to disclose.
02Import from a local file
- In the target browser, open UA Pro → “More” → “Import/Export Config”.
- First click “Export Config” to preserve the target browser’s original configuration in case you need to restore it.
- Click “Import Config” and select the
.jsonfile. - Read the replacement warning and the rule and list counts. Click “View configuration contents” to inspect the complete JSON before confirming. Choosing “Cancel” writes nothing. After confirming, wait for the “Config imported!” message. If settings change during confirmation, the extension will ask you to repeat the operation.
- Check the global and domain rules, custom lists and resource domain fallback switch; also check whether existing tab rules override them. Refresh the pages you want to test, then verify the UA.
The extension first checks the file, then attempts to install the rules, and finally writes the persistent configuration. If installation or writing fails, it attempts to restore the rules currently saved in the browser. If it reports that restoration failed, check the actual settings. When browser sync or another window changes the configuration at the same time, this process should not be treated as a cross-device transaction.
03Load from a remote address
Remote configuration uses the same JSON content as a local backup. It is a one-time manual load and import, not an automatically updated subscription.
- First export a configuration backup, or prepare a JSON file as described below.
- Place the file on an HTTPS service accessible to the target browser and obtain a complete address that directly returns the JSON content, such as
https://example.com/ua-pro/config.json. This address is only an example; replace it with your own actual address. - In UA Pro, open “More” → “Import/Export Config”, expand “Remote Config”, paste the URL, then click “Load”.
- After loading and format validation succeed, the extension shows a confirmation dialog and the remote host name. Click “View configuration contents” to inspect the complete JSON actually downloaded. Confirming updates settings using the same rules as a local import; cancelling does not import.
- After the file changes on the server, enter the address, load it and confirm again to use the new content. The address is not automatically retained when you reopen the panel.
Only direct HTTPS links are accepted. HTTP, usernames or passwords in the address, and URL fragments are not accepted, and redirects are not followed. Requests carry no browser cookies or login credentials, send no Referer and bypass the cache; services requiring a login cookie therefore cannot be used. UA Pro does not apply this extension’s configured UA rules to this request, though other extensions or network devices may still modify it. The address may contain query parameters; protect an address containing an access token like a password. Use a trusted address and ensure the response is directly a JSON file, not a login page or an HTML page displaying code.
Local files and remote responses are each limited to 128 KiB. Remote reads time out after 10 seconds, and the content actually read is counted. Browser sync storage also has a smaller per-item quota, so a file under 128 KiB may still fail to save if the rules or an individual library are too large. If an error occurs, check that the server returns status 200 and valid JSON, the certificate is valid, the address does not redirect, and the network is reachable.
04Complete JSON example
The following example can be saved as a UTF-8 encoded config.json. Example domains and UA values are illustrative only; back up your current configuration before replacing it. JSON is case-sensitive: use double quotation marks for strings, do not add a comma after the final item, and do not write comments in 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
}
}
This example sets one built-in global UA and four domain rules. More specific subdomain rules such as app.example.com take precedence over example.com. Paused rules do not participate in active matching, so a parent-domain or global rule may take effect instead. Whether an actual site recognizes the example UA depends on the site.
05Top-level fields and replacement behavior
| Field | Example | Purpose |
|---|---|---|
version |
2 |
Required. The new version accepts only the numeric value 2. |
type |
"ua-switcher-config" |
Required. Configuration type identifier; it must match this string exactly. |
timestamp |
"2026-11-16T06:00:00.000Z" |
Required. A UTC timestamp with milliseconds and Z; for record-keeping only, not for determining when rules take effect. |
data |
{ ... } |
Required. An object containing the complete configuration, including every field in the table below. |
Fields in data |
Required format | Import behavior in this version |
|---|---|---|
globalRule |
One rule object, or null |
A rule object replaces the existing global rule; null clears it. |
domainRules |
{ "域名": 规则对象 } |
The entire object replaces the existing domain rules; {} clears them. |
userCustomData |
{ "分类": ["UA", ...] } |
The entire object replaces the existing custom UA library; {} clears it. |
userAppendData |
{ "分类": ["追加文本", ...] } |
The entire object replaces the existing append-text library; {} clears it. |
resourceDomainFallback |
true or false |
JSON Boolean: turns resource domain fallback on or off. |
All five fields are required; null cannot be used except for globalRule. Missing fields, unknown fields and duplicate JSON keys are rejected; older-version or partial configurations are not imported either. Domain rules and both libraries are replaced as whole sets: for example, a domainRules containing only one domain replaces the other existing domain rules in the target browser. We recommend editing an actual file exported by the new version and retaining every item you need.
Resource domain fallback can apply a rule based on a resource request’s destination domain only when the main page has no active tab, domain or global UA. It does not mean that all cross-domain resources override the main page rule.
06How to write rule objects
The global rule and each domain rule use the same structure:
{
"enabled": true,
"mode": "custom",
"params": {
"category": "常用",
"value": "ExampleAgent/1.0"
}
}
enabled: true means enabled; false means paused. mode determines the fields in params:
6.1 Built-in UA: builtin
{
"enabled": true,
"mode": "builtin",
"params": { "os": "Windows", "uaKey": "Edge 125 (Latest)" }
}
os and uaKey must exactly match the internal preset keys for this version of the extension; they are not necessarily the translated labels shown in the interface. The safest approach is to select the preset in the interface, export the configuration and copy the corresponding params. Check again when the preset list changes between versions.
6.2 Custom UA: custom
{
"enabled": true,
"mode": "custom",
"params": { "category": "常用", "value": "ExampleAgent/1.0" }
}
value is the complete UA string. category is used for categorization and editing in the interface; we recommend also including the value in the category of the same name in userCustomData. When the rule takes effect, it reads its own value; manually importing a rule does not automatically add the value to the custom library.
6.3 Append text: append
{
"enabled": true,
"mode": "append",
"params": { "category": "应用标记", "value": "MyApp/1.0" }
}
The extension adds a space after the current browser’s original UA, then appends value. We recommend also keeping the text in the category of the same name in userAppendData; importing the rule does not automatically populate the list.
6.4 Random UA: random
{
"enabled": true,
"mode": "random",
"params": { "pool": "custom:随机示例", "strategy": "page" }
}
strategy must be "page" (drawn on every full page load) or "tab" (retained per rule and tab). Random draws can repeat, so two identical consecutive results do not necessarily mean no new draw occurred.
Common pool values:
| Value | Random source |
|---|---|
all |
All built-in UAs, custom UAs and UAs generated from append text |
builtin |
All built-in UAs |
builtin_desktop, builtin_mobile, builtin_legacy |
Built-in desktop, mobile or legacy-device categories |
builtin_gaming, builtin_smarttv, builtin_communication, builtin_social |
The corresponding built-in category |
custom |
UAs in all custom categories |
custom:分类名 |
UAs in the category specified by userCustomData |
append_all |
UAs corresponding to all append text |
append:分类名 |
UAs corresponding to append text in the category specified by userAppendData |
The category name after the colon must match a key in the library. An enabled random rule must have available candidates, or the file will be rejected.
07Checks when editing by hand
- Use domain names as keys in
domainRules, for exampleexample.comorshop.example.com; do not includehttps://, paths, ports or spaces. Domain rules also match subdomains. In this version,*.example.comalso includesexample.comitself; it does not mean “subdomains only”. - Category names may contain Chinese and must be non-empty strings without control characters or dangerous bidirectional text controls;
__proto__,prototypeandconstructorcannot be category names. We recommend using printable ASCII characters for UAs and append text. Do not include newlines, tabs or other control characters. Each UA can be at most 4096 characters. Escape double quotation marks and backslashes in text according to JSON rules. - Each category maps to an array of strings, for example
"常用": ["Agent/1.0", "Agent/2.0"]. Keep the square brackets even for a single item. An empty category can be written as[]. - Do not put double quotation marks around
true,falseornull;"false"is a string, not a Boolean. - The file must be valid UTF-8 and JSON, with no duplicate keys. The extension also checks the structure, field types, rules, preset names and random pools; correct syntax does not guarantee that a rule is usable.
A configuration file can change the UA your browser sends to websites. HTTPS protects the transfer but does not guarantee that the server’s configuration matches your intentions. Import only files from trusted sources, inspect their contents before confirming and verify the actual effect after refreshing the target page.
08Troubleshooting
| Symptom | What to check |
|---|---|
| File format reported as invalid | Check UTF-8, JSON syntax, duplicate keys, version, required fields and rule types. Use a file exported by the new version as a template. |
| Remote load fails | Check the HTTPS certificate, direct link, network and response content. Redirects, cookie login and HTTP are not allowed. |
| Rules are missing after import | Domain rules and both libraries are replaced as whole sets. Restore from the pre-import backup, or add all items you want to keep to the new file. |
| An empty global rule was imported, but the page still uses another UA | Check for existing tab rules or matching domain rules; they may take precedence over the global rule. |
| Import succeeds but the UA is wrong | Check that the rule is enabled, its content is valid, the random pool has available entries, and no higher-priority tab or domain rule applies; then refresh the page. |
| Storage error when importing a large amount of data | Both the file and browser sync storage have size limits. Reduce the rules or lists and retry, then check the existing configuration. |
| The extension does not change after the remote file is modified | Remote loading is a one-time manual import. Enter the address again, load it and confirm. |