What is the "User-Agent Switcher" extension and how does it work?

When activated, this extension performs two main actions:

1. It overrides the navigator.userAgent string with a custom string provided by the user.
2. It modifies the "User-Agent" header sent with each request.

The first method helps JavaScript of the page to detect the user's browser type and operating system, while the second method assists web servers in identifying the user in the remote server. When the extension is active, both methods are applied to prevent the actual "User-Agent" string from being exposed. Additionally, this extension modifies other "navigator" keys related to the browser's User Agent.

When the extension is inactive (disabled via the toolbar popup by pressing the "Reset" button), there is no network manipulation, and the extension does not use any resources. The JavaScript override function is unregistered to ensure there are no performance drawbacks.

This extension only alters the "User-Agent" string for "HTTP://" and "HTTPS://" schemes. Locally loaded HTML pages with the "FILE://" scheme bypass the extension's protective script and display your actual "User-Agent" string. However, this poses no security or privacy concern as such pages cannot send requests to a web server.

What's new in this version?

Please check the Logs section.

How can I set a custom or predefined "User-Agent" string in this extension?

After installing the extension, a toolbar button (action button) will appear in your browser. Click this button to open the popup. You can pin the button into the toolbar area if it is hidden on the extensions menu. Wait a few seconds for all "User-Agent" strings to load. You can filter the strings by "Browser" type or "Operating System," or use the "custom" filtering box to find specific strings. Select a "User-Agent" string from the list It will be inserted into a text box where you can edit it. Once you're satisfied with the content, click the "Apply" button.

Sometimes, new versions of "User-Agent" strings for a particular browser are not on the list. Can I manually set it?

Yes, if you have a new User-Agent string, paste it into the text box in the popup and press the "Apply" button. Additionally, you can use the GitHub bug reporter to submit the new User-Agent string for inclusion in the list.

How can I reset the "User-Agent" string back to the default one?

Open the toolbar popup (action popup) and press the reset button. The toolbar color will change, and the tooltip will reset as well.

What is my current "User-Agent" string that is visible to websites?

To find your current "User-Agent" string, hover your mouse pointer over the toolbar button. The string and its source will be displayed in the tooltip. The source can be one of the following values: "user," "*," "custom," or "per-tab."

• "user" indicates that the User-Agent is set by the user through the popup interface.
• "*" means the User-Agent is the fallback provided by the user for custom mode.
• "custom" is used when there is a hostname key in the custom JSON object that matches the current tab.
• "per-tab" is used when the User-Agent is applied specifically to the current tab by pressing the "Apply (this tab)" button.

Additionally, in the version above 0.6.0, the extension changes the action icon based on these keywords.

Although the extension is active, my actual "User-Agent" string is still used in incognito mode. How can I fix this?

Go to your browser's extension manager and enable this extension to work in incognito mode. Optionally, you can also activate the extension for file URLs if you want the navigator object to be overridden.

Can I apply user-agent string spoofing only for certain domains?

Starting from version 0.1.3, you can choose between "white-list," "black-list," or "custom" modes of operation. In "black-list" mode, the custom user-agent string is applied to all tabs except those listed on the options page. Conversely, in "white-list" mode, the user-agent string is only applied to tabs whose hostname matches one of the hostnames listed on the options page. In "custom" mode, the user-agent string is determined from a user-defined JSON object. If a key in the JSON object matches the hostname of the tab, the corresponding user-agent string is used. Otherwise, the default user-agent string of your browser or the one set from the popup interface is used.

What does the "custom" mode mean and how can I use it?

In "custom" mode, the extension uses a user-defined JSON object to specify user-agent strings. If the JSON object contains a key that matches the top-level hostname (e.g., www.google.com), the value associated with that key becomes the user-agent string for all requests originating from that hostname. If no matching key is found, the extension defaults to the user-agent string set in the popup or the browser's default user-agent string.

To randomize user-agent strings, provide an array of user-agent strings instead of a single one. In version 0.6.0 and above, the extension randomly selects a user-agent string from the provided list for the current session. In previous versions, the user-agent string changed randomly with each new request. This change is due to modifications in manifest v3, which restricts dynamic alteration of network rules. Use "*" to match all hostnames. In versions before 0.6.0, you can use the "_" key to persist user agents for the session, though this key is ignored in versions 0.6.0 and above.

{
  "www.google.com": "useragent-string-1",
  "www.bing.com": "useragent-string-2",
  "www.example.com": [
    "random-useragent-string-1",
    "random-user-agent-string-2"
  ],
  "*": "useragent-string-for-all-hostnames"
}

{
  "www.example1.com": [
    "random-useragent-string-1",
    "random-user-agent-string-2"
  ],
  "www.example2.com": [
    "random-useragent-string-3",
    "random-user-agent-string-4"
  ],
  "_": ["www.example1.com", "www.example2.com"]
}

What is the purpose of the "Apply (window)" button in the toolbar popup?

[Deprecated in version 0.6.0] Since version 0.2.4, you could set a user-agent string specifically for the current window. This meant that all other browser windows would use the global setting except for the current window, which could help in organizing your work efficiently. You could assign multiple user-agent strings per window as needed. To reset window-based UA settings, use the "Restart" button in the toolbar popup, which clears all temporary settings when the extension restarts. Note that window-based settings are not permanent as they do not persist when the browser is restarted or all tabs in the window are closed. The extension adds a badge notification to the toolbar to indicate windows with defined user-agent strings. Users of black-list and white-list modes should refer to the options page to understand how these lists interact with the window-based user-agent string setting.

Is it possible to set an empty user-agent string?

Yes, you can use the keyword "empty" as the user-agent string. Please note that leaving the input blank is not valid. The extension will apply an empty user-agent string when "empty" is used. However, this is not recommended unless for special usage scenarios.

Does this extension support wildcard matching? How can I set a user-agent string for both a top domain and all its sub-domains?

(After 0.6.0 release]: The extension now applies the user-agent string set in custom mode for the domain and all its sub-domains.

[Before 0.6.0 release]: Wildcard matching is not supported directly due to performance considerations in JavaScript. Instead, the extension offers exact matching options. When enabled, you must list all sub-domains explicitly for the match to apply. If the option is disabled, the extension automatically includes all sub-domains in the matching process. For example, if google.com is listed in the white or black list, then www.google.com will also be matched.

How can I easily switch between different modes (black-list, white-list, and custom modes)?

Use the right-click context menu over the action button to switch between different modes. For example, if you are currently using the custom mode and wish to temporarily disable the extension, switch to the default black-list mode.

How can I determine if the user-agent string of the current tab is set? What do the different toolbar icon colors mean?

As of version 0.3.2, the toolbar icon uses three different colors to indicate its status.

• The gray color signifies that the extension is completely disabled, meaning no network observer is installed, and the extension has no impact on the browser.
• When the icon is colorful (not gray), it indicates that there is at least one network observer active. This could be due to a window with a custom user-agent set or if you are using the white-list or black-list modes.
• An orange color indicates that the current tab is using the user-agent string set from the toolbar popup.
• A half-blue color means the tab is being ignored, and the default user-agent string is used. This applies to internal pages, pages not refreshed after enabling the extension, or pages on the protected list or white/blacklists. If using JSON mode, the color remains orange, and the user-agent string is displayed in the tooltip area.

In version 0.6.0, two new colors were introduced:

• The half-green color indicates that the extension could potentially match the hostname with a custom rule.
• The half-pink color signifies that the tab is using a per-tab user-agent string.

Although the extension modifies the userAgent key of the "navigator" object, there are additional keys that must be altered to fully spoof the navigator object when switching between browsers such as Firefox and Chrome.

This extension spoofs more than just the user agent key. It currently modifies "navigator.userAgent," "navigator.appVersion," "navigator.platform," "navigator.vendor," "navigator.product," and "navigator.oscpu." If these modifications are insufficient for your needs, you can define additional keys in the options page under a custom parser object. When a user-agent string matches a key in this parser object, the extension bypasses the default parser and uses the specified object instead. You can define multiple keys as needed. To delete a key, use the "[delete]" keyword as the value. All keys defined in this object will be appended or replaced in the navigator object, allowing you to customize it according to your preferences.

What does this extension do with the port number in the hostname part of the URL (e.g., http://127.0.0.1:8000/)?

[after 0.6.0 release]: The extension uses the actual hostname and ignores the port number.

[before 0.6.0 release]: In both white-list and black-list modes, the extension considers the entire hostname including the port number when resolving matches. For example, the hostname "127.0.0.1:8000" would need to be specified to match pages with that exact port. In custom mode, the extension checks both hostnames with and without the port section. This means rules for both "127.0.0.1:8000" and "127.0.0.1" would match pages like http://127.0.0.1:8000/.

Can I group several hostnames to have a single user-agent string in custom mode using the JSON object?

Yes, you can create a key in the JSON object that lists hostnames separated by commas. Refer to the example on the extension's options page for more information. In version 0.6.0 and above, all hostnames in the same key will receive the same user agent string (randomly selected from the provided list) for the current session.

I need to create a user-agent string based on the browser's current user-agent string. Is it doable with this extension?

Yes, this extension supports "${}" placeholders. Whatever is inside the "${}" expression will be passed by a sandboxed navigator object, and the result replaces the expression. To use the current user-agent string use ${userAgent} or to use the current platform use ${platform}. You can have multiple ${} expressions in your user-agent string definition too.

As of version 0.4.3, the parser also supports a more complex syntax replacement ("${dot-separated.keys|ua-parser@custum-user-agent-string}") which uses a sandboxed parsed user-agent object which provides a more flexible variable replacement. For instance, to get the current browser version use "${browser.version|ua-parser}". You can also pass a user-agent string to this parser and then extract a key. For instance to extract the browser version from the "ua-parser" of Mozilla/5.0 ... user-agent string, use "${browser.version|ua-parser@Mozilla/5.0 ...}". Here is a sample output of the "ua-parser" object. You can use all these keys in your replacement queries:

{
  "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.102 Safari/537.36",
  "browser": {
    "name": "Chrome",
    "version": "85.0.4183.102",
    "major": "85"
  },
  "engine": {
    "name": "Blink",
    "version": "85.0.4183.102"
  },
  "os": {
    "name": "Mac OS",
    "version": "10.15.6"
  },
  "device": {},
  "cpu": {}
}

Can I set a user-agent string in the Firefox browser before it starts?

Firefox supports a preference called "general.useragent.override" which allows you to input a user-defined UA string. Setting this preference will overwrite the default UA string used by your browser. It's important to note that this method does not overwrite other navigator properties, but it is the most reliable way to change the actual user-agent string. If you intend to use a single UA string consistently, it is recommended to set this preference and also configure the same UA string in this extension to ensure all relevant navigator properties are protected.

Is it possible for an admin user to set the default user-agent string of this extension for all machines in the local network

As of version 0.3.6, this extension supports reading a custom user-agent string from its managed storage. This way an admin user can use the operating system's policy center to adjust a custom user-agent string. This method works on all Chromium browsers as well as the Firefox browser. For instance to set a custom agent for Chrome browser on Mac OS, create "com.google.Chrome.extensions.bhchdcejhohfmigjafbampogmaanbfkg.plist" file in "/Library/Managed Preferences/" directory with the following content:

<!DOCTYPE plist PUBLIC "-//Apple/DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>ua</key>
    <string>this is me</string>
</dict>
</plist>

<!DOCTYPE plist PUBLIC "-//Apple/DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>json</key>
    <string>JSON string (use Shift key while exporting to generate this string)</string>
</dict>
</plist>

Starting with version 0.6.1, the extension can now accept configurations from a remote server that provides preferences in JSON format. To create a sample JSON file, use the export button and modify the file as needed. Then, set up the server and configure the options page to use this server. Keep in mind that the server configurations will overwrite the user settings each time a new GUID is generated, so it is important to include the remote address in the provided JSON for future updates.

[Firefox Only] What does the "Consider Containers" button mean on the popup interface?

This option isolates user-agent strings for different containers. Each container is treated as a distinct environment. Users must manually set a user-agent string for each container. If no user-agent string is set for a container, it defaults to the browser's default user-agent, even if the default container has a custom user-agent string. This logic also applies to window-based user-agent strings.

User-agent strings set for containers persist across browser restarts, so they need to be configured only once. To set a user-agent string for a container, open the interface on a tab belonging to that container and click the "Apply (container)" button.

When I enable this extension, I encounter "Error 1010 Ray ID: Access denied" on several websites, including this page. What could be causing this issue?

Many websites verify your user-agent string to ensure requests are coming from a browser and not automated scripts. Ensure you are using a valid user-agent string that accurately represents a browser. To check the current user-agent string being used, hover your mouse over the action button when you encounter this error on a website. The tooltip will display the current user-agent string in use. An example of an invalid user-agent string does not start with "Mozilla/5.0".

What is the meaning of "Sibling Hostnames" on the options page?

This feature has been deprecated since version 0.6.0. It was a JSON array used to group hostnames that are siblings to each other. For example, "google.com" and "youtube.com" are considered siblings because both belong to Alphabet Inc. All hostnames within the same group would share a single user-agent string. The extension resolved the user-agent string for the first request to any hostname in the group and then applied this user-agent string to all members of the group for subsequent requests. This feature was particularly useful when using "Custom Mode" with a random list where the hostname was also included in the "_" list. It allowed the extension to randomly select a user-agent string once for this hostname and use it consistently across all subsequent requests from this hostname and its siblings.

For version 0.6.0 and above, since the extension now selects a user-agent string once per session and applies it uniformly across all hostnames grouped under a key, the need for this feature has been eliminated.

Is this extension sufficient to make sure my real user-agent string is not leaking?

This extension does its best to protect your user-agent string from being revealed to web pages. However, it is also recommended to start your browser with the exact same user-agent string. Although most browsers support applying a custom user-agent, they are not going to alter other navigator properties. However, the actual user-agent is going to be spoof even if for any reason this extension failed at spoofing the string. On Firefox you can apply a custom user-agent string from about:config panel. Open this URL in a browser tab and search for general.useragent.overridepreference preference. Set the exact user-agent string as the one you have set for this extension, and restart your browser. For Chrome, you can create a desktop shortcut, and pass --user-agent="Your new user agent" argument to the executable.