UA Override List Policy

The user agent override whitelist provides the ability to serve a custom user agent (UA) to a site from B2G. If you find a site which is broken in B2G or Firefox for Android and you have confirmed (e.g. by using an add-on like Phony) that it is broken due to UA sniffing problems, then the site may be able to be added to the UA override list temporarily until it gets fixed.

Sites can be added to the UA Override list if/when:

1. An evangelism bug has been opened and the site has been contacted;
2. The site has proved unresponsive or unwilling to accommodate us (how long we wait for this will depend on factors such as the popularity of the site and the extent of breakage);
3. There is a specific proposed alternative UA for each broken product which has minimal changes from the default;
4. Either: Deep testing (not just the front page) has shown that a UA override for that UA in that product leads to a significant UX improvement on the site; or we know that the fix works because it restores a UA which that product had previously;
5. The override is only for the broken products;
6. The entry in the prefs file comes with a comment with a reference to the evangelism bug in question.

Note that the evangelism bug and the bug for adding the site to the override list should be two separate bugs.

Sites should be removed from the list, for all active branches, once the site has confirmed that they have fixed it, or deep testing makes us believe they have.

This policy attempts to balance the ability to react to problems users are experiencing, with a requirement to check that we are aiming before shooting, that we don't actually degrade the user experience (e.g. by bypassing a check which kept them from a very broken site) and that we are making sure the list does not grow without any organized efforts to shrink it again.

UA Override Capabilities

UA overrides are maintained in a json file that lives in mozilla-central, but are served from a CDN. This allows us to push updates to users independent of release dates.

Note: a similar file for B2G exists, but is basically unmaintained.

The code which parses and constructs them is in UserAgentOverrides.jsm, and the code which apples them is in nsHTTPHandler.cpp. The code for fetching updates lives in UserAgentUpdates.jsm

To verify if an override was successfully synced to the CDN, visit:

https://dynamicua.cdn.mozilla.net/0/%7Baa3c5121-dab2-40e2-81ca-7ea25febc110%7D

It should be there within 24 hours of landing on mozilla-central.

An override applies to the domain given and all subdomains (unless a subdomain has a more specific rule).

Simple UA override

The UA override system has the ability to do a search and replace in the UA, replacing all occurrences of one static string with another. So:

 // bug 826335, globo.com
 "globo.com": "\\(Mobile#(Android; Mobile",

replaces "(Mobile" with "(Android; Mobile" - i.e. turning the B2G UA into the Firefox for Android UA. The # separates the search part and the replace part, and on the left hand side regexp-special characters - e.g. ( - which you want matched as literals need double-backslash-escaping (the first escapes the backslash for JS, and the second escapes the char in the regexp to make it a literal).

Effectively, the following string operation occurs:

 "Mozilla/5.0 (Mobile; rv:38.0) Gecko/38.0 Firefox/38.0".replace(new RegExp("\\Mobile", "g"), "(Android; Mobile")

The system also has the ability to entirely replace the UA with another string. So:

 // bug 826348, linkedin.com
 "linkedin.com": "Mozilla/5.0 (Linux; Android 4.0.4; Galaxy Nexus Build/IMM76B) AppleWebKit/535.19 (KHTML, like Gecko) Chrome/18.0.1025.133 Mobile Safari/535.19",

changes our UA to be that of Chrome on Android 4.0.4 on a Galaxy Nexus. These two cases are differentiated in the code by the presence or absence of a hash (#) character.

Complex UA override

Lastly, there is also a system for more complex, conditional overrides, but these have to be hard-coded. At time of writing, there is only one of these, used to request desktop sites in Firefox for Android.

WebCompat Go Faster is being developed to replace any need to hard-code conditional overrides.