{"id":28586026,"url":"https://github.com/aws-solutions/clickstream-analytics-on-aws-android-sdk","last_synced_at":"2025-06-11T06:30:30.913Z","repository":{"id":168112337,"uuid":"616258323","full_name":"aws-solutions/clickstream-analytics-on-aws-android-sdk","owner":"aws-solutions","description":"Android SDK for Clickstream Analytics on AWS","archived":false,"fork":false,"pushed_at":"2025-02-14T20:03:47.000Z","size":531,"stargazers_count":17,"open_issues_count":0,"forks_count":1,"subscribers_count":23,"default_branch":"main","last_synced_at":"2025-02-14T21:18:18.272Z","etag":null,"topics":["analytics","android-sdk","aws","aws-clickstream-solution","aws-solutions","clickstream"],"latest_commit_sha":null,"homepage":"https://aws.amazon.com/solutions/implementations/clickstream-analytics-on-aws/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aws-solutions.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-20T02:45:29.000Z","updated_at":"2025-02-14T20:00:30.000Z","dependencies_parsed_at":"2023-06-08T09:15:30.187Z","dependency_job_id":"dd1f1cdd-be1f-4d6b-8011-c09d54f146c2","html_url":"https://github.com/aws-solutions/clickstream-analytics-on-aws-android-sdk","commit_stats":null,"previous_names":["awslabs/clickstream-android","aws-solutions/clickstream-analytics-on-aws-android-sdk"],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-android-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-android-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-android-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-android-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws-solutions","download_url":"https://codeload.github.com/aws-solutions/clickstream-analytics-on-aws-android-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-android-sdk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259214187,"owners_count":22822841,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","android-sdk","aws","aws-clickstream-solution","aws-solutions","clickstream"],"created_at":"2025-06-11T06:30:29.893Z","updated_at":"2025-06-11T06:30:30.800Z","avatar_url":"https://github.com/aws-solutions.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS Solution Clickstream Analytics SDK for Android\n\n[![Maven Central](https://img.shields.io/maven-central/v/software.aws.solution/clickstream.svg)](https://search.maven.org/artifact/software.aws.solution/clickstream)\n\n## Introduction\n\nClickstream 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](https://github.com/aws-solutions/clickstream-analytics-on-aws-android-sdk), which provisions data pipeline to ingest and process event data into AWS services such as S3, Redshift.\n\nThe 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.\n\nVisit our [Documentation site](https://docs.aws.amazon.com/solutions/latest/clickstream-analytics-on-aws/android-sdk.html) to learn more about Clickstream Android SDK.\n\n### Platform Support\n\nClickstream Android SDK supports Android 4.1 (API level 16) and later.\n\n## Integrate SDK\n\n### 1. Include SDK\n\nAdd the following dependency to your `app` module's `build.gradle` file.\n\n```groovy\ndependencies {\n    implementation 'software.aws.solution:clickstream:1.0.0'\n}\n```\n\nthen sync your project, if you have problem to build your app, please check [troubleshooting](#Troubleshooting)\n\n### 2. Parameter configuration\n\nFind the res directory under your  `project/app/src/main` , and manually create a raw folder in the res directory. \n\n![](images/raw_folder.png)\n\nDownload your `amplifyconfiguration.json` file from your clickstream control plane, and paste it to raw folder, the json file will be as following:\n\n```json\n{\n  \"analytics\": {\n    \"plugins\": {\n      \"awsClickstreamPlugin\": {\n        \"appId\": \"your appId\",\n        \"endpoint\": \"https://example.com/collect\",\n        \"isCompressEvents\": true,\n        \"autoFlushEventsInterval\": 10000,\n        \"isTrackAppExceptionEvents\": false\n      }\n    }\n  }\n}\n```\n\nYour `appId` and `endpoint` are already set up in it, here's an explanation of each property:\n\n- **appId**: the app id of your project in control plane.\n- **endpoint**: the endpoint url you will upload the event to AWS server.\n- **isCompressEvents**: whether to compress event content when uploading events, default is `true`\n- **autoFlushEventsInterval**: event sending interval, the default is `10s`\n- **isTrackAppExceptionEvents**: whether auto track exception event in app, default is `false`\n\n### 3. Initialize the SDK\n\nIt is recommended that you initialize the SDK in your application's `onCreate()` method. Please note that the initialization code needs to run in the main thread.\n\n#### 3.1 Initialize the SDK with default configuration\n```java\nimport software.aws.solution.clickstream.ClickstreamAnalytics;\n\npublic void onCreate() {\n    super.onCreate();\n    try{\n        ClickstreamAnalytics.init(getApplicationContext());\n        Log.i(\"MyApp\", \"Initialized ClickstreamAnalytics\");\n    } catch (AmplifyException error){\n        Log.e(\"MyApp\", \"Could not initialize ClickstreamAnalytics\", error);\n    } \n}\n```\n#### 3.2 Initialize the SDK with global attributes and custom configuration\n\nThe following example code shows how to add traffic source fields as global attributes when initializing the SDK.\n\n```java\nimport software.aws.solution.clickstream.ClickstreamAnalytics;\n\npublic void onCreate() {\n    super.onCreate();\n    try{\n        ClickstreamAttribute globalAttributes = ClickstreamAttribute.builder()\n            .add(ClickstreamAnalytics.Attr.TRAFFIC_SOURCE_SOURCE, \"amazon\")\n            .add(ClickstreamAnalytics.Attr.TRAFFIC_SOURCE_MEDIUM, \"cpc\")\n            .add(ClickstreamAnalytics.Attr.TRAFFIC_SOURCE_CAMPAIGN, \"summer_promotion\")\n            .add(ClickstreamAnalytics.Attr.TRAFFIC_SOURCE_CAMPAIGN_ID, \"summer_promotion_01\")\n            .add(ClickstreamAnalytics.Attr.TRAFFIC_SOURCE_TERM, \"running_shoes\")\n            .add(ClickstreamAnalytics.Attr.TRAFFIC_SOURCE_CONTENT, \"banner_ad_1\")\n            .add(ClickstreamAnalytics.Attr.TRAFFIC_SOURCE_CLID, \"amazon_ad_123\")\n            .add(ClickstreamAnalytics.Attr.TRAFFIC_SOURCE_CLID_PLATFORM, \"amazon_ads\")\n            .build();\n        ClickstreamConfiguration configuration = new ClickstreamConfiguration()\n            .withAppId(\"your appId\")\n            .withEndpoint(\"http://example.com/collect\")\n            .withLogEvents(true)\n            .withInitialGlobalAttributes(globalAttributes);\n        ClickstreamAnalytics.init(getApplicationContext(), configuration);\n        Log.i(\"MyApp\", \"Initialized ClickstreamAnalytics\");\n    } catch (AmplifyException error){\n        Log.e(\"MyApp\", \"Could not initialize ClickstreamAnalytics\", error);\n    } \n}\n```\nBy default, we will use the configurations in `amplifyconfiguration.json` file. If you add a custom configuration, the added configuration items will override the default values. \n\nYou can also add all the configuration parameters you need in the `init` method without using the `amplifyconfiguration.json` file.\n\n### 4. Update Configuration\n\nAfter initial the SDK we can use the following code to up configure it.\n\n```java\nimport software.aws.solution.clickstream.ClickstreamAnalytics;\n\n// config the SDK after initialize.\nClickstreamAnalytics.getClickStreamConfiguration()\n            .withAppId(\"appId\")\n            .withEndpoint(\"https://example.com/collect\")\n            .withAuthCookie(\"your authentication cookie\")\n            .withSendEventsInterval(10000)\n            .withSessionTimeoutDuration(1800000)\n            .withTrackScreenViewEvents(false)\n            .withTrackUserEngagementEvents(false)\n            .withTrackAppExceptionEvents(false)\n            .withLogEvents(true)\n            .withCustomDns(CustomOkhttpDns.getInstance())\n            .withCompressEvents(true);\n```\n\n\u003e note: this configuration will override the default configuration in `amplifyconfiguration.json` file.\n\n### Start using\n\nNow that you've integrated the SDK, let's start using it in your app.\n\n#### Record event\n\nAdd the following code where you need to report an event.\n\n```java\nimport software.aws.solution.clickstream.ClickstreamAnalytics;\nimport software.aws.solution.clickstream.ClickstreamEvent;\n\nClickstreamEvent event = ClickstreamEvent.builder()\n    .name(\"PasswordReset\")\n    .add(\"Channel\", \"SMS\")\n    .add(\"Successful\", true)\n    .add(\"ProcessDuration\", 78.2)\n    .add(\"UserAge\", 20)\n    .build();\nClickstreamAnalytics.recordEvent(event);\n\n// for record an event directly\nClickstreamAnalytics.recordEvent(\"button_click\");\n```\n\n#### Add global attribute\n\n```java\nimport software.aws.solution.clickstream.ClickstreamAttribute;\nimport software.aws.solution.clickstream.ClickstreamAnalytics;\n\nClickstreamAttribute globalAttribute = ClickstreamAttribute.builder()\n    .add(\"channel\", \"HUAWEI\")\n    .add(\"level\", 5.1)\n    .add(\"class\", 6)\n    .add(\"isOpenNotification\", true)\n    .build();\nClickstreamAnalytics.addGlobalAttributes(globalAttribute);\n\n// for delete an global attribute\nClickstreamAnalytics.deleteGlobalAttributes(\"level\");\n```\n\nIt is recommended to set global attributes when initializing the SDK, global attributes will be included in all events that occur after it is set.\n\n#### Login and logout\n\n```java\nimport software.aws.solution.clickstream.ClickstreamAnalytics;\n\n// when user login success.\nClickstreamAnalytics.setUserId(\"UserId\");\n\n// when user logout\nClickstreamAnalytics.setUserId(null);\n```\n\nWhen we log into another user, we will clear the before user's user attributes, after `setUserId()` you need add your user's attribute.\n\n#### Add user attribute\n\n```java\nimport software.aws.solution.clickstream.ClickstreamAnalytcs;\nimport software.aws.solution.clickstream.ClickstreamUserAttribute;\n\nClickstreamUserAttribute clickstreamUserAttribute = ClickstreamUserAttribute.builder()\n    .add(\"_user_age\", 21)\n    .add(\"_user_name\", \"carl\")\n    .build();\nClickstreamAnalytics.addUserAttributes(clickstreamUserAttribute);\n```\n\nCurrent 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.\n\n#### Record event with items\n\nYou can add the following code to log an event with an item.\n\n**Note: Only pipelines from version 1.1+ can handle items with custom attribute.**\n\n```java\nimport software.aws.solution.clickstream.ClickstreamAnalytcs;\nimport software.aws.solution.clickstream.ClickstreamItem;\n\nClickstreamItem item_book = ClickstreamItem.builder()\n     .add(ClickstreamAnalytics.Item.ITEM_ID, \"123\")\n     .add(ClickstreamAnalytics.Item.ITEM_NAME, \"'Nature'\")\n     .add(ClickstreamAnalytics.Item.ITEM_CATEGORY, \"book\")\n     .add(ClickstreamAnalytics.Item.PRICE, 99)\n     .add(\"book_publisher\", \"Nature Research\")\n     .build();\n\nClickstreamEvent event = ClickstreamEvent.builder()\n     .name(\"view_item\")\n     .add(ClickstreamAnalytics.Item.ITEM_ID, \"123\")\n     .add(ClickstreamAnalytics.Item.CURRENCY, \"USD\")\n     .add(\"event_category\", \"recommended\")\n     .setItems(new ClickstreamItem[] {item_book})\n     .build();\n\nClickstreamAnalytics.recordEvent(event);\n```\n\n#### Record Screen View events manually\n\nBy default, SDK will automatically track the preset `_screen_view` event when Activity triggers `onResume`.\n\nYou 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.\n\n* `SCREEN_NAME` Required. Your screen's name.\n* `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.\n\n```java\nimport software.aws.solution.clickstream.ClickstreamAnalytcs;\n\nClickstreamEvent event = ClickstreamEvent.builder()\n     .name(ClickstreamAnalytics.Event.SCREEN_VIEW)\n     .add(ClickstreamAnalytics.Attr.SCREEN_NAME, \"HomeFragment\")\n     .add(ClickstreamAnalytics.Attr.SCREEN_UNIQUE_ID, String.valueOf(HomeFragment.hashCode()))\n     .build();\n\nClickstreamAnalytics.recordEvent(event);\n```\n\n#### Log the event json in debug mode\n\n```java\nimport software.aws.solution.clickstream.ClickstreamAnalytics;\n\n// log the event in debug mode.\nClickstreamAnalytics.getClickStreamConfiguration()\n            .withLogEvents(BuildConfig.DEBUG);\n```\n\nafter config `.withLogEvents(true)` and when you record an event, you can see the event json at your AndroidStudio **Logcat** by filter `EventRecorder`.\n\n#### Config custom DNS\n\n```java\nimport software.aws.solution.clickstream.ClickstreamAnalytics;\n\n// config custom dns.\nClickstreamAnalytics.getClickStreamConfiguration()\n            .withCustomDns(CustomOkhttpDns.getInstance());\n```\n\nIf 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.\n\n#### Send event immediately\n\n```java\nimport software.aws.solution.clickstream.ClickstreamAnalytics;\n\n// for send event immediately.\nClickstreamAnalytics.flushEvent();\n```\n\n#### Disable SDK\nYou 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.\n\nPlease note that the disable and enable code needs to be run in the main thread.\n```java\nimport software.aws.solution.clickstream.ClickstreamAnalytics;\n\n// disable SDK\nClickstreamAnalytics.disable();\n\n// enable SDK\nClickstreamAnalytics.enable();\n```\n\n## How to build locally\n\nopen an terminal window, at the root project folder to execute:\n\n```shell\n./gradlew build -p clickstream\n```\n\n## Troubleshooting\n\n#### Problem: Duplicate class for kotlin-stdlib:1.8.x\n\nIf 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.\n\n1. Upgrade your kotlin version to 1.8\n\n2. Add bom library to your app module's `build.gradle` file, it will align the kotlin version with 1.8\n   \n   ```kotlin\n   implementation(platform(\"org.jetbrains.kotlin:kotlin-bom:1.8.10\"))\n   ```\n\n3. add `resolutionStrategy` to your app module's  `build.gradle` file to force specifying your kotlin version to build.\n   \n   ```kotlin\n   configurations.all {\n       resolutionStrategy {\n           force(\"org.jetbrains.kotlin:kotlin-stdlib:1.7.20\")\n       }\n   }\n   ```\n\n## Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License\n\nThis library is licensed under the [Apache 2.0 License](./LICENSE.txt).\n\n\n## Anonymous operational metrics\n\t \nThis solution collects anonymous operational metrics to help AWS improve the quality and features of the solution. For more information, including how to disable this capability, please see the [implementation guide](https://docs.aws.amazon.com/solutions/latest/clickstream-analytics-on-aws/solution-overview.html).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-solutions%2Fclickstream-analytics-on-aws-android-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws-solutions%2Fclickstream-analytics-on-aws-android-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-solutions%2Fclickstream-analytics-on-aws-android-sdk/lists"}