Url module - User-Agent handling

Copyright 2004-2011 Opera Software ASA. All rights reserved. This file is part of the Opera web browser. It may not be distributed under any circumstances.

  1. Abstract
  2. General description
  3. User Agent overrides
  4. Run-time additions to the User Agent string
  5. References

Abstract

This document describes the UAManager class in Opera and how it handles the User-Agent strings reported by Opera.

General description

Opera can report several different User Agent strings, depending on how it is configured. The UAManager is the code that composes this string, using the user configuration, and a list of overridden hosts, either hard-coded or defined by the preferences.

See the generated API documentation for a description on how to access the various strings. The actual string to use at run-time is defined by the user preferences.

Note: The Opera 8.0 syntax, used for when Opera does not identify as itself, was introduced in v3.6x to bypass Wells Fargo sniffers, and does not strictly adhere to the User-Agent string standards.

User Agent overrides

The UAManager co-operates with the ServerName class from the Url module to handle overridden User-Agent strings on a host-by-host basis.

Using the host override functionality for preferences, it is possible for the users to specify their own overridden user agents on a host-by-host basis. These overrides are configured in the normal way, see the API documentation for the Preferences module for detailed information on how to achieve that. In addition, the preferences download support can be used to automatically retrieve such overrides from Opera's servers.

Run-time additions to the User Agent string

Comment components

Certain code modules, such as the voice support, wish to identify themselves by adding information to the string. This is accomplished by calling UAManager::AddComponent() with a string to insert in the comment part of the User-Agent string (inside the parenthesis). Each token is inserted in the semicolon separated list at the end of the comment string, before the UA language token. Each token can only be added once, additional adds will be ignored (but will not flag an error).

Any ISP branding token, as specified in the preferences file, will be inserted after any run-time added components, before the language token. ISP branding requires support for run-time tokens be enabled.

If the token is controlled by a toggle, it is also possible to remove a previously added token using UAManager::RemoveComponent(). It is not possible to remove the ISP id in this manner.

The token must conform to the syntactic rules of the User-Agent string, as defined in RFC 2616, and must not contain any opening or closing parentheses.

Example: Adding the string IBM EVV/3.0/EAK01AG9/LE (identifier for one version of the voice library) might yield a User-Agent string on the form:
Opera/9.00 (Windows NT 5.1; U; IBM EVV/3.0/EAK01AG9/LE; en)

Comment components are enabled by activating TWEAK_URL_UA_COMPONENTS. Please note that you also need to enable the corresponding preference. You can control the default through the TWEAK_PREFS_UASTRING_COMPONENTS setting.

Product tokens

In some special cases, a product wants to be able to identify itself in the User-Agent string by adding an identifying token at the beginning or end of the string. This is accomplished by calling UAManager::SetPrefix() and UAManager::SetSuffix() with the string that should either be the prefix or the suffix.

The typical use is to add the brand and model of a mobile phone.

The token added must conform to the syntactic rules for product identifiers in RFC 2616, and is reserverd for identifying actual products. For other kind of identification, please use the comment components as described above.

Example: Adding the prefix SonyEricssonP990i/R100 (identifier for one of the mobile phones Opera is running on) might yield a User-Agent string on the form:
SonyEricssonP990i/R100 Opera/9.00 (Symbian OS; U; en)

Product tokens are enabled by activating TWEAK_URL_UA_TOKENS. They do not require any preference to be set to be active, they will always be used if the functionality is enabled and a prefix and/or suffix is set.

Dynamic tokens

For some builds, it is not possible to serve all needs with just adding static comments or product tokens. For instance, in the Opera Mini server, we want to be able to insert the phone model into the User-Agent string, and different windows in the same session can be used on different phone models.

This is accomplished by implementing the OpUAComponentManager interface in your platform code. Whenever the core code requests a User-Agent string, the various APIs in this interface will be called with a context that should make it possible to determine which client requests the information.

The dynamic token support is enabled by activating TWEAK_URL_UA_COMPONENTS_CONTEXT. You will need to inherit the OpUAComponentManager API and implement the OpUAComponentManager::Create() factory method.

References

  1. Preferences module