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
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.
- Installing Analytics.js for Web
- Analytics.js for iOS
- Analytics.js for Android
- Server SDKs- please reach out for more information.
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.
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 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.
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 | ✔ | ✔ |
Updated 5 months ago