Automatically track sessions

Analytics Auto Tracking helps you to automatically track user behaviors like sessions start/stop, page view change and web events like clicking or mouseover.

The Auto Tracking feature is only supported when you have Amazon Pinpoint configured for Amplify Analytics.

Session Tracking

You can track the session both in a web app or a React Native app by using Analytics. A web session can be defined in different ways. To keep it simple we define a web session as being active when the page is not hidden and inactive when the page is hidden. A session in a React Native app is active when the app is in the foreground and inactive when the app is in the background.

For example:

1import { configureAutoTrack } from 'aws-amplify/analytics';
2
3configureAutoTrack({
4  // REQUIRED, turn on/off the auto tracking
5  enable: true,
6  // REQUIRED, the event type, it's one of 'event', 'pageView' or 'session'
7  type: 'session',
8  // OPTIONAL, additional options for the tracked event.
9  options: {
10    // OPTIONAL, the attributes of the event
11    attributes: {
12      customizableField: 'attr'
13    }
14  }
15});

By default, when the page/app transitions to the foreground, the Analytics module will send an event to the Amazon Pinpoint Service.

1{
2  "eventType": "_session_start",
3  "attributes": {
4    "customizableField": "attr"
5  }
6}

This behavior can be disabled by calling configureAutoTrack:

1import { configureAutoTrack } from 'aws-amplify/analytics';
2
3configureAutoTrack({
4  enable: false,
5  type: 'session'
6});

Page View Tracking

Use this feature to track the most frequently viewed page/url in your webapp. It automatically sends events containing url information when a page is visited.

This behavior can be enabled by calling configureAutoTrack:

1import { configureAutoTrack } from 'aws-amplify/analytics';
2
3configureAutoTrack({
4  // REQUIRED, turn on/off the auto tracking
5  enable: true,
6  // REQUIRED, the event type, it's one of 'event', 'pageView' or 'session'
7  type: 'pageView',
8  // OPTIONAL, additional options for the tracked event.
9  options: {
10    // OPTIONAL, the attributes of the event
11    attributes: {
12      customizableField: 'attr'
13    },
14
15    // OPTIONAL, the event name. By default, this is 'pageView'
16    eventName: 'pageView',
17
18    // OPTIONAL, the type of app under tracking. By default, this is 'multiPageApp'.
19    // You will need to change it to 'singlePage' if your app is a single-page app like React
20    appType: 'multiPageApp',
21
22    // OPTIONAL, provide the URL for the event.
23    urlProvider:  () => {
24      // the default function
25      return window.location.origin + window.location.pathname;
26    }
27  }
28});

This behavior can be disabled by calling configureAutoTrack:

1import { configureAutoTrack } from 'aws-amplify/analytics';
2
3configureAutoTrack({
4  enable: false,
5  type: 'pageView'
6});

Page Event Tracking

Use this type of tracking to track user interactions with specific elements on a page. Just attach the specified selectors to your DOM element and turn on the auto tracking.

This behavior can be enabled by calling configureAutoTrack:

1import { configureAutoTrack } from 'aws-amplify/analytics';
2
3configureAutoTrack({
4  // REQUIRED, turn on/off the auto tracking
5  enable: true,
6  // REQUIRED, the event type, it's one of 'event', 'pageView' or 'session'
7  type: 'event',
8  // OPTIONAL, additional options for the tracked event.
9  options: {
10    // OPTIONAL, the attributes of the event
11    attributes: {
12      customizableField: 'attr'
13    },
14    // OPTIONAL, events you want to track. By default, this is 'click'
15    events: ['click'],
16
17    // OPTIONAL, the prefix of the selectors. By default, this is 'data-amplify-analytics-'
18    // Per https://www.w3schools.com/tags/att_global_data.asp, always start
19    // the prefix with 'data' to avoid collisions with the user agent
20    selectorPrefix: 'data-amplify-analytics-'
21  }
22});

For example:

1<!-- you want to track this button and send an event when it is clicked -->
2<button
3  data-amplify-analytics-on="click"
4  data-amplify-analytics-name="click"
5  data-amplify-analytics-attrs="attr1:attr1_value,attr2:attr2_value"
6/>

When the button above is clicked, an event will be sent automatically. This is equivalent to doing:

1<script>
2  import { record } from 'aws-amplify/analytics';
3  var sendEvent = function() {
4    record({
5      name: 'click',
6      attributes: {
7        attr: 'attr', // the default ones
8        attr1: attr1_value, // defined in the button component
9        attr2: attr2_value // defined in the button component
10      }
11    });
12  };
13</script>
14<button onclick="sendEvent()" />

This behavior can be disabled by calling configureAutoTrack:

1import { configureAutoTrack } from 'aws-amplify/analytics';
2
3configureAutoTrack({
4  enable: false,
5  type: 'event'
6});

Note: Amplify doesn't capture the location automatically. Instead, you can add the location information in the default config when you configure Analytics or while updating the end point.

Identify user

Enable and disable analytics