Resource: User Agents Database

Fahrzin Hemmati edited this page May 21, 2015 · 14 revisions

The user agents database is located in the resources/user-agents folder in the main repository. The folder is split up into sections depending on the type of user agent:

  • resources/user-agents/apps - contains UAs for native mobile apps, embedded apps and so on
  • resources/user-agents/browsers - contains UAs for normal browsers
  • resources/user-agents/core - core data - default properties and default (fallback) browser
  • resources/user-agents/crawlers - bots, crawlers, search engines etc.
  • resources/engines.json - contains definitions about rendering engines with their versions and the defined properties
  • resources/platforms.json - contains definitions about platforms with their versions and the defined properties

All files are described in a JSON file format.

Format

Divisions

Each individual .json file is rendered in the INI file as a "division", which is a section headed like so:

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; Division Name

[UserAgent/1.*]
Some=Property
Another=Value

The UA file for this would look like:

{
  "division": "Division Name",
  "sortIndex": 1120,
  "lite": true,
  "userAgents": [
    {
      "userAgent": "UserAgent\/1.*",
      "properties": {
        "Some": "Property",
        "Another": "Value"
      }
    }
  ]
}

The sort index is a "global" sort index which allows overall ordering of the Browscap files. The lite property marks a division to be rendered into the lite version of the Browscap files. The userAgents property should contain an array of "User Agent objects" (see reference below).

Version Expansion

Version expansion is a way of re-using the same User Agent definition for multiple versions that have the same match strings, just with different versions. You can use the #MAJORVER# and #MINORVER# tags Using version expansion will output a separate division for each version specified, e.g.:

{
  "division": "Division Name #MAJORVER#.#MINORVER#",
  "versions": ["1.0", "1.5"],
  "sortIndex": 1120,
  "userAgents": [
    {
      "userAgent": "UserAgent\/#MAJORVER#.#MINORVER#.*",
      "properties": {
        "Parent": "DefaultProperties",
        "Version": "#MAJORVER#.#MINORVER#",
        "MajorVer": "#MAJORVER#",
        "MinorVer": "#MINORVER#"
      }
    }
  ]
}

This version specification would render as two divisions:

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; Division Name 1.0

[UserAgent/1.0.*]
Parent="DefaultProperties"
Version="1.0"
MajorVer="1"
MinorVer="0"

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; Division Name 1.5

[UserAgent/1.5.*]
Parent="DefaultProperties"
Version="1.5"
MajorVer="1"
MinorVer="5"

User Agent objects

Each user agent object (contained in the userAgents array described above) can be a very simple object consisting of a user agent match string (or simple identifier, which can be used as a tree identifier) and a set of properties. The platform and the engine properties are optional and linked to the entries in their files. If defined these linked properties are default definitions for the platform or the engine and could be overwritten in the children sections.

{
  "userAgent": "Foo\/1.* Bar\/10.*",
  "platform": "PlatformX",
  "engine": "EngineY",
  "properties": {
    "Parent": "DefaultProperties",
    "Comment": "Foo Bar browser",
    "Version": "1.0",
    "MajorVer": "1",
    "MinorVer": "0",
    "Tables": "true"
  }
}

Children Expansion

If a browser has more than one version of useragent (independent from version and platforms), these different useragents should be added within the children definition, e.g.:

{
  "division": "Amoi",
  "sortIndex": 2060,
  "userAgents": [
    {
      "userAgent": "Amoi",
      "properties": {
        "Parent": "DefaultProperties",
        "Browser": "Amoi",
        "Platform": "JAVA",
        "Platform_Maker": "Oracle",
        "isMobileDevice": "true"
      },
      "children": [
        {
          "match": "AMOI\/R1A"
        },
        {
          "match": "Amoi-A869\/Plat-V-FT\/WAP2.0\/MIDP2.0\/CLDC1.0"
        },
        {
          "match": "Amoi-H9\/Plat-EMP\/WAP2.0\/MIDP2.0\/CLDC1.0"
        },
        {
          "match": "Amoi-M6\/Plat-EMP\/WAP2.0\/MIDP2.0\/CLDC1.0"
        },
        {
          "match": "Amoi-M8\/Plat-EMP\/WAP2.0\/MIDP2.0\/CLDC1.0",
          "engine": "Gecko",
          "properties": {
            "isMobileDevice": "false"
          }
        }
      ]
    }
  ]
}

A Child definition may include its own properties Array. This should only used for properties which differs for that specific Child from its UserAgent Parent. If a Child definition has a different rendering engine, a Child section can have a engine property.

Platform Expansion

This allows you to easily specify that a browser appears on many platforms easily. This is done by adding a children definition, with a match with a #PLATFORM# tag and a platforms array, e.g.:

{
  "userAgent": "FooBarBrowser",
  "properties": {
    "Parent": "DefaultProperties",
    "Comment": "Foo Bar browser",
    "Version": "1.0",
    "MajorVer": "1",
    "MinorVer": "0",
    "Tables": "true"
  },
  "children": {
    "match": "Foo\/1.* Bar\/10. (#PLATFORM#)",
    "platforms": ["Win8_32", "Win8_64", "Android_4_1", "WinPhone8"]
  }
}

This user agent will now render four times, each with a different platform specification. Version expansion can also be used in the children.match string by using the #MAJORVER# and #MINORVER# tags.

Platforms can be found in the [Resource: Platforms Database] file.

Schema Reference

Division object reference

  • division: Name of the division (output as an INI comment)
  • versions: (optional) Enable version expansion for the specified versions
  • sortIndex: Global sort index
  • lite: (optional) Flag to show that the division will be part of the lite version of the output files
  • userAgents: Array of user agents

User Agent object reference

  • userAgent: Identifier, or User Agent match
  • platform: (optional) an Platform Name which is used as default for the User Agent
  • engine: (optional) an Engine Name which is used for the User Agent
  • properties: Array of properties
  • children: Array of Children objects

Children object reference

  • match: User Agent match
  • properties: (optional) Array of properties
  • engine: (optional) an Engine Name which is used for the User Agent
  • platforms: (optional) Enables platform expansion for the specified platforms

Tags reference

  • #MAJORVER#: the major version number
  • #MINORVER#: the minor version number
  • #PLATFORM#: the platform UA match string

Properties reference

actual Properties

  • Parent: Parent user agent
  • Comment: A comment about the UA
  • Browser: The Name of the Browser
  • Browser_Type: The Type of the Browser, it may have one of these values: Browser, Application, Bot/Crawler, Useragent Anonymizer, Offline Browser, Multimedia Player, Library, Feed Reader, Email Client or unknown
  • Browser_Bits: The number of bits, it may have one of these values: "0", "8", "16", "32", or "64"
  • Browser_Maker: The Name of the company or organsation who created the Browser
  • Browser_Modus: The Modus the Browser is running, only relevant for mobile Browsers who can activate a Desktop Mode
  • Version: The Version of the Browser
  • MajorVer: The Major Version Part of Version
  • MinorVer: The Minor Version Part of Version
  • Platform: The Name of the Platform the Browser is running on
  • Platform_Version: The Version of the Platform
  • Platform_Description: A Description for the Platform
  • Platform_Bits: The number of bits, it may have one of these values: "0", "8", "16", "32", or "64"
  • Platform_Maker: The Name of the company or organsation who created the Platform
  • isSyndicationReader: A Flag to sign the Browser is a RSS Reader
  • CssVersion: The Major Version of CSS the Browser is supporting
  • Device_Name: The (Marketing) Name of the Device
  • Device_Maker: The Name of the company or organsation who created the Device (e.g. Apple Inc)
  • Device_Type: The Type of the Device, it may have one of these values: Mobile Phone, Mobile Device, Tablet, Desktop, TV Device, Console, FonePad, Ebook Reader, Car Entertainment System or unknown
  • Device_Pointing_Method: The Method who Objects are pointed with on the device, it may have one of these values: mouse, touchscreen, joystick, stylus, clickwheel, trackpad, trackball or unknown
  • Device_Code_Name: A Codename of the Device to differ Devices with the same Device_Name
  • Device_Brand_Name: The Name of the company the device is branded with (e.g. Apple)
  • RenderingEngine_Name: The Name of the Engine
  • RenderingEngine_Version: The Version of the Engine
  • RenderingEngine_Description: A Description about the Engine
  • RenderingEngine_Maker: The Name of the company or organsation who created the Engine

mostly unmaintained Properties

Theses properties are not actively maintained. Except the first two ones it should be possible to detect these properties with Javascript better.

  • Alpha: A Flag to sign the Browser as Alpha Version
  • Beta: A Flag to sign the Browser as Beta Version
  • Frames: A Flag to sign the Browser is supporting Frames
  • IFrames: A Flag to sign the Browser is supporting IFrames
  • Tables: A Flag to sign the Browser is supporting Tables
  • Cookies: A Flag to sign the Browser is supporting Cookies, be aware that the user often can deactivate cookies
  • BackgroundSounds: A Flag to sign the Browser is supporting Background Sounds (should only be true for Browsers using the Trident engine)
  • JavaScript: A Flag to sign the Browser is supporting JavaScript, be aware that the user often can deactivate JavaScript
  • VBScript: A Flag to sign the Browser is supporting VB Script (should only be true for Browsers using the Trident engine)
  • JavaApplets: A Flag to sign the Browser is supporting Java Applets
  • ActiveXControls: A Flag to sign the Browser is supporting ActiveX Controls (should only be true for Browsers using the Trident engine)

deprecated Properties

Theses properties are maintained, but deprecated. Replacement properties have been added some time ago.

  • Win16: A Flag to sign the Browser is running on 16Bit Windows, please use the Platform_Bits property instead
  • Win32: A Flag to sign the Browser is running on 32Bit Windows, please use the Platform_Bits property instead
  • Win64: A Flag to sign the Browser is running on 64Bit Windows, please use the Platform_Bits property instead
  • isMobileDevice: A Flag to sign the Browser is running on a mobile device, please use the Device_Type property
  • isTablet: A Flag to sign the Browser is running on a tablet device, please use the Device_Type property
  • Crawler: A Flag to sign the Browser is a Bot/Crawler, please use the Browser_Type property
  • AolVersion: The AOL Version