Using Analytics.js to Track Web and Product Events

Analytics.js is a powerful library that can log and categorize web-based events for reporting (example, page visits, product logins, and form-fills on your marketing site.

Analytics.js utilizes 6 different types of API calls to track users. Each call represents a distinct type of semantic information about a user and shares the same common fields.

  • Identify
  • Track
  • Page/Screen
  • Note that, while these are two separate calls, they function in a very similar way. Page calls are used for web sources while screen calls are used for mobile ones.
  • Group
  • Alias

Identify

The identify method is used to associate behavior and to record traits about your users. The call includes a unique User ID and any option traits you know about them (email, name, role, etc.). Implementing identify is one of the first steps you should take in order to get the most out of Astronomer Clickstream.We recommend calling identify at a couple of points:

  • After a user registers
  • After a user logs in
  • When a user updates their info
  • Upon loading any pages that are accessible by a logged-in user

Here’s a sample identify snippet:analytics.identify("1205119", { "name": "Dagny Smith", "email": "dagny@astronomer.io" "plan": "enterprise" });And the resulting payload:{ "type": "identify", "traits": { "name": "Dagny Smith", "email": "dagny@astronomer.io" "plan": "enterprise", }, "userID": "1205119" }As you can see, an identify call has 2 components beyond the common fields:

CaliberMind Identity Method is Used to Associate Behavior and to Record Traits About Your Users

Anonymous and User ID’s

For cases where you don’t actually know who the user is but you still want to be able to associate them to traits, events, or page views, you should use an Anonymous ID.The Anonymous ID can really be any pseudo-unique identifier. Feel free to use any readily available identifier or generate a new random one. UUIDs work great.

Note: Our web and mobile libraries automatically use Anonymous IDs to keep track of users.User IDs are a more permanent and consistent identifier. We recommend including them in your identify calls as often as possible. You are most likely already using a unique identifier to recognize a user in your own database - this identifier is a great UserID.Also, we recommend using something like a database ID over something like an email address or a username as they are more robust and consistent. If you want to track information like email addresses or usernames, send them through as traits instead.

Traits

In an identify call, traits are pieces of information that you know about a user. Traits can really be anything - from email addresses to age or A/B test variations. Some traits are reserved in order to be handled in special ways. These reserved traits should only be used for their intended meanings.

CaliberMind Traits are Pieces of Information that You Know About a User

Track

To record any actions your users perform, along with properties that describe the action, you will want to use a track call. Each of these actions is known as an event, and each of these events has a name. Calling track is one of the first steps towards getting the most out of Analytics.js. Here’s a sample track call:

analytics.track("Viewed Product", { "product": "Cat Feather Toy", "model_number": "B001BOVEU4", "price": "9.99" });

That sample call would yield the following payload:

{ "type": "track", "event": "Viewed Product", "properties": { "model_number": "B001BOVEU4" "price": "9.99" } }

As you can see, a track call has 2 components beyond the common fields:

A CaliberMind Track Call Has Two Components Beyond the Common Fields

Properties

Properties are extra bits of information that you can tie to the events you track and can really be anything. We recommend sending properties as often as possible to give you a more complete picture of what your users are doing. We have reserved some properties that have semantic meanings and are handled in special ways. These reserved properties should only be used for their intended meanings.

CaliberMind Properties are Extra Bits of Information You Can Tie to Events You Track

Page

The page call allows you to record whenever a user sees a page of your website, along with any optional properties you want to include about the page. Calling page or screen is one of the first steps to getting the most out of Analytics.js.

Important - In the analytics.js snippet, a page call is included by default (just after the analytics.load). We do this because this method needs to be called at least once per page load. You have the option of sprucing up the call with a name or properties and can call it multiple times if you have a single-page application. Here’s a sample page call:

analytics.page("Home")And, here’s the corresponding payload:{ "type": "page", "name": "Home", "properties": { "title": "Astronomer: The Platform for Data Engineering", "url": "https://ww.astronomer.io" } }

As you can see, a page call has 2 components beyond the common fields:

A CaliberMind Page Call Has Two Components Beyond the Common Fields

Properties

Properties are extra bits of information that you can tie to the pages you track and can really be anything. We recommend sending properties as often as possible to give you a more complete picture of what your users are doing. We have reserved some properties that have semantic meanings and are handled in special ways. These reserved properties should only be used for their intended meanings.Note: In analytics.js, we automatically send the following properties: title, path,url, referrer, and search.

CaliberMind Properties are Extra Bits of Information You can Tie to Pages You Track

Group

Use the group call when you want to associate an individual user with a group - a company, organization, account, team, etc. While a user can be in more than one group, not all platforms support multiple groups. This method also lets you record custom traits about the group. Calling group is slightly more advanced than identify, track, or page, but it’s pretty useful if you have accounts with multiple users.

Here’s a sample group call: analytics.group("ak9g2hgpcf",{ "name": "Astronomer", "industry": "Technology", "employees": "48" });And the corresponding payload:{ "type": "Group", "groupID": "ak9g2hgpcf", "traits": { "name": "Astronomer", "industry": "Technology", "employees": "48" } }As you can see, a group call has 2 components beyond the common fields:

A CaliberMind Group Call Lets You Associate an Individual User with a Group

Group ID

A Group ID is the unique identifier by which you recognize a group in your database.

Traits

Traits are extra bits of information that you can tie to the pages you track and can really be anything.We have reserved some traits to be handled in special ways. These reserved traits should only be used for their intended meanings.

CaliberMind Traits are Extra Bits of Information You can Tie to the Pages You Track

Alias

The alias method is used to merge two user identities, effectively connecting two sets of user data as one. Calling alias is slightly more advanced than identify, track, or page, but it’s required to manage user identities successfully in some of our destinations.Here’s a sample alias:analytics.alias("k9jlquh2ew");And the resulting payload:{ "type": "alias", "previousId": "dagny@astronomer.io", "userId": "k9jlquh2ew" }

Previous ID

The previousId is the existing ID that you’ve already referred to the user by. This could be an Anonymous ID that was assigned to the user or a User ID that you’ve previously identified them with in identify.

User ID

The UserId string will either be the user’s new identity or an existing identity that you wish to merge with the previousId.

Common Fields of API Calls

Every API call has a common structure. While some specific calls pass extra information, they will all pass the information detailed in this document. Note, that while the system will send 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": "Astronomer", "version": "123", "build": "1.1.1.123", "namespace": "com.production.astronomer" }, "campaign": { "name": "Astronomer 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.5120, "speed": 0 }, "network": { "bluetooth": false, "carrier": "Verizon", "cellular": true, "wifi": true }, "os": { "name": "iPhone OS", "version": "8.1.3" }, "page": { "path": "/", "referrer": "", "search": "", "title": "Astronomer", "url": "https://www.astronomer.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.

Sample CaliberMind Fields Chart

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.

CaliberMind Context Field Provides Other Information You can Gather to Offer Useful Context about a Data Point

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.

All CaliberMind Fields Listed can Be Populated, But Not Automatically for Each One

How did we do?

Analytics.JS Overview

How Cookie Settings Affect the Analytics.JS Tracking Script

Contact