awslabs/clickstream-web

Web SDK for Clickstream Analytics on AWS

AWS Solution Clickstream Analytics SDK for Web

Introduction

Clickstream Web SDK can help you easily collect and report events from browser to AWS. This SDK is part of an AWS solution - Clickstream Analytics on AWS, which provisions data pipeline to ingest and process event data into AWS services such as S3, Redshift.

The SDK relies on the Amplify for JS SDK Core Library and is developed according to the Amplify AnalyticsProvider interface. In addition, we've added features that automatically collect common user events and attributes (e.g., page view, first open) to simplify data collection for users.

Visit our Documentation site to learn more about Clickstream Web SDK.

Integrate SDK

Include SDK

npm install @aws/clickstream-web

Initialize the SDK

Copy your configuration code from your clickstream solution web console, we recommended you add the code to your app's root entry point, for example index.js/app.tsx in React or main.ts in Vue/Angular, the configuration code should look like as follows. You can also manually add this code snippet and replace the values of appId and endpoint after you registered app to a data pipeline in the Clickstream Analytics solution console.

import { ClickstreamAnalytics } from '@aws/clickstream-web';

ClickstreamAnalytics.init({
   appId: "your appId",
   endpoint: "https://example.com/collect",
});

Your appId and endpoint are already set up in it.

Start using

Record event

Add the following code where you need to record event.

import { ClickstreamAnalytics } from '@aws/clickstream-web';

// record event with attributes
ClickstreamAnalytics.record({
  name: 'button_click',
  attributes: {
    event_category: 'shoes',
    currency: 'CNY',
    value: 279.9,
  }
});

//record event with name
ClickstreamAnalytics.record({ name: 'button_click' });

Login and logout

import { ClickstreamAnalytics } from '@aws/clickstream-web';

// when user login success.
ClickstreamAnalytics.setUserId("UserId");

// when user logout
ClickstreamAnalytics.setUserId(null);

Add user attribute

ClickstreamAnalytics.setUserAttributes({
  userName:"carl",
  userAge: 22
});

When opening for the first time after integrating the SDK, you need to manually set the user attributes once, and current login user's attributes will be cached in localStorage, so the next time browser open you don't need to set all user's attribute again, of course you can use the same api ClickstreamAnalytics.setUserAttributes() to update the current user's attribute when it changes.

Add global attribute

1. Add global attributes when initializing the SDK

   The following example code shows how to add traffic source fields as global attributes when initializing the SDK.

   import { ClickstreamAnalytics, Attr } from '@aws/clickstream-web';
   
   ClickstreamAnalytics.init({
      appId: "your appId",
      endpoint: "https://example.com/collect",
      globalAttributes:{
        [Attr.TRAFFIC_SOURCE_SOURCE]: 'amazon',
        [Attr.TRAFFIC_SOURCE_MEDIUM]: 'cpc',
        [Attr.TRAFFIC_SOURCE_CAMPAIGN]: 'summer_promotion',
        [Attr.TRAFFIC_SOURCE_CAMPAIGN_ID]: 'summer_promotion_01',
        [Attr.TRAFFIC_SOURCE_TERM]: 'running_shoes',
        [Attr.TRAFFIC_SOURCE_CONTENT]: 'banner_ad_1',
        [Attr.TRAFFIC_SOURCE_CLID]: 'amazon_ad_123',
        [Attr.TRAFFIC_SOURCE_CLID_PLATFORM]: 'amazon_ads',
      }
   });

2. Add global attributes after initializing the SDK

   import { ClickstreamAnalytics, Attr } from '@aws/clickstream-web';
   
   ClickstreamAnalytics.setGlobalAttributes({
     [Attr.TRAFFIC_SOURCE_MEDIUM]: "Search engine",
     level: 10,
   });

It is recommended to set global attributes when initializing the SDK, global attributes will be included in all events that occur after it is set, you also can remove a global attribute by setting its value to null.

Record event with items

You can add the following code to log an event with an item.

Note: Only pipelines from version 1.1+ can handle items with custom attribute.

import { ClickstreamAnalytics, Item, Attr } from '@aws/clickstream-web';

const itemBook: Item = {
  id: '123',
  name: 'Nature',
  category: 'book',
  price: 99,
  book_publisher: "Nature Research",
};
ClickstreamAnalytics.record({
  name: 'view_item',
  attributes: {
    [Attr.CURRENCY]: 'USD', 
    [Attr.VALUE]: 99,
    event_category: 'recommended',
  },
  items: [itemBook],
});

Send event immediate in batch mode

When you are in batch mode, you can still send an event immediately by setting the isImmediate attribute, as in the following code:

import { ClickstreamAnalytics } from '@aws/clickstream-web';

ClickstreamAnalytics.record({
  name: 'button_click',
  isImmediate: true,
});

Other configurations

In addition to the required appId and endpoint, you can configure other information to get more customized usage:

import { ClickstreamAnalytics, EventMode, PageType } from '@aws/clickstream-web';

ClickstreamAnalytics.init({
   appId: "your appId",
   endpoint: "https://example.com/collect",
   sendMode: EventMode.Batch,
   sendEventsInterval: 5000,
   isTrackPageViewEvents: true,
   isTrackUserEngagementEvents: true,
   isTrackClickEvents: true,
   isTrackSearchEvents: true,
   isTrackScrollEvents: true,
   isTrackPageLoadEvents: true,
   isTrackAppStartEvents: true,
   isTrackAppEndEvents: true,
   pageType: PageType.SPA,
   isLogEvents: false,
   authCookie: "your auth cookie",
   sessionTimeoutDuration: 1800000,
   idleTimeoutDuration: 120000,
   searchKeyWords: ['product', 'class'],
   domainList: ['example1.com', 'example2.com'],
});

Here is an explanation of each property:

• appId (Required): the app id of your project in control plane.
• endpoint (Required): the endpoint path you will upload the event to AWS server.
• sendMode: EventMode.Immediate, EventMode.Batch, default is Immediate mode.
• sendEventsInterval: event sending interval millisecond, works only bath send mode, the default value is 5000
• isTrackPageViewEvents: whether auto record page view events in browser, default is true
• isTrackUserEngagementEvents: whether auto record user engagement events in browser, default is true
• isTrackClickEvents: whether auto record link click events in browser, default is true
• isTrackSearchEvents: whether auto record search result page events in browser, default is true
• isTrackScrollEvents: whether auto record page scroll events in browser, default is true
• isTrackPageLoadEvents: whether auto record page load performance events in browser, default is false
• isTrackAppStartEvents: whether auto record app start events in browser when pages becomes visible, default is false
• isTrackAppEndEvents: whether auto record app end events in browser when pages becomes invisible, default is false
• pageType: the website type, SPA for single page application, multiPageApp for multiple page application, default is SPA. This attribute works only when the attribute isTrackPageViewEvents's value is true
• isLogEvents: whether to print out event json for debugging, default is false.
• authCookie: your auth cookie for AWS application load balancer auth cookie.
• sessionTimeoutDuration: the duration for session timeout millisecond, default is 1800000
• idleTimeoutDuration: the maximum duration of user inactivity before triggering an idle state, default is 120000 millisecond, Any idle duration exceeding this threshold will be removed in the user_engagement events on the current page.
• searchKeyWords: the customized Keywords for trigger the _search event, by default we detect q, s, search, query and keyword in query parameters.
• domainList: if your website cross multiple domain, you can customize the domain list. The _outbound attribute of the _click event will be true when a link leads to a website that's not a part of your configured domain.

Configuration update

You can update the default configuration after initializing the SDK, below are the additional configuration options you can customize.

import { ClickstreamAnalytics } from '@aws/clickstream-web';

ClickstreamAnalytics.updateConfigure({
  isLogEvents: true,
  authCookie: 'your auth cookie',
  isTrackPageViewEvents: false,
  isTrackUserEngagementEvents: false,
  isTrackClickEvents: false,
  isTrackScrollEvents: false,
  isTrackSearchEvents: false,
  isTrackPageLoadEvents: false,
  isTrackAppStartEvents: true,
  isTrackAppEndEvents: true,
});

Implementing Clickstream Web SDK in Google Tag Manager Using Template

1. Download the Clickstream SDK template file (.tpl) from the SDK Release Page.

2. Refer to the Google Tag Manager Import Guide for instructions on importing the .tpl file as a custom template in your tag manager console.

3. Refer to the Use your new tag to add ClickstreamAnalytics tag to your container.

4. The ClickstreamAnalytics tag currently supports four tag types:

   • Initialize SDK
   • Record Custom Event
   • Set User ID
   • Set User Attribute

   Note: Ensure that you initialize the SDK tag first before use other ClickstreamAnalytics tag types.

How to integrate and test locally

Integrate the .tgz file

Clone this repository locally and execute the following script to generate aws-clickstream-web-0.12.0.tgz zip package, which will be located in the project root folder.

cd clickstream-web && npm i && npm run pack

Copy the aws-clickstream-web-0.12.0.tgz into your project, then execute the script in your project root folder to install the SDK.

npm install ./aws-clickstream-web-0.12.0.tgz

Note: Please correct the SDK version and change the path to where the aws-clickstream-web-0.12.0.tgz file is located.

Integrate the clickstream-web.min.js file

Execute the following script to generate clickstream-web.min.js, located in the /dist folder.

cd clickstream-web && npm i && npm run pack

Copy the clickstream-web.min.js into your project and add the following initial code into your index.html.

<script src="clickstream-web.min.js"></script>
<script>
    window.ClickstreamAnalytics.init({
        appId: 'your appId',
        endpoint: 'https://example.com/collect',
        isLogEvents: true,
        pageType: window.PageType.SPA, //multiPageApp
        sendMode: window.SendMode.Batch, //Immediate
    })
</script>

You can also find the clickstream-web.min.js file in the Release page.

Test

npm run test

Security

See CONTRIBUTING for more information.

License

This library is licensed under the Apache 2.0 License.

clickstream-web's Issues

`package.json` `"main"` key has wrong file name

Describe the bug

The file path for "main" in package.json should be ./lib/index.js

Steps To Reproduce

- create a directory for reproduction and `cd` into it
- `yarn init -y`
- `yarn add @aws/clickstream-web`
- put the following in `index.js`:

const clickstream = require('@aws/clickstream-web')
console.debug(clickstream)

- run `node index.js`

Observe that the program crashes.

Expected behavior

The program outlined in the reproduction steps should successfully run to completion.

The fix is to update "main" to point to ./lib/index.js

Clickstream-Web Version

0.10.0

Node version

v20.11.0

TypeScript version

N/A

Relevant log output

<details>
<summary>Log Messages</summary>


INSERT LOG MESSAGES HERE

```

Is this a regression?

Yes

Regression additional context

No response

Browser

N/A

Additional context

Here is the output of the reproduction program:

node:internal/modules/cjs/loader:452
      throw err;
      ^

Error: Cannot find module '/Users/harrison.marshall/Developer/reproduce-clickstream-issue/node_modules/@aws/clickstream-web/lib/index.ts'. Please verify that the package.json has a valid "main" entry
    at tryPackage (node:internal/modules/cjs/loader:444:19)
    at Module._findPath (node:internal/modules/cjs/loader:715:18)
    at Module._resolveFilename (node:internal/modules/cjs/loader:1130:27)
    at Module._load (node:internal/modules/cjs/loader:985:27)
    at Module.require (node:internal/modules/cjs/loader:1235:19)
    at require (node:internal/modules/helpers:176:18)
    at Object.<anonymous> (/Users/harrison.marshall/Developer/reproduce-clickstream-issue/index.js:1:21)
    at Module._compile (node:internal/modules/cjs/loader:1376:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1435:10)
    at Module.load (node:internal/modules/cjs/loader:1207:32) {
  code: 'MODULE_NOT_FOUND',
  path: '/Users/harrison.marshall/Developer/reproduce-clickstream-issue/node_modules/@aws/clickstream-web/package.json',
  requestPath: '@aws/clickstream-web'
}