User Agent Enrichment

A user agent request header contains a string that tells a website information about the user’s device, operating system, and browser. This can be helpful information when you are trying to do analysis on your users. The User Agent enrichment will take a user agent string and parse it into the device, browser, browser version, operating system, and operating system version.

If you want to start using the enrichment right now while tracking pageviews, clicks, and form submissions, check out the Web Auto-Collector.

When this enrichment is being used, you can do analysis on many different properties:

Property Description
device An object containing info about the device.
device.family A string containing the device family. ie: “iPhone”.
device.type A string containing the device type ie: “mobile phone”. When user agent is invalid that property doesn’t exists.
browser An object containing info about the browser.
browser.family A string containing the family of the browser. ie: “Firefox”
browser.major A number indicating the major version of the browser.
browser.minor A number indicating the minor version of the browser.
browser.patch A number indicating the patch of the browser.
os An object containing info about the os.
os.family A string containing the family of the operating system. ie: “Windows 10”
os.major A number indicating the major version of the operating system.
os.minor A number indicating the minor version of the operating system.
os.patch A number indicating the patch of the operating system.
os.patch_minor A number indicating the minor version of the patch of the operating system.

Any values of the user agent that Keen can’t parse will say “Other”.

To Activate User Agent Enrichment

The parameters for the User Agent enrichment are as follows:

Parameter Description
name “keen:ua_parser”
input An object with a key of “ua_string” and a value of the name of the property containing the user agent string to parse.
{ "ua_string": "property.containing.ua_string" }
output A property name describing where the produced object should be stored.

This enrichment can be used with the dynamic user agent placeholder.

To activate the enrichment, include the keen.addons object in your data model as seen below:

{
  "user_agent": "${keen.user_agent}",
  "keen": {
    "addons": [{
      "name": "keen:ua_parser",
      "input": {
        "ua_string": "user_agent"
      },
      "output": "parsed_user_agent"
    }]
  }
}

The example above will create an output that looks like this:

{
  "user_agent": "Mozilla/5.0 (iPhone; U; CPU iPhone OS 5_1_1 like Mac OS X; en AppleWebKit/534.46.0 (KHTML, like Gecko) CriOS/19.0.1084.60 Mobile/9B206 Safari/7534.48.3",
  "parsed_user_agent": {
    "device": {
      "family": "iPhone",
      "type": "mobile phone"
    },
    "browser": {
      "family": "Chrome Mobile iOS",
      "major": 19,
      "minor": 0,
      "patch": 1084
    },
    "os": {
      "family": "iOS",
      "major": 5,
      "minor": 1,
      "patch": 1,
      "patch_minor": null
    }
  },
  "keen": {
    "created_at": "2012-12-14T20:24:01.123000+00:00",
    "timestamp": "2012-12-14T20:24:01.123000+00:00",
    "id": "asd9fadifjaqw9asdfasdf939"
  }
}

You can also find the API Reference section for this enrichment here.

Examples

You might want to know what browsers are most popular with your users or what browsers are being used when you for example send an error event you created.

Count pageviews with parsed_user_agent.browser.family group_by:

Group by browser

Or you might want to compute what operating systems are your users using.

Count pageviews with parsed_user_agent.os.family group_by:

Group by OS