UA PRO USER GUIDE

Getting started guide

Start from your first rule and learn about scope, random modes, resource fallback and configuration migration.

Applies to version: 1.4.5 · Guide updated: November 16, 2026

This guide covers version 1.4.5. Check the version available from your chosen installation source.

UA Pro lets you set the User-Agent (UA) for all websites, specific domains or a single tab. First choose which pages a rule affects, then choose how the UA is generated. When several rules exist, the extension selects one main-page rule by priority; ordinary in-page resources inherit the main page's UA first.

01Understanding UA and page resources

A UA is a description of identity that the browser sends to websites, usually covering the browser, operating system and device. UA Pro can modify the User-Agent of ordinary web requests and provide the matching value for navigator.userAgent on ordinary pages.

Choosing a mobile UA lets you observe what a website returns for mobile UAs, but it does not turn a computer into a phone, and it does not automatically change screen size, browser engine, IP or the full browser fingerprint.

Suppose the address bar shows https://shop.example.com/product:

Term Meaning in this example
Main page The product page opened in the address bar
Main-page domain shop.example.com, without protocol or path
Parent domain Relative to shop.example.com, example.com is a parent domain
Subdomain img.shop.example.com is a subdomain below shop.example.com
In-page resources Images, scripts, styles, API requests, ordinary network iframes and so on loaded by the page
Resource domain The destination domain of a resource request, such as cdn.example.net

In this guide, "main-page domain" means the hostname of the page in the address bar. It is not a top-level domain such as .com, and it is not necessarily a registered domain such as example.com.

02Three independent settings concepts

Setting Question it answers Examples
Scope Which pages use this rule? Global, the example.com domain, the current tab
UA mode Where does the UA content come from? Built-in UA, Custom, Append text, Random UA
Random mode When random is selected, when is a new value drawn? Every page load, Per tab

For example, "domain scope + Random UA + Per tab" means that each tab visiting pages within that domain scope stores its own random result for the rule. It does not mean that all tabs visiting the domain share one permanent UA.

2.1 Scope

Scope What it affects Lifetime and override relationship
Global Ordinary website pages with no higher-priority rule Configuration is kept; can be overridden by domain or tab rules
Domain Pages whose main-page domain matches the specified domain or one of its subdomains Configuration is kept; can be overridden by more specific domain rules or tab rules
Tab The tab in which the rule was created Highest priority; still applies when that tab navigates to other websites, and stops when the tab is closed

"Global scope + Per tab random" is still a global rule; saving random results separately does not turn it into a top-priority tab rule.

2.2 UA mode

Mode How the UA is generated Suitable for
Built-in UA Picks a UA from preset browsers or devices Quickly using a preset identity
Custom Uses the full UA string you enter Using a specific UA, or saving your own UA list
Append text Adds a space and the specified text after the browser's default UA Attaching an identifying marker to the default UA
Random UA Draws a UA from the selected candidate pool Assigning random values per page load or per tab

Append text is based on the browser's default UA, not on an overridden parent-domain UA or global UA. For example, if the global rule is a Custom UA and a domain rule appends MyTest, that domain ends up using "browser default UA + space + MyTest". The two rules do not stack.

The random candidate pool can come from built-in UAs, a custom list, an append-text list, or a combination of these sources; you can also pick specific categories. Append-text candidates are first combined with the browser's default UA and then enter the draw. If the pool is empty or has no valid content, the rule cannot become a valid main-page rule.

03Main-page rule priority

Tab rule → most specific valid domain rule → parent-domain rules, level by level → global rule → browser default UA.

The first enabled rule that can produce a valid UA, in this order, is used, and later rules are not combined with it. There is no extra priority between fixed modes and random modes.

Check order Example when the main page is news.shop.example.com
1 Current tab rule
2 Valid rule for news.shop.example.com
3 Valid rule for shop.example.com
4 Valid rule for example.com
5 Valid global rule
6 None of the above is valid; use the browser default UA

"Valid" has two conditions: the rule is enabled, and it can produce a legal, non-empty UA. Paused rules, illegal UAs and empty random candidate pools are skipped.

3.1 How domains match

When you set example.com, the following main pages match:

Main-page domain Match?
example.com Yes
www.example.com Yes
shop.example.com Yes
a.shop.example.com Yes
otherexample.com No
example.com.other.net No
example.net No

Enter example.com in the domain field; do not enter https://, a path, query parameters or a port. Configuration is currently per domain, not per URL path.

Version 1.4.5 does not offer an option to match only that exact hostname and exclude all subdomains. If you only want to affect the shop.example.com branch, enter shop.example.com, but its subdomains are still included.

The compatibility form *.example.com also covers example.com itself and its subdomains in the current version, not just the subdomains. If valid example.com and *.example.com rules both exist, the former takes priority; when the former is paused, the latter can take over. New users usually only need the plain domain form.

3.2 Difference between pause and remove

Action or state Meaning
Pause Keeps the configuration but temporarily excludes it from matching; can be resumed
Remove Deletes the rule; recreate it if needed
Overridden The rule is still enabled, but a higher-priority rule applies to the current page
Invalid The current content cannot produce a valid UA; fix the content or the candidate pool

After a rule is paused or removed, the extension keeps looking for other valid rules. Therefore, pausing is not an exclusion rule that forces the page to use the browser default UA.

For example, suppose the only enabled, valid rules are global set to UA-G, example.com set to UA-P and shop.example.com set to UA-C:

Action Result when opening shop.example.com
All three rules enabled UA-C
Pause the subdomain rule UA-P
Also pause the parent-domain rule UA-G
Also pause the global rule Browser default UA
Add a valid tab rule UA-T That tab uses UA-T

UA-G, UA-P, UA-C and UA-T here are just labels for different UA contents.

04Two random modes

4.1 Every page load

A value is drawn once for each full network load of the main page, and ordinary in-page resources reuse that main-page result. Refreshing or a full navigation draws again; in-page requests such as images, APIs and iframes do not each trigger a new main-page draw.

For example, suppose the candidate pool contains UA-A, UA-B and UA-C:

Action One possible result
Open the page for the first time The main document and ordinary resources use UA-A
The page goes on to request images and APIs Still UA-A
Only an anchor or SPA in-page route changes Still UA-A
Refresh the page Drawn again; may use UA-C
Fully navigate to another page that still matches this rule Drawn again; may use UA-B

"Drawing again" does not mean "necessarily getting a different value". Likewise, when the browser's back or forward button restores a cached document directly, without a new network load of the main document, it cannot simply be treated as a new draw.

For redirects, the applicable rule is still determined by the destination page. Within the same navigation and the same rule, each redirect hop does not trigger repeated draws; if the destination domain hits a different rule, that rule is applied instead.

4.2 Per tab

The random result is stored per "rule + tab". As long as the configuration is unchanged and the tab is not closed, refreshes and full navigations under the same rule keep using that result.

For example, configure "Per tab" random for example.com:

Action One possible result
Tab 1 opens example.com This rule binds UA-A to tab 1
Tab 1 refreshes or goes to shop.example.com, with no more specific rule Continues with UA-A
Tab 2 opens example.com A binding is stored for tab 2; it may be UA-B, or may still be UA-A
Tab 1 goes to other.net, which has no rule, and there is no global rule Uses the browser default UA
Tab 1 returns to example.com Restores this rule's original UA-A
Close tab 1 and open it again The original tab binding is cleared and can be reassigned

If a separate shop.example.com rule exists, then even if both rules select the same candidate pool, they are still different rules and store random bindings separately. After rule parameters or the candidate library are modified, or after the browser restarts, random results may be reassigned.

4.3 Scope and mode combinations

The table below describes behavior once a rule has won main-page priority. Fixed modes include Built-in UA, Custom and Append text.

Scope Fixed modes Random on every page load Random per tab
Global Matching pages use this rule's UA Drawn on each main-page network load Each tab stores its own binding for this global rule
Domain Pages of the matching domain and its subdomains use this UA Drawn on each main-page network load within the matching scope Each tab stores its own binding for this domain rule
Tab This tab uses this UA, including after navigating to other websites This tab draws on each main-page network load This tab keeps a fixed random result for the rule, preserved across refreshes and cross-site navigation

In every combination, ordinary in-page resources inherit the main-page UA first. The random mode determines the lifetime of the value and does not change rule priority.

05In-page resources and resource-domain fallback

5.1 Resources inherit first when the main page has a rule

Suppose the following rules exist:

  • shop.example.com → UA-Shop.
  • cdn.example.net → UA-CDN.

When you open shop.example.com and the page loads cdn.example.net/photo.png, the image uses UA-Shop. Even if the resource's destination domain has its own rule, it does not override the main-page rule. This keeps the main document and ordinary in-page resources on the same UA.

If you open cdn.example.net directly in the address bar of a new tab, it is then the main-page domain and can match its own UA-CDN rule.

5.2 When the fallback switch takes effect

Resource domain fallback under "More" is off by default. It is an independent global switch and applies to all UA modes.

It takes effect only when the main page has no valid tab, domain or global UA, and it lets resources look for a valid domain rule based on their own destination domain. Resource domains follow the same logic: the more specific rule takes priority, and when a child rule is paused, the parent rule is inherited.

Does the main page have a valid UA? Switch Does the resource itself match a valid domain rule? UA of ordinary resources
Yes Off or on Yes or no Inherits the main-page UA
No Off Yes or no Browser default UA
No On Yes UA generated by the resource-domain rule
No On No Browser default UA

When the main page has no valid rule, its main document still uses the browser default UA; resource fallback never assigns a value to the main page in return. A valid global rule also counts as "the main page has a valid UA", so a global rule prevents resource fallback from taking over ordinary resources.

5.3 Fallback example

Open news.example.org, with no tab rule, main-page domain rule or global rule. There is also cdn.example.net → UA-CDN:

Request Fallback off Fallback on
news.example.org main document Default UA Default UA
news.example.org/api API Default UA Default UA
cdn.example.net/app.js Default UA UA-CDN
img.cdn.example.net/photo.png Default UA UA-CDN, inherited from the resource's parent-domain rule
other.net/font.woff, no matching rule Default UA Default UA

If a global UA-G is added, all the ordinary requests above are governed by the main page's UA-G, and the resource's UA-CDN no longer takes over.

5.4 Fallback with random modes

Resource-domain rule mode How the value is obtained when fallback is allowed
Fixed modes Uses the UA configured in the resource rule
Random on every page load The result is stored per "this load of the host page + resource rule"; resources in that page load that match the same rule share it
Random per tab The result is stored per "host tab + resource rule"; the same tab keeps using it after refreshes

For example, if cdn.example.net uses a random mode and both img.cdn.example.net and js.cdn.example.net inherit it, the two share that binding. If img.cdn.example.net has its own valid rule, it belongs to a different rule and can use a different UA.

Other tabs visiting the resource domain do not overwrite the resource random bindings already stored for the current page. Turning on fallback allows different resource rules on the same page to use different UAs; if you want an ordinary page to stay consistent as a whole, usually keep it off (the default).

06Setting your first rule

  1. Open the website you want to configure and click the UA Pro icon in the toolbar.
  2. If available, click the button to set a rule for the current website, or create a new rule through "More".
  3. Choose a scope. For a temporary test in the current tab only, choose "Tab"; to apply to multiple tabs of the same website, choose "Domain"; to use it as the default for all websites, choose "Global".
  4. If you chose Domain, check the domain field. For example, if you are on www.example.com and want to include shop.example.com, enter example.com.
  5. Choose a mode. For "Built-in", pick a browser or device; for "Custom", enter a full UA; for "Append Text", enter only the text to append; for "Random", choose a candidate pool and a random mode.
  6. In "Review and apply", check the scope and content, then click "Apply" or "Save & apply". Wait for the "Rule saved and enabled" confirmation.
  7. Refresh the web page and check the currently active rule shown on the home screen. Existing pages must be refreshed before the main document and scripts both adopt the new UA.

In the rule list you can edit, pause, resume or remove rules. A rule overridden by another remains enabled but does not currently have priority; a paused rule does not take part in matching. If a no-valid-UA warning appears, check the custom content or the random candidate pool.

A custom UA should be a single line of valid request-header content, without line breaks or control characters. New custom content or append text can be saved to a list by category, to select later or use as random candidates.

07Enable the UA overlay

Open More and enable UA overlay. It is off by default and can appear on accessible HTTP/HTTPS pages.

Page UA: the value the page's JavaScript reads from navigator.userAgent.

Request UA: the User-Agent observed by the browser for this main-document request.

This shows the UA of the current page in the browser’s address bar. It does not include the UA of requests for images, scripts, APIs or other resources, such as CDN resources.

If both values are available and exactly the same, they are shown on one line. Otherwise, they are shown separately.

If the window was turned on after the page loaded, refresh the page to capture its main request. When the request is unavailable, the window shows that status instead of using the configured value.

To move the window, drag the handle or a label. Drag the left or right border to adjust width, and the top or bottom border to adjust height. Double-clicking a border restores automatic sizing only for that dimension. The half-circle button adjusts background opacity. The close button turns off the window on all pages.

If a User-Agent is long, its text automatically continues on the next line in a narrow window. The window becomes taller when needed. Scroll inside the window if the text is taller than the screen. Manually set width and height remain until reset.

The window tries to keep the same size while loading the values for a new page. It shows a loading placeholder, never the previous page's values. A full navigation recreates the page, so the window may briefly disappear.

Changing a rule does not change an already loaded page or the header sent with its original request. Refresh to check the new rule. A proxy or server may change request headers after the browser observes them. The window cannot appear on protected browser pages or browser extension stores.

The More menu also contains New User Guide; click UA Pro at the bottom of that menu to open the website.

08How to configure common goals

Goal How to set it Notes
Try a mobile UA in the current tab only Tab + built-in mobile UA Still applies when that tab goes to other websites; stops after it is closed
Use a fixed UA across a whole site Domain example.com + Built-in UA or Custom Includes all subdomains; also applies to other tabs
Use a different UA for a shop subsite Keep the parent rule and add a shop.example.com rule Without a higher-priority rule, the child rule takes priority; when the child rule is paused, the parent rule can take over
Use one UA by default for all websites, with one site as an exception Set UA-G globally and UA-D on the target domain Where no other higher-priority rule applies, the target domain uses UA-D and other pages use UA-G
Select a random UA for a site on every refresh Domain + Random UA + Every page load Resources in that page load share it; a draw may repeat
Keep a site's UA stable in each tab Domain + Random UA + Per tab Each rule stores a binding separately in each tab
Set UAs for external resources only, by destination domain Create a resource-domain rule and turn on resource fallback The host page must not have a valid tab, domain or global UA
Temporarily disable a subdomain rule Click Pause The page uses the highest-priority remaining valid rule, such as a tab rule, another matching domain rule or the global rule. If none applies, it uses the browser default UA

09Backup and migration

The import and export features under "More" can back up or migrate global rules, domain rules, the custom library, the append-text library and the resource-domain fallback switch.

Tab rules and random bindings that have already been drawn are not part of this persistent configuration export. Importing does not rebuild the original tabs or their random state.

You can import a local configuration file, or load a remote configuration address and confirm the import. Export a backup first. A provided global-rule, domain-rules, custom-library or append-library object replaces its corresponding section. If any of these four sections is missing or null, its existing value remains unchanged; in particular, a null global rule does not clear an existing one. Resource domain fallback is enabled only when its field is true; otherwise, including when the field is missing or null, it is off after import.

In 1.4.5, the legacy random mode domain is treated as "Every page load"; legacy random rules that do not specify a random strategy are treated as "Per tab". After migrating, check the required random mode in the interface.

10FAQ and usage limits

Question Explanation
Why does the page still show the old UA right after saving? Existing documents are not reloaded; refresh after the save succeeds. Also check whether a higher-priority rule overrides it
Why is a custom UA still used after I paused the child rule? A valid tab rule may still take priority. Otherwise, another matching domain rule or the global rule may take over. Refresh the page after changing the rule and check the active rule
Why doesn't my resource-domain rule work? First check whether the main page already has a valid UA, then whether resource fallback is on, and finally whether the resource-domain rule is valid
Why doesn't the random value change after a refresh? Per-tab mode keeps it by design; Every-page-load mode can also draw the same value again
Why do tabs opened at the same time have the same UA? Random values may repeat; concurrent first navigations may also share one pre-drawn spare value
Why does the page still look like the desktop site after switching to a mobile UA? Websites may also rely on screen size, Client Hints or other information; changing the UA alone does not guarantee a different page layout

Concurrent first navigations use an approach that preserves the browser's native navigation: when several new tabs open a URL directly at the same time and the first packet is sent before the dedicated rule is installed, they may use the same pre-drawn UA; afterwards each tab stores its own binding. The extension adds no navigation relay and does not change native form POSTs into another navigation method.

Ordinary HTTP/HTTPS pages and their resources are the main target of this feature. Shared Service Worker requests cannot always be attributed to a single tab; UA synchronization for Client Hints, navigator inside Workers and iframes with no-network documents is not fully implemented in this version. Preserving a site's original Server-Timing is also not yet implemented in this change. Do not treat UA modification as a complete browser fingerprint spoof.

1.4.5 uses the webRequest and webNavigation permissions to track main-page navigation and the UA actually sent. It uses neither blocking-request permissions nor debugger permissions.

11Version verification and references

The final verification environment for 1.3.0 was an isolated test profile on Windows Edge 157.0.4341.42 with local HTTP/HTTPS sites. The full HTTPS run passed 128 cases with 2527 assertions; the HTTP boundary regression passed 5 cases with 441 assertions. These verify the rule combinations described above and the stated concurrency boundary; they do not mean every browser version and website has been covered.

The window in version 1.4.5 was tested in isolated Chrome and Edge profiles with local HTTPS pages. The tests covered navigation, combining identical page and request UAs into one line, resizing and delayed reads. They do not cover every website.

Detailed test records are kept in the project materials. Check the installable version on the Chrome Web Store or the offline download page; available versions may differ from this guide.