{"id":28586025,"url":"https://github.com/aws-solutions/clickstream-analytics-on-aws-react-native-sdk","last_synced_at":"2025-07-29T18:10:57.139Z","repository":{"id":231077684,"uuid":"771847869","full_name":"aws-solutions/clickstream-analytics-on-aws-react-native-sdk","owner":"aws-solutions","description":"React Native SDK for Clickstream Analytics on AWS","archived":false,"fork":false,"pushed_at":"2025-04-15T20:39:43.000Z","size":2564,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-04-15T21:35:23.738Z","etag":null,"topics":["analytics","android","aws-clickstream-solution","aws-solutions","clickstream-react-native","ios","react-native","react-native-sdk"],"latest_commit_sha":null,"homepage":"https://aws.amazon.com/solutions/implementations/clickstream-analytics-on-aws/","language":"TypeScript","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":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-14T04:02:10.000Z","updated_at":"2025-04-15T20:39:25.000Z","dependencies_parsed_at":"2025-02-26T18:43:12.623Z","dependency_job_id":"56519d7b-60f9-46a4-9ced-1a6493fab1bf","html_url":"https://github.com/aws-solutions/clickstream-analytics-on-aws-react-native-sdk","commit_stats":null,"previous_names":["awslabs/clickstream-react-native","aws-solutions/clickstream-analytics-on-aws-react-native-sdk"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-react-native-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-react-native-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-react-native-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-react-native-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-react-native-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-react-native-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","aws-clickstream-solution","aws-solutions","clickstream-react-native","ios","react-native","react-native-sdk"],"created_at":"2025-06-11T06:30:29.060Z","updated_at":"2025-06-11T06:30:29.778Z","avatar_url":"https://github.com/aws-solutions.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS Solution Clickstream Analytics SDK for React Native\n\n## Introduction\n\nClickstream React Native SDK can help you easily collect and report events from React Native apps to AWS. This SDK is\npart of an AWS solution - [Clickstream Analytics on AWS](https://github.com/aws-solutions/clickstream-analytics-on-aws), which\nprovisions data pipeline to ingest and process event data into AWS services such as Amazon S3, Redshift.\n\nThe SDK relies on the [Clickstream Android SDK](https://github.com/aws-solutions/clickstream-android)\nand [Clickstream Swift SDK](https://github.com/aws-solutions/clickstream-swift). Therefore, Clickstream React Native SDK also\nsupports automatically collect common preset events and attributes (e.g., session start, first open). In addition, we've\nadded easy-to-use APIs to simplify data collection in React Native apps.\n\nVisit\nour [Documentation site](https://aws-solutions.github.io/clickstream-analytics-on-aws/en/latest/sdk-manual/react-native/) to\nlearn more about Clickstream React Native SDK.\n\n### Platform Support\n\n**Android**: Supports Android 4.1 (API level 16) and later.\n\n**iOS**: Supports iOS 13 and later.\n\n## Integrate SDK\n\n### Include SDK\n\n```bash\n$ npm install @aws/clickstream-react-native\n```\n\nAfter complete, you need to install the pod dependencies for iOS:\n\n```bash\n$ cd ios \u0026\u0026 pod install\n```\n\n### Initialize the SDK\n\nCopy your configuration code from your clickstream solution web console, we recommended you add the code to your app's\nentry point like `index.js`, the configuration code should look like as follows. You can also manually add this code\nsnippet and replace the values of appId and endpoint after you registered app to a data pipeline in the Clickstream\nAnalytics solution web console.\n\n```javascript\n// index.js\n\nimport { ClickstreamAnalytics } from '@aws/clickstream-react-native';\n\nClickstreamAnalytics.init({\n  appId: 'your appId',\n  endpoint: 'https://example.com/collect',\n});\n```\n\nYour `appId` and `endpoint` are already set up in it.\n\n\u003e Make sure you call `ClickstreamAnalytics.init` as early as possible in your application’s life-cycle. And make sure\n\u003e the SDK is initialized when calling other APIs.\n\n### Start using\n\n#### Record event\n\nAdd the following code where you need to record events.\n\n```typescript\nimport { ClickstreamAnalytics } from '@aws/clickstream-react-native';\n\n// record event with attributes\nClickstreamAnalytics.record({\n  name: 'button_click',\n  attributes: {\n    event_category: 'shoes',\n    currency: 'CNY',\n    value: 279.9,\n  },\n});\n\n// record event with name\nClickstreamAnalytics.record({ name: 'button_click' });\n```\n\n#### Login and logout\n\n```typescript\nimport { ClickstreamAnalytics } from '@aws/clickstream-react-native';\n\n// when user login success.\nClickstreamAnalytics.setUserId(\"userId\");\n\n// when user logout\nClickstreamAnalytics.setUserId(null);\n```\n\n#### Add user attribute\n\n```typescript\nimport { ClickstreamAnalytics } from '@aws/clickstream-react-native';\n\nClickstreamAnalytics.setUserAttributes({\n  userName: \"carl\",\n  userAge: 22\n});\n```\n\nWhen opening the Apps for the first time after integrating the SDK, you need to manually set the user attributes once,\nand current login user's attributes will be cached in disk, so the next time app open you don't need to set all user\nattributes again, of course you can use the same API `ClickstreamAnalytics.setUserAttributes()` to update the current\nuser's attribute when it changes.\n\n#### Add global attribute\n\n1. Add global attributes when initializing the SDK\n\n\t The following example code shows how to add traffic source fields as global attributes when initializing the SDK.\n   ```typescript\n   import { ClickstreamAnalytics, Attr } from '@aws/clickstream-react-native';\n   ClickstreamAnalytics.init({\n      appId: 'your appId',\n      endpoint: 'https://example.com/collect',\n      globalAttributes:{\n        [Attr.TRAFFIC_SOURCE_SOURCE]: 'amazon',\n        [Attr.TRAFFIC_SOURCE_MEDIUM]: 'cpc',\n        [Attr.TRAFFIC_SOURCE_CAMPAIGN]: 'summer_promotion',\n        [Attr.TRAFFIC_SOURCE_CAMPAIGN_ID]: 'summer_promotion_01',\n        [Attr.TRAFFIC_SOURCE_TERM]: 'running_shoes',\n        [Attr.TRAFFIC_SOURCE_CONTENT]: 'banner_ad_1',\n        [Attr.TRAFFIC_SOURCE_CLID]: 'amazon_ad_123',\n        [Attr.TRAFFIC_SOURCE_CLID_PLATFORM]: 'amazon_ads',\n        [Attr.APP_INSTALL_CHANNEL]: 'amazon_store',\n      },\n   });\n   ```\n\n2. Add global attributes after initializing the SDK\n\n   ``` typescript\n   import { ClickstreamAnalytics, Attr } from '@aws/clickstream-react-native';\n\n   ClickstreamAnalytics.setGlobalAttributes({\n     [Attr.TRAFFIC_SOURCE_MEDIUM]: \"Search engine\",\n     level: 10,\n   });\n   ```\n\nIt is recommended to set global attributes when initializing the SDK, global attributes will be included in all events\nthat occur after it is set.\n\n#### Delete global attribute\n\n``` typescript\nClickstreamAnalytics.deleteGlobalAttributes(['level','_traffic_source_medium']);\n```\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```typescript\nimport { ClickstreamAnalytics, Item, Attr } from '@aws/clickstream-react-native';\n\nconst itemBook: Item = {\n  id: '123',\n  name: 'Nature',\n  category: 'book',\n  price: 99,\n  book_publisher: \"Nature Research\",\n};\nClickstreamAnalytics.record({\n  name: 'view_item',\n  attributes: {\n    [Attr.VALUE]: 99,\n    [Attr.CURRENCY]: 'USD',\n    event_category: 'recommended',\n  },\n  items: [itemBook],\n});\n```\n\n#### Record Screen View events manually\n\nBy default, SDK will automatically track the preset `_screen_view` event when Android Activity triggers `onResume` or\niOS ViewController triggers `viewDidAppear`.\n\nYou can also manually record screen view events whether automatic screen view tracking is enabled, add the following\ncode 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 id of your Component. If you do not set, the SDK will set a default value based\n  on the hashcode of the current Activity or ViewController.\n\n```typescript\nimport { ClickstreamAnalytics, Attr, Event } from '@aws/clickstream-react-native';\n\nClickstreamAnalytics.record({\n  name: Event.SCREEN_VIEW,\n  attributes: {\n    [Attr.SCREEN_NAME]: 'HomeComponet',\n    [Attr.SCREEN_UNIQUE_ID]: '123adf',\n  },\n});\n```\n\n#### Record screen views when using React Navigation\nHere's an [example](https://github.com/aws-samples/clickstream-sdk-samples/pull/25/files#diff-96a74db413b2f02988e5537fdbdf4f307334e8f5ef3a9999df7de3c6785af75bR344-R397) of globally logging React Native screen view events when using React Navigation 6.x\n\nFor other version of React Navigation, you can refer to official documentation: [Screen tracking for analytics](https://reactnavigation.org/docs/screen-tracking/).\n\n#### Other configurations\n\nIn addition to the required `appId` and `endpoint`, you can configure other information to get more customized usage\nwhen initialing the SDK:\n\n```typescript\nimport { ClickstreamAnalytics } from '@aws/clickstream-react-native';\n\nClickstreamAnalytics.init({\n  appId: 'your appId',\n  endpoint: 'https://example.com/collect',\n  isLogEvents: true,\n  isCompressEvents: true,\n  isTrackScreenViewEvents: false,\n  isTrackUserEngagementEvents: true,\n  isTrackAppExceptionEvents: true,\n  sendEventsInterval: 15000,\n  sessionTimeoutDuration: 1800000,\n  authCookie: 'your auth cookie',\n  globalAttributes: {\n    _traffic_source_medium: 'Search engine',\n  },\n});\n```\n\nHere is an explanation of each property:\n\n- **appId (Required)**: the app id of your project in solution web control.\n- **endpoint (Required)**: the endpoint path you will upload the event to ingestion server.\n- **isLogEvents**: whether to print out event json for debugging, default is `false`.\n- **isCompressEvents**: whether to compress event content when uploading events, default is `true`.\n- **sendEventsInterval**: event sending interval millisecond, works only bath send mode, the default value is `5000`\n- **isTrackScreenViewEvents**: whether auto record native screen view events, default is `true`\n- **isTrackUserEngagementEvents**: whether auto record user engagement events, default is `true`\n- **isTrackAppExceptionEvents**: whether auto record exception events of native apps, default is `false`\n- **sendEventsInterval**: event sending interval millisecond, the default value is `10000` (10s)\n- **sessionTimeoutDuration**: the duration for session timeout millisecond, default is `1800000` (30 minutes)\n- **authCookie**: your auth cookie for AWS application load balancer auth cookie.\n- **globalAttributes**: the global attributes when initializing the SDK.\n\n#### Configuration update\n\nYou can update the default configuration after initializing the SDK, below are the additional configuration options you\ncan customize.\n\n```typescript\nimport { ClickstreamAnalytics } from '@aws/clickstream-react-native';\n\nClickstreamAnalytics.updateConfigure({\n  appId: 'your appId',\n  endpoint: 'https://example.com/collect',\n  isLogEvents: true,\n  authCookie: 'your auth cookie',\n  isCompressEvents: true,\n  isTrackPageViewEvents: false,\n  isTrackUserEngagementEvents: false,\n  isTrackAppExceptionEvents: false,\n});\n```\n\n#### Logging events json in debug mode\n\n```javascript\nimport { ClickstreamAnalytics } from '@aws/clickstream-react-native';\n\nClickstreamAnalytics.init({\n  appId: 'your appId',\n  endpoint: 'https://example.com/collect',\n  isLogEvents: true,\n});\n```\n\nAfter configuring `isLogEvents:true` when initializing the SDK, when you record an event, you can see the event raw json\nin AndroidStudio Logcat or Xcode debug console by filter `EventRecorder`.\n\n#### Disable SDK\n\nYou can disable the SDK in the scenario you need. After disabling the SDK, the SDK will not handle the logging and\nsending of any events. Of course, you can enable the SDK when you need to continue logging events.\n\n```javascript\nimport { ClickstreamAnalytics } from '@aws/clickstream-react-native';\n\n// disable SDK\nClickstreamAnalytics.disable();\n\n// enable SDK\nClickstreamAnalytics.enable();\n```\n\n## How to integrate and test locally\n\nClone this repository locally and execute the following script to generate `aws-clickstream-react-native-0.3.3.tgz` zip\npackage, which will be located in the project root folder.\n\n```bash\n$ cd clickstream-react-native \u0026\u0026 yarn \u0026\u0026 yarn run pack\n```\n\nCopy the `aws-clickstream-react-native-0.3.3.tgz` into your project, then execute the script in your project root folder to\ninstall the SDK.\n\n```bash\n$ yarn add ./aws-clickstream-react-native-0.3.3.tgz\n```\n\n**Note**: Please correct the SDK version and change the path to where the `aws-clickstream-react-native-0.3.3.tgz` file is\nlocated.\n\nYou can also find the `aws-clickstream-react-native-0.3.3.tgz` file in\nthe [Release](https://github.com/aws-solutions/clickstream-react-native/releases) page.\n\n### Test\n\n```bash\n$ yarn run test\n\n# with lint\n$ sh ./deployment/run-unit-tests.sh\n```\n\n## Collection of operational metrics\n\nThis solution collects anonymized operational metrics to help AWS improve the\nquality of features of the solution. For more information, including how to disable\nthis capability, please see the [implementation guide](https://docs.aws.amazon.com/solutions/latest/clickstream-analytics-on-aws).\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).\n\nAlthough this repository is released under the [Apache 2.0 License](./LICENSE), it includes some [third party dependencies](./NOTICE) with [BlueOak-1.0.0](https://spdx.org/licenses/BlueOak-1.0.0.html) license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-solutions%2Fclickstream-analytics-on-aws-react-native-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws-solutions%2Fclickstream-analytics-on-aws-react-native-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-solutions%2Fclickstream-analytics-on-aws-react-native-sdk/lists"}