Table of Contents
Types of Analytics.js Calls
Types of Analytics.js Call
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 (CaliberMind doesn't yet support "Alias" calls.)
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 identity 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:
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.
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:
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.
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:
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.
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:
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.
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 previous Id is the existing ID that you’ve already referred to the user. This could be an Anonymous ID that was assigned to the user or a User ID that you’ve previously identified them within 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 previous Id.
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.
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.
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.
