Skip to content


AWS Solution Clickstream Analytics SDK for Android

Maven Central


Clickstream Android SDK can help you easily collect and report in-app events from Android devices 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 Android SDK Core Library and is developed according to the Amplify Android SDK plug-in specification. In addition, we've added features that automatically collect common user events and attributes (e.g., screen view, first open) to simplify data collection for users.

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

Platform Support

Clickstream Android SDK supports Android 4.1 (API level 16) and later.

Integrate SDK

1.Include SDK

Add the following dependency to your app module's build.gradle file.

dependencies {
    implementation ''

then sync your project, if you have problem to build your app, please check troubleshooting

2.Parameter configuration

Find the res directory under your project/app/src/main , and manually create a raw folder in the res directory.

Download your amplifyconfiguration.json file from your clickstream control plane, and paste it to raw folder, the json file will be as following:

  "analytics": {
    "plugins": {
      "awsClickstreamPlugin": {
        "appId": "appId",
        "endpoint": "",
        "isCompressEvents": true,
        "autoFlushEventsInterval": 10000,
        "isTrackAppExceptionEvents": false

Your appId and endpoint are already set up in it, here's an explanation of each property:

  • appId: the app id of your project in control plane.
  • endpoint: the endpoint url you will upload the event to AWS server.
  • isCompressEvents: whether to compress event content when uploading events, default is true
  • autoFlushEventsInterval: event sending interval, the default is 10s
  • isTrackAppExceptionEvents: whether auto track exception event in app, default is false

3.Initialize the SDK

It is recommended that you initialize the SDK in the Application onCreate() method. Please note that the initialization code needs to run in the main thread.


public void onCreate() {

        Log.i("MyApp", "Initialized ClickstreamAnalytics");
    } catch (AmplifyException error){
        Log.e("MyApp", "Could not initialize ClickstreamAnalytics", error);

4.Config the SDK

After initial the SDK we can use the following code to custom configure it.


// config the SDK after initialize.
            .withAuthCookie("your authentication cookie")

note: this configuration will override the default configuration in amplifyconfiguration.json file.

Start using

Now that you've integrated the SDK, let's start using it in your app.

Record event

Add the following code where you need to report an event.


ClickstreamEvent event = ClickstreamEvent.builder()
    .add("Channel", "SMS")
    .add("Successful", true)
    .add("ProcessDuration", 78.2)
    .add("UserAge", 20)

// for record an event directly

Add global attribute


ClickstreamAttribute globalAttribute = ClickstreamAttribute.builder()
    .add("channel", "HUAWEI")
    .add("level", 5.1)
    .add("class", 6)
    .add("isOpenNotification", true)

// for delete an global attribute

Login and logout


// when user login success.

// when user logout

When we log into another user, we will clear the before user's user attributes, after setUserId() you need add your user's attribute.

Add user attribute


ClickstreamUserAttribute clickstreamUserAttribute = ClickstreamUserAttribute.builder()
    .add("_user_age", 21)
    .add("_user_name", "carl")

Current login user‘s attributes will be cached in disk, so the next time app launch you don't need to set all user's attribute again, of course you can update the current user's attribute when it changes.

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.


ClickstreamItem item_book = ClickstreamItem.builder()
     .add(ClickstreamAnalytics.Item.ITEM_ID, "123")
     .add(ClickstreamAnalytics.Item.ITEM_NAME, "'Nature'")
     .add(ClickstreamAnalytics.Item.ITEM_CATEGORY, "book")
     .add(ClickstreamAnalytics.Item.PRICE, 99)
     .add("book_publisher", "Nature Research")

ClickstreamEvent event = ClickstreamEvent.builder()
     .add(ClickstreamAnalytics.Item.ITEM_ID, "123")
     .add(ClickstreamAnalytics.Item.CURRENCY, "USD")
     .add("event_category", "recommended")
     .setItems(new ClickstreamItem[] {item_book})


Record Screen View events manually

By default, SDK will automatically track the preset _screen_view event when Activity triggers onResume.

You can also manually record screen view events whether or not automatic screen view tracking is enabled, add the following code to record a screen view event with two attributes.

  • SCREEN_NAME Required. Your screen's name.
  • SCREEN_UNIQUE_ID Optional. Set the hashcode of your Activity, Fragment, or View. If you do not set, SDK will set a default value based on the current Activity's hashcode.

ClickstreamEvent event = ClickstreamEvent.builder()
     .add(ClickstreamAnalytics.Attr.SCREEN_NAME, "HomeFragment")
     .add(ClickstreamAnalytics.Attr.SCREEN_UNIQUE_ID, String.valueOf(HomeFragment.hashCode()))


Log the event json in debug mode


// log the event in debug mode.

after config .withLogEvents(true) and when you record an event, you can see the event json at your AndroidStudio Logcat by filter EventRecorder.

Config custom DNS


// config custom dns.

If you want to use custom DNS for network request, you can create your CustomOkhttpDns which implementation okhttp3.Dns, then config .withCustomDns(CustomOkhttpDns.getInstance()) to make it works.

Send event immediately


// for send event immediately.

Disable SDK

You can disable the SDK in the scenario you need. After disabling the SDK, the SDK will not handle the logging and sending of any events. Of course you can enable the SDK when you need to continue logging events.

Please note that the disable and enable code needs to be run in the main thread.


// disable SDK

// enable SDK

How to build locally

open an terminal window, at the root project folder to execute:

./gradlew build -p clickstream


Problem: Duplicate class for kotlin-stdlib:1.8.x

If your project use kotlin 1.7 or lower, you may have this problem, you can choose one of the following three ways to fix it.

  1. Upgrade your kotlin version to 1.8

  2. Add bom library to your app module's build.gradle file, it will align the kotlin version with 1.8

  3. add resolutionStrategy to your app module's build.gradle file to force specifying your kotlin version to build.

    configurations.all {
        resolutionStrategy {


See CONTRIBUTING for more information.


This library is licensed under the Apache 2.0 License.