Analytics.js Overview

Overview

Analytics.js is a specification designed to standardize event tracking for web analytics, advertising platforms, marketing tools, and much more. By utilizing Analytics.js and its event methods, you will create a rich, actionable data set from your website, mobile app, server, and other sources. It is particularly useful for tracking the pages or screens your users visit, the actions they take on your property, and whether the user has been identified previously.

Once your Analytics.js tracking ecosystem has been configured, you will be ready to send events to MetaRouter, transform them within the MetaRouter platform according to your preferences, and send them to your vendors (referred to as Integrations). Continue on to get started with Analytics.js.

Prerequisites

  1. A Successful MetaRouter Deployment
  2. Set up your DNS

Note: You can install Analytics.js prior to creating your Data Infrastructure. However, no events can be processed by MetaRouter until your Data Infrastructure is configured.

Installing the Analytics.js SDKs

Follow the link below to learn how to install the Analytics.js SDK.

Determining What to Track

Your organization is likely already tracking a variety of events, and may even already be using the Analytics.js event spec. If you're already using Analytics.js, then you won't need to establish and code events again unless you'd like to add to or modify your event tracking schema. If you are not currently using Analytics.js, then continue reading on.

You'll want to work on developing your event schema, which will contain the event names, properties and traits, and any other data you'd like to track on your site. We recommend centralizing your tracking into a central spreadsheet, which will serve as a source of truth. Transparency is important so that different teams (engineering, marketing, analytics, etc.) can quickly see the available events and data they have on hand, and where extra tracking implementation might be needed.

When considering what you want to track, think about the type of information necessary to make your tools work. For advertising, you likely want to ensure you're sending page or track events that encompass your conversion actions, as well as identify events that will help you build retargeting audiences and measure performance. For analytics tools, you'll want to record the same information for optimization purposes and user journey tracking.

You likely already have an event ecosystem in place; you will just need to translate that to Analytics.js. Once you do this, you never have to touch your event schema again unless you want to add to or modify your schema.

πŸ“˜

MetaRouter Event Schema Workbook

We've built a spreadsheet that you can get started with here. Please fill out as best as you can to help us understand what events you will track, what properties will those events have (global as well as per event) and the types of values those properties will be.

Event Types

These are the available event types when using MetaRouter:

Support for event specs other than Analytics.js

In some cases, Analytics.js may not serve as the best specification for tracking data. We are planning on supporting additional specifications in the future. If you would like a different event specification, please let us know.

Common Fields of Analytics.js API Calls

Every Analytics.js API call has a common structure. While some specific calls pass extra information, they will all pass the information detailed in this section. While MetaRouter can include all of these fields, not every destination will accept every field listed below.

General Structure

As mentioned above, there is a general structure that governs our API calls. Below is an example of this structure in raw JSON:

{
  "anonymousId": "exampleAnonymousId1234",
  "context": {
    "active": true,
    "app": {
      "name": "MetaRouter",
      "version": "123",
      "build": "1.1.1.123",
      "namespace": "com.production.metarouter"
    },
    "campaign": {
      "name": "MetaRouter Sunday Reads",
      "source": "Newsletter",
      "medium": "email",
      "term": "tps reports",
      "content": "image link"
    },
    "device": {
      "id": "exampleDeviceId",
      "advertisingId": "exampleAdvertisingId",
      "adTrackingEnabled": true,
      "manufacturer": "Apple",
      "model": "iPhone7,2",
      "name": "astro",
      "type": "ios",
      "token": "exampleToken"
    },
    "ip": "1.2.3.4",
    "library": {
      "name": "analytics.js",
      "version": "2.11.1"
    },
    "locale": "nl-NL",
    "location": {
      "city": "Cincinnati",
      "country": "United States",
      "latitude": 39.1031,
      "longitude": 84.512,
      "speed": 0
    },
    "network": {
      "bluetooth": false,
      "carrier": "Verizon",
      "cellular": true,
      "wifi": true
    },
    "os": {
      "name": "iPhone OS",
      "version": "8.1.3"
    },
    "page": {
      "path": "/",
      "referrer": "",
      "search": "",
      "title": "MetaRouter",
      "url": "https://www.metarouter.io/"
    },
    "providers": {
      "google": {
        "glcid": "123abc"
      },
      "bing": {
        "mid": "xyz456",
        "msclkid": "789dcef"
      }
    },
    "referrer": {
      "id": "exampleId",
      "type": "example"
    },
    "screen": {
      "width": 320,
      "height": 568,
      "density": 2
    },
    "timezone": "America/Cincinnati",
    "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 9_1 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13B143 Safari/601.1"
  },
  "integrations": {
    "All": true
  },
  "messageId": "exampleMessageId",
  "receivedAt": "2017-12-5T01:05:31.909Z",
  "sentAt": "2017-12-5T01:05:31.581Z",
  "type": "track",
  "userId": "exampleUserId",
  "version": 2
}

Below is a chart detailing what the fields in the above sample payload mean.

FieldTypeDescription
anonymousIdObject (optional)A pseudo-unique substitute for User ID. This is for cases when you don't have an absolutely unique identifier.
contextObject (optional)Dictionary of extra information that provides useful context about a message that is not directly related to the API call
integrationsString (optional)Dictionary of destinations to either enable or disable
messageIdString (implicit)Automatically collected, this is a unique identifier for each message that lets you find an individual message across the API
receivedAtDate (implicit)The timestamp of when a message is received by MetaRouter
sentAtDate (optional)The timestamp of when a message is sent to MetaRouter
typeString (implicit)Type of message, according to the Event method
userIdString (required)Unique string that identifies a user in your database
versionNumber (implicit)Version of the Tracking API that received the message, automatically set by MetaRouter

A Note on anonymousId

MetaRouter leverages a UUID4-formatted anonymous identifier, anonymousId, for user identification and attribution with its libraries. In a web browser context, this identifier is set as a first-party cookie and is persisted across user sessions to serve as a consistent identifier for the user. This parameter is available for use for attribution with downstream integrations, or can be utilized by MetaRouter's Sync-Injector for External ID matching with certain vendors who support this.

Each of MetaRouter's SDKs (Web, iOS, Android, Server) generate their own Anonymous IDs for users. Most CDPs and attribution platforms will allow for the sending and centralization of multiple Anonymous IDs for a single user, as long as there is a consistent User ID (eg. Hashed Email) that can be provided for these users as well. This is usually done at the beginning of sessions using an Identify call.

Context

This section will provide other information you can gather to provide useful context about the user's device and environment. You can pass additional information with the context object; however, we recommend passing any custom user or behavior values in the properties object.

You should only use these fields for their intended meaning; they are complete and explicit specifications.

FieldTypeDescription
activeStringTells whether a user is active. This can be used to flag an identify call to update its traits
appObjectInformation about the current application, including name, version, and build.
campaignObjectInformation about the campaign that led to the API call, including name, source, medium, term, and content. This field maps directly to the common UTM campaign parameters.
deviceObjectInformation about the device, including id, manufacturer, model, name, type, and version.
ipStringUser's IP address.
libraryObjectInformation about the library making the API calls, including name and version.
localeObjectCurrent user's locale string
locationObjectInformation about user's location, including city, country, latitude, longitude, region, and speed.
networkObjectInformation about user's current device connection, including bluetooth, carrier, cellular, and wifi.
osObjectInformation about user's operating system, including name and version.
pageObjectInformation about the current page of the user's browser, including hash, path, referrer, search, title, and url.
referrerObjectInformation about how the user got to the page, including type, name, url, and link.
screenObjectInformation about the user's device screen, including density, height, and width.
timezoneStringThe timezone the user is located in
traitsObjectCurrent user's traits, defined by Identify calls
userAgentStringUser agent of the user's device.

All of the fields listed in the above table can be populated, but this does not happen automatically for each one. Below is a chart that details which context fields are automatically populated. If there is no check mark, you will have to manually send these variables.

Context FieldWebiOSAndroid
app.namexβœ”βœ”
app.versionxβœ”βœ”
app.buildxβœ”βœ”
campaign.nameβœ”xx
campaign.sourceβœ”xx
campaign.mediumβœ”xx
campaign.termβœ”xx
campaign.contentβœ”xx
device.typexβœ”βœ”
device.idxβœ”βœ”
device.advertisingIdxβœ”βœ”
device.adTrackingEnabledxβœ”βœ”
device.manufacturerxβœ”βœ”
device.modelxβœ”βœ”
device.namexβœ”βœ”
hashβœ”xx
library.nameβœ”βœ”βœ”
library.versionβœ”βœ”βœ”
ipβœ”βœ”βœ”
localexβœ”βœ”
location.latitudexxx
location.longitudexxx
location.speedxxx
network.bluetoothxxβœ”
network.carrierxβœ”βœ”
network.cellularxβœ”βœ”
network.wifixβœ”βœ”
os.namexβœ”βœ”
os.versionxβœ”βœ”
page.pathβœ”xx
page.searchβœ”xx
page.titleβœ”xx
page.urlβœ”xx
screen.densityxxβœ”
screen.heightxβœ”βœ”
screen.widthxβœ”βœ”
searchβœ”xx
titleβœ”xx
traitsxβœ”βœ”
userAgentβœ”xβœ”
urlβœ”xx
timezonexβœ”βœ”