Page updated Jan 16, 2024

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.

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:

Analytics.autoTrack('session', { // REQUIRED, turn on/off the auto tracking enable: true, // OPTIONAL, the attributes of the event, you can either pass an object or a function // which allows you to define dynamic attributes attributes: { attr: 'attr' }, // when using function // attributes: () => { // const attr = somewhere(); // return { // myAttr: attr // } // }, // OPTIONAL, the service provider, by default is the Amazon Pinpoint provider: 'AWSPinpoint' });
1Analytics.autoTrack('session', {
2 // REQUIRED, turn on/off the auto tracking
3 enable: true,
4 // OPTIONAL, the attributes of the event, you can either pass an object or a function
5 // which allows you to define dynamic attributes
6 attributes: {
7 attr: 'attr'
8 },
9 // when using function
10 // attributes: () => {
11 // const attr = somewhere();
12 // return {
13 // myAttr: attr
14 // }
15 // },
16 // OPTIONAL, the service provider, by default is the Amazon Pinpoint
17 provider: 'AWSPinpoint'
18});

When the page is loaded, the Analytics module will send an event to the Amazon Pinpoint Service.

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

To keep backward compatibility, the auto tracking of the session is enabled by default. You can turn it off by:

Analytics.configure({ // OPTIONAL - Allow recording session events. Default is true. autoSessionRecord: false });
1Analytics.configure({
2 // OPTIONAL - Allow recording session events. Default is true.
3 autoSessionRecord: false
4});

or

Analytics.autoTrack('session', { enable: false }); // Note: this must be called before Amplify.configure() or Analytics.configure() to cancel the session_start event
1Analytics.autoTrack('session', {
2 enable: false
3});
4
5// Note: this must be called before Amplify.configure() or Analytics.configure() to cancel the session_start event

Page View Tracking

If you want to track which page/url in your webapp is the most frequently viewed one, you can use this feature. It will automatically send events containing url information when the page is visited.

To turn it on:

Analytics.autoTrack('pageView', { // REQUIRED, turn on/off the auto tracking enable: true, // OPTIONAL, the event name, by default is 'pageView' eventName: 'pageView', // OPTIONAL, the attributes of the event, you can either pass an object or a function // which allows you to define dynamic attributes attributes: { attr: 'attr' }, // when using function // attributes: () => { // const attr = somewhere(); // return { // myAttr: attr // } // }, // OPTIONAL, by default is 'multiPageApp' // you need to change it to 'SPA' if your app is a single-page app like React type: 'multiPageApp', // OPTIONAL, the service provider, by default is the Amazon Pinpoint provider: 'AWSPinpoint', // OPTIONAL, to get the current page url getUrl: () => { // the default function return window.location.origin + window.location.pathname; } });
1Analytics.autoTrack('pageView', {
2 // REQUIRED, turn on/off the auto tracking
3 enable: true,
4 // OPTIONAL, the event name, by default is 'pageView'
5 eventName: 'pageView',
6 // OPTIONAL, the attributes of the event, you can either pass an object or a function
7 // which allows you to define dynamic attributes
8 attributes: {
9 attr: 'attr'
10 },
11 // when using function
12 // attributes: () => {
13 // const attr = somewhere();
14 // return {
15 // myAttr: attr
16 // }
17 // },
18 // OPTIONAL, by default is 'multiPageApp'
19 // you need to change it to 'SPA' if your app is a single-page app like React
20 type: 'multiPageApp',
21 // OPTIONAL, the service provider, by default is the Amazon Pinpoint
22 provider: 'AWSPinpoint',
23 // OPTIONAL, to get the current page url
24 getUrl: () => {
25 // the default function
26 return window.location.origin + window.location.pathname;
27 }
28});

Page Event Tracking

If you want to track user interactions with elements on the page, you can use this feature. All you need to do is attach the specified selectors to your dom element and turn on the auto tracking.

To turn it on:

Analytics.autoTrack('event', { // REQUIRED, turn on/off the auto tracking enable: true, // OPTIONAL, events you want to track, by default is 'click' events: ['click'], // OPTIONAL, the prefix of the selectors, by default is 'data-amplify-analytics-' // in order to avoid collision with the user agent, according to https://www.w3schools.com/tags/att_global_data.asp // always put 'data' as the first prefix selectorPrefix: 'data-amplify-analytics-', // OPTIONAL, the service provider, by default is the Amazon Pinpoint provider: 'AWSPinpoint', // OPTIONAL, the default attributes of the event, you can either pass an object or a function // which allows you to define dynamic attributes attributes: { attr: 'attr' } // when using function // attributes: () => { // const attr = somewhere(); // return { // myAttr: attr // } // } });
1Analytics.autoTrack('event', {
2 // REQUIRED, turn on/off the auto tracking
3 enable: true,
4 // OPTIONAL, events you want to track, by default is 'click'
5 events: ['click'],
6 // OPTIONAL, the prefix of the selectors, by default is 'data-amplify-analytics-'
7 // in order to avoid collision with the user agent, according to https://www.w3schools.com/tags/att_global_data.asp
8 // always put 'data' as the first prefix
9 selectorPrefix: 'data-amplify-analytics-',
10 // OPTIONAL, the service provider, by default is the Amazon Pinpoint
11 provider: 'AWSPinpoint',
12 // OPTIONAL, the default attributes of the event, you can either pass an object or a function
13 // which allows you to define dynamic attributes
14 attributes: {
15 attr: 'attr'
16 }
17 // when using function
18 // attributes: () => {
19 // const attr = somewhere();
20 // return {
21 // myAttr: attr
22 // }
23 // }
24});

For example:

<!-- you want to track this button and send an event when it is clicked --> <button data-amplify-analytics-on="click" data-amplify-analytics-name="click" data-amplify-analytics-attrs="attr1:attr1_value,attr2:attr2_value" />
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:

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

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.