Overview

Analytics.js contains a series of event methods that will track almost any action occurring on a web, mobile or other application. These methods are compatible with any Analytics.js data source, and will replace traditional, often similarly named, event methods and functions that third party vendors offer.

Page

Page calls are the only event types that are recorded by default when you install MetaRouter sources on your website/app. These are the foundation of most tracking plans, as anyone familiar with analytics or marketing is familiar with how they function. Think about Google Analytics- soon after you place their code on your site, you'll start seeing data about the pages your users are visiting, where they are located geographically (inferred from IP addresses), and you can even configure conversion events based on page URLs.

This all functions because their code grabs information about the page your users are on. Our snippet replicates this action, as page events can easily grab information about the webpage a user is on with minimal manual configuration.

Your event schema should encompass much more than the data that page calls can grab, but page calls are a great place to start if you haven't set up your other event types, such as identify and track. Page events will contain the name of the page as the event name, and will contain a set of properties about the page as well.

These are the fields that a page call will include outside of common fields:

Page Event Template

Page events follow this format:

analytics.page([category], [name], [properties], [options], [callback]);

Examples

Here is an example of a page call in Javascript (keep in mind this is automatically triggered by default for the analytics.js snippet):

analytics.page("MetaRouter Homepage")

Analytics.js will populate fields based on information available from the browser. Here is an example payload, common fields removed:

{
  "type": "page",
  "name": "MetaRouter Homepage",
  "properties": {
    "title": "MetaRouter: Fast, Flexible and Secure Data Routing",
    "url": "http://www.metarouter.io/home"
  }
}

This is what the event looks like, including common fields:

{
  "anonymousId": "e1d6bae1-ec1d-420d-8c6b-aae36364d731",
  "messageId": "c9a62350-c9aa-4600-97d1-13743dc21624",
  "sentAt": "2020-12-10T19:17:19.495Z",
  "receivedAt": "2020-12-10T19:17:19.484Z",
  "type": "page",
  "originalTimestamp": "2020-12-10T19:17:19.471Z",
  "userId": "5da8c9e33026b556271393dc",
  "writeKey": "mE8RXK5djcKPyQhipPFTZ",
  "context": {
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36",
    "library": {
      "name": "analytics.js",
      "version": "3.2.34"
    },
    "page": {
      "path": "/home",
      "title": "MetaRouter: Fast, Flexible and Secure Data Routing",
      "url": "https://www.metarouter.io/home"
    },
    "ip": "71.196.228.000"
  },
  "host": null,
  "integrations": {},
  "properties": {
    "path": "/home",
    "referrer": "https://www.g2.com",
    "search": "",
    "title": "MetaRouter: Fast, Flexible and Secure Data Routing",
    "url": "https://www.metarouter.io/home"
  },
  "timestamp": "2020-12-10T19:17:19.46Z"
}

Overriding Fields

You can override fields that are typically automatically populated by setting them in your calls. For the example above, your event call could be:

analytics.page('MetaRouter Homepage', {
  title: 'MetaRouter: Fast, Flexible and Secure Data Routing',
  url: 'http://www.metarouter.io/home',
  path: '/',
  referrer: 'https://www.g2.com'
});

Identity

For more information on Anonymous ID and User ID, check out our Identify documentation. Anonymous IDs will automatically be appended to your page event payload for anonymous tracking, and User IDs will be appended if a user has been identified before a page call occurs.

Page Fields

Properties

Properties represent any additional information you might want to track about the pages that your users visit.

We automatically send title, path, url. referrer and search properties with your page events. You may also notice that there is overlap with page properties and context properties of other events, like track events. The information contained in these calls is somewhat similar and helps with analyzing other event types.

Common additional properties to include with you page events are UTM parameters that help determine how a user got to the page and what marketing/advertising campaign might have brought the user to the site.

Screen

A screen call is a mobile-specific type of event that is analogous to a page call, which you can read more about here. It contains similar types of data, but works for tracking navigation across mobile app screens.

Our Mobile SDKs can automatically track screen calls based on a configuration setting. You'll notice during implementation a specific function called .recordScreenViews. If this is enabled, you will begin automatically recording screen events with your implementation of the SDK. This is a great way to get started with mobile event tracking!

Screen calls include these fields:

Examples

The implementation of a screen call will differ based on what language you are developing for. Here's how you'd make that call with the iOS development language, Objective-C:

[[SEGAnalytics sharedAnalytics] screen:@"Game Start"
properties:@{ @"category": @"puzzle" }];

This call would result in this payload, with common fields removed:

{
  "type": "screen",
  "name": "Game Start",
  "properties": {
    "category": "puzzles"
  }
}

Identity

For more information on Anonymous ID and User ID, check out our Identify documentation. Anonymous IDs will automatically be appended to your screen event payload for anonymous tracking, and User IDs will be appended if a user has been identified before a screen call occurs.

Track

Track calls represent what many analysts and marketers refer to as “custom events”- anything that a user might interact with on a page. These go deeper than page or screen calls, which only record information when a user navigates to a new URL or app screen. Track events are useful for recording button clicks, video plays, module opens/closes, and much more depending on how you have set up your property. While much information can be inferred about a user based on the URL or screen they are interacting with and its contents, track calls are essential to creating a robust dataset that describes how users are interacting with individual components of a given page or screen.

Each track event should contain a descriptive name for the action it represents (noun and past-tense names like “product ordered” work well), and should contain a set of key properties you may want to track. For example, if someone clicks a button called “See Demo”, you can include properties about that button like the color, copy variations, and placement on the page if A/B testing. If it's a “product_added” event, you could easily include information about the product- its name, SKU, category, and more. Make sure your event names and properties are descriptive enough that someone other than yourself can decipher what they represent.

A track call contains these fields in addition to common fields:

Track Event Template

Track events follow this format:

analytics.track(event, [properties], [options], [callback]);

NOTE - We recommend using snake_case naming conventions for the data schema used within our system in order to match the logic our system will automatically apply. See the below section for more details.

Automatic Track Event Name Sanitization

The MetaRouter Platform will sanitize all custom Track event names to become snake_case. This operation will also sanitize names with the following logic in this specific order.

1. Removing special characters and spaces.
2. Removing duplicate underscores
3. Removing leading or trailing underscores

For example, Application Opened will become application_opened and _H@llo___W$rld! will become hllo_wrld

Examples

Here's an example of a track call looks like with common fields removed (in Javascript):

analytics.track('product_viewed', {
	product_name: 'Cat Feather Toy',
	model_number: 'B001BOVEU4',
	sku: '123ABC',
	category: 'cats'
})

The above function would result in this payload:

{
  "type": "track",
  "event": "product_viewed",
  "properties": {
    "product_name": "Cat Feather Toy",
    "model_number": "B001BOVEU4",
    "sku": "123ABC",
    "category": "cats"
  }
}

And here's what a track calls looks like containing common fields:

{
  "anonymousId": "509a2cba-909a-4b24-89c8-96c825eb35a8", //unique identifier for every visitor
  "properties": {
    "product_name": "Cat Feather Toy",
    "model_number": "B001BOVEU4",
    "sku": "123ABC",
    "category": "cats"
  },
  "messageId": "417d072f-6405-4a97-892a-14347d5dec23",
  "sentAt": "2020-12-09T23:13:05.674Z",
  "receivedAt": "2020-12-09T23:13:06.469Z",
  "type": "identify",
  "originalTimestamp": "2020-12-09T23:13:05.672Z",
  "userId": "7b32d59f-467b-4758-87a8-7d7396b59699",
  "writeKey": "YOUR_WRITE_KEY",
  "context": {
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36 Edg/87.0.664.57",
    "library": {
      "name": "analytics.js",
      "version": "3.2.19"
    },
    "page": {
      "path": "/cat-feather-toy",
      "referrer": "https://amazon.com",
      "title": "Cat Feather Toy",
      "url": "https://catstore.com/cat-feather-toy"
    },
    "ip": "125.7.20.000"
  },
  "host": null,
  "integrations": {},
  "timestamp": "2020-12-09T23:13:06.467Z"
}

Identity

For more information on Anonymous ID and User ID, check out our Identify documentation. Anonymous IDs will automatically be appended to your track event payload for anonymous tracking, and User IDs will be appended if a user has been identified before a track call occurs.

Track Fields

Properties

As mentioned above, properties are key pieces of information that describe your track events and help you understand everything you might need to know about that event, such as A/B testing variables.

Helper Methods

Analytics.js contains two helper methods, trackLink and trackForm.

trackLink

trackLink attaches to a track call as a handler to a link. This method will insert a short 300ms timeout, which gives the track call more time to execute. This can be helpful where a page redirects before the track call can complete all of its requests.

trackLink Template

analytics.trackLink(element, event, [properties])

trackLink Example

var url = document.getElementById('enterprise-demo-link');

analytics.trackLink(url, 'enterprise_demo_viewed', {
  plan: 'Enterprise'
});

trackForm

trackForm adds a track call trigger to a specific form submission. This method will insert a short 300ms timeout, which gives the track call more time to execute. This can be helpful where a page redirects before the track call can complete all of its requests.

trackLink Template

analytics.trackForm(form, event, [properties])

trackForm Example

var formFill = document.getElementById('learn-more-submission');

analytics.trackForm(formFill, 'Learn More Submitted', {
  plan: 'Enterprise',
});

Identify

Identify calls are an incredibly important aspect of any analytics.js implementation where the known identity of a user is crucial, such as for product analytics, data science, customer success tools, and more. While not all tools require identity (such as common digital advertising platforms or Google Analytics), your analytics capabilities will be hindered if you cannot tie a set of behaviors to specific user profiles.

The identify call signals the end of the anonymous user journey and the beginning of the known user journey. A common case in this instance would of course be a user sign up, where a prospect hands over an email address, first/last name, company, and other crucial information required by, for example, a SaaS demo or e-commerce cart checkout. By associating a common identifier such as a user_id on a known email or other identifier, you can easily track your customers' and prospects' behaviors on your website or app and leverage that for use in one of the many tools located in our destination library.

Common triggers for an identify call are:

• An account/user registration
• Every subsequent login
• Account/user updates their profile
• A user accesses a gated portion of your website/app

While you can send data into your tools using page calls that are automatically generated when our snippet is loaded, you'll want to quickly get started on implementing your first identify events if you want to perform any advanced user behavior analysis. Here's how you can get started.

Identify Event Template

Identify events follow this format:

analytics.identify([userId], [traits], [options], [callback]);

Examples

You'll want to trigger an analytics.identify call that will track critical information about the user using this javascript function:

analytics.identify("509a2cba-909a-4b24-89c8-96c825eb35a8", {
	name: "Jerry Seinfeld",
	email: "[email protected]",
	plan: "enterprise",
	logins: 26
});

Which would result in this payload (with common fields removed, which we discuss here):

{
  "type": "identify",
  "traits": {
    "name": "Jerry Seinfeld",
    "email": "[email protected]",
    "plan": "enterprise",
    "logins": 26
  },
  "userId": "1234abcd5678"
}

So you can see an identify payload with common fields:

{
  "anonymousId": "509a2cba-909a-4b24-89c8-96c825eb35a8",
  "traits": {
    "name": "Jerry Seinfeld",
    "email": "[email protected]",
    "plan": "enterprise",
    "logins": 26
  },
  "messageId": "417d072f-6405-4a97-892a-14347d5dec23",
  "sentAt": "2020-12-09T23:13:05.674Z",
  "receivedAt": "2020-12-09T23:13:06.469Z",
  "type": "identify",
  "originalTimestamp": "2020-12-09T23:13:05.672Z",
  "userId": "7b32d59f-467b-4758-87a8-7d7396b59699",
  "writeKey": "YOUR_WRITE_KEY",
  "context": {
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36 Edg/87.0.664.57",
    "library": {
      "name": "analytics.js",
      "version": "3.2.19"
    },
    "page": {
      "path": "/pricing",
      "referrer": "https://g2.com",
      "title": "MetaRouter Pricing",
      "url": "https://metarouter.io/pricing"
    },
    "ip": "125.7.20.000"
  },
  "host": null,
  "integrations": {},
  "timestamp": "2020-12-09T23:13:06.467Z"
}

Identify Fields

We'll break down a few of the fields listed above. Please note that a User ID or Anonymous ID must be included with every event. An Anonymous ID will be generated automatically for client-side events, but please be aware of this requirement when sending events server-side.

Anonymous ID

MetaRouter leverages a UUID4-formatted, anonymous ID for user identification and attribution with its libraries. This ID is set as a first-party cookie (on web), 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 for integrations that require an identity sync.

It is also important to note that every one of MetaRouter's SDKs generate their own anonymous IDs for the user. Most CDPs and attribution platforms will allow for sending and centralizing 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.

User ID

A User ID is a permanent value that should be unique to each user and stored in your database. We recommend generating this value via UUID-4 or deriving it from your own database. This value is different than anonymous IDs because while it still is a randomly generated number, it should be associated to known identifiers like an email once that information is shared with you by your users.

We don't recommend simply using the known identifier as a User ID, as these can change (e.x. someone switches email addresses). That way, if information changes about a user, you can continue to stitch together their profile with the common User ID.

Traits

Traits are, in essence, analogous to track event properties in that they are made up of highly customizable fields, such as the name of your user, their email, physical address, subscription type, and so on. Anything about a user that you might want to append to their profile, you can include as a trait.

Group

Group calls are a more advanced kind of call that associate an individual user with a group- such as an organization, company, account, etc. This is especially useful for B2B analytics, where you'll likely want to analyze data on an account-by-account basis. Being able to aggregate individual user actions underneath an account will help you take a holistic approach to utilizing your data. There are many other use cases for Group calls as well.

Examples

In order to place a user into a group, you can make this Javascript call:

analytics.group("5e8c91ea9d91a7b8185e8645", {
	name: "Sterling Cooper",
	industry: "Advertising",
	employees: 63,
	plan: "premium",
});

Which would result in this payload, without common fields:

{
  "type": "group",
  "groupId": "5e8c91ea9d91a7b8185e8645",
  "traits": {
    "name": "Sterling Cooper",
    "industry": "Advertising",
    "employees": 63,
    "plan": "premium"
  }
}

Identity

For more information on Anonymous ID and User ID, check out our Identify documentation. Anonymous IDs will automatically be appended to your group event payload for anonymous tracking, and User IDs will be appended if a user has been identified before a group call occurs. The Group ID is a unique ID that your database should recognize.

Traits

Similar to identify events, traits are the extra pieces of information you wish to know about the group you are identifying- its physical address, associated phone numbers and emails, and anything else you might wish to associate with a given group.