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. Set up your first MetaRouter Cluster
  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. We've built a spreadsheet that you can get started with here, or you can use your own planner. 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.

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"
   "providers": {
     "google": {
        "glcid": "123abc"
     }
     "bing": {
       "mid": "xyz456"
       "msclkid": "789dcef"
     }
   }
    },
    "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/"
    },
    "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.

Field

Type

Description

anonymousId

Object (optional)

A pseudo-unique substitute for User ID. This is for cases when you don't have an absolutely unique identifier.

context

Object (optional)

Dictionary of extra information that provides useful context about a message that is not directly related to the API call

integrations

String (optional)

Dictionary of destinations to either enable or disable

messageId

String (implicit)

Automatically collected, this is a unique identifier for each message that lets you find an individual message across the API

receivedAt

Date (implicit)

The timestamp of when a message is received by MetaRouter

sentAt

Date (optional)

The timestamp of when a message is sent to MetaRouter

type

String (implicit)

Type of message, according to the Event method

userId

String (required)

Unique string that identifies a user in your database

version

Number (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 a data point. You should only use these fields for their intended meaning; they are complete and explicit specifications.

Field

Type

Description

active

String

Tells whether a user is active. This can be used to flag an identify call to update its traits

app

Object

Information about the current application, including name, version, and build.

campaign

Object

Information 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.

device

Object

Information about the device, including id, manufacturer, model, name, type, and version.

ip

String

User's IP address.

library

Object

Information about the library making the API calls, including name and version.

locale

Object

Current user's locale string

location

Object

Information about user's location, including city, country, latitude, longitude, region, and speed.

network

Object

Information about user's current device connection, including bluetooth, carrier, cellular, and wifi.

os

Object

Information about user's operating system, including name and version.

page

Object

Information about the current page of the user's browser, including hash, path, referrer, search, title, and url.

referrer

Object

Information about how the user got to the page, including type, name, url, and link.

screen

Object

Information about the user's device screen, including density, height, and width.

timezone

String

The timezone the user is located in

traits

Object

Current user's traits, defined by Identify calls

userAgent

String

User 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 Field

Web

iOS

Android

app.name

x

app.version

x

app.build

x

campaign.name

x

x

campaign.source

x

x

campaign.medium

x

x

campaign.term

x

x

campaign.content

x

x

device.type

x

device.id

x

device.advertisingId

x

device.adTrackingEnabled

x

device.manufacturer

x

device.model

x

device.name

x

hash

x

x

library.name

library.version

ip

locale

x

location.latitude

x

x

x

location.longitude

x

x

x

location.speed

x

x

x

network.bluetooth

x

x

network.carrier

x

network.cellular

x

network.wifi

x

os.name

x

os.version

x

page.path

x

x

page.search

x

x

page.title

x

x

page.url

x

x

screen.density

x

x

screen.height

x

screen.width

x

search

x

x

title

x

x

traits

x

userAgent

x

url

x

x

timezone

x