{"id":28586022,"url":"https://github.com/aws-solutions/clickstream-analytics-on-aws-flutter-sdk","last_synced_at":"2025-08-13T18:15:21.284Z","repository":{"id":203933666,"uuid":"709093016","full_name":"aws-solutions/clickstream-analytics-on-aws-flutter-sdk","owner":"aws-solutions","description":"Flutter SDK for Clickstream Analytics on AWS","archived":false,"fork":false,"pushed_at":"2025-02-26T18:21:19.000Z","size":200,"stargazers_count":8,"open_issues_count":0,"forks_count":2,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-06-11T06:41:06.183Z","etag":null,"topics":["analytics","android","aws-clickstream-solution","aws-solutions","clickstream","dart-package","flutter","flutter-plugin","flutter-sdk","ios"],"latest_commit_sha":null,"homepage":"https://aws.amazon.com/solutions/implementations/clickstream-analytics-on-aws/","language":"Dart","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","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,"zenodo":null}},"created_at":"2023-10-24T02:00:36.000Z","updated_at":"2025-02-26T18:21:23.000Z","dependencies_parsed_at":"2024-06-12T11:48:34.957Z","dependency_job_id":"d6271b1b-2c42-4786-bceb-e868e9509dd5","html_url":"https://github.com/aws-solutions/clickstream-analytics-on-aws-flutter-sdk","commit_stats":null,"previous_names":["awslabs/clickstream-flutter","aws-solutions/clickstream-analytics-on-aws-flutter-sdk"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/aws-solutions/clickstream-analytics-on-aws-flutter-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-flutter-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-flutter-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-flutter-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-flutter-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-flutter-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws-solutions%2Fclickstream-analytics-on-aws-flutter-sdk/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270287510,"owners_count":24558622,"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","status":"online","status_checked_at":"2025-08-13T02:00:09.904Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","dart-package","flutter","flutter-plugin","flutter-sdk","ios"],"created_at":"2025-06-11T06:30:27.710Z","updated_at":"2025-08-13T18:15:21.196Z","avatar_url":"https://github.com/aws-solutions.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS Solution Clickstream Analytics SDK for Flutter\n\n## Introduction\n\nClickstream Flutter SDK can help you easily collect and report events from your mobile app to AWS. This SDK is part of an AWS solution - [Clickstream Analytics on AWS](https://github.com/aws-solutions/clickstream-analytics-on-aws), which provisions data pipeline to ingest and process event data into AWS services such as S3, Redshift.\n\nThe SDK relies on the [Clickstream Android SDK](https://github.com/aws-solutions/clickstream-analytics-on-aws-android-sdk) and [Clickstream Swift SDK](https://github.com/aws-solutions/clickstream-analytics-on-aws-swift-sdk). Therefore, flutter SDK also supports automatically collect common user events and attributes (e.g., session start, first open). In addition, we've added easy-to-use APIs to simplify data collection in Flutter apps.\n\nVisit our [Documentation site](https://aws-solutions.github.io/clickstream-analytics-on-aws/en/latest/sdk-manual/flutter/) to learn more about Clickstream Flutter SDK.\n\n## Integrate SDK\n\n### Include SDK\n\n```bash\nflutter pub add clickstream_analytics\n```\n\nAfter complete, rebuild your Flutter application:\n\n```bash\nflutter run\n```\n\n### Initialize the SDK\n\nCopy your configuration code from your clickstream solution web console, 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.\n\n```dart\nimport 'package:clickstream_analytics/clickstream_analytics.dart';\n\nfinal analytics = ClickstreamAnalytics();\nanalytics.init(\n  appId: \"your appId\",\n  endpoint: \"https://example.com/collect\"\n);\n```\n\nPlease note：\n\n1. Your `appId` and `endpoint` are already set up in it.\n2. We only need to initialize the SDK once after the application starts. It is recommended to do it in the main function of your App.\n3. We can use `bool result = await analytics.init()` to get the boolean value of the initialization result.\n\n### Start using\n\n#### Record event\n\nAdd the following code where you need to record event.\n\n```dart\nimport 'package:clickstream_analytics/clickstream_analytics.dart';\n\nfinal analytics = ClickstreamAnalytics();\n\n// record event with attributes\nanalytics.record(name: 'button_click', attributes: {\n  \"event_category\": \"shoes\",\n  \"currency\": \"CNY\",\n  \"value\": 279.9\n});\n\n//record event with name\nanalytics.record(name: \"button_click\");\n```\n\n#### Login and logout\n\n```dart\n/// when user login success.\nanalytics.setUserId(\"userId\");\n\n/// when user logout\nanalytics.setUserId(null);\n```\n\n#### Add user attribute\n\n```dart\nanalytics.setUserAttributes({\n  \"userName\": \"carl\",\n  \"userAge\": 22\n});\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 use the same api `analytics.setUserAttributes()` to update the current user's attribute when it changes.\n\n#### Add global attribute\n\n1. Add global attributes when initializing the SDK\n   \n   The following example code shows how to add traffic source fields as global attributes when initializing the SDK.\n   ```dart\n   analytics.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   ```dart\n   analytics.addGlobalAttributes({\n     Attr.TRAFFIC_SOURCE_MEDIUM: \"Search engine\",\n     \"level\": 10\n   });\n   ```\n\n#### Delete global attribute\n```\nanalytics.deleteGlobalAttributes([\"level\"]);\n```\n\nIt is recommended to set global attributes after each SDK initialization, global attributes will be included in all events that occur after it is set.\n\n#### Record event with items\n\nYou can add the following code to log an event with an item. you can add custom item attribute in `attributes` object.\n\n**Note: Only pipelines from version 1.1+ can handle items with custom attribute.**\n\n```dart\nvar itemBook = ClickstreamItem(\n    id: \"123\",\n    name: \"Nature\",\n    category: \"book\",\n    price: 99,\n    attributes: {\n      \"book_publisher\": \"Nature Research\"\n    }\n);\n\nanalytics.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 iOS ViewController triggers `viewDidAppear`.\n\nYou can also manually record screen view events whether automatic screen view tracking is enabled, add the following code to record a screen view event with two attributes.\n\n* `screenName` Required. Your screen's name.\n* `screenUniqueId` Optional. Set the id of your Widget. If you do not set, the SDK will set a default value based on the hashcode of the current Activity or ViewController.\n\n```dart\nanalytics.recordScreenView(\n  screenName: 'Main',\n  screenUniqueId: '123adf',\n  attributes: { ... }\n);\n```\n\n#### Other configurations\n\nIn addition to the required `appId` and `endpoint`, you can configure other information to get more customized usage:\n\n```dart\nfinal analytics = ClickstreamAnalytics();\nanalytics.init(\n  appId: \"your appId\",\n  endpoint: \"https://example.com/collect\",\n  isLogEvents: false,\n  isCompressEvents: false,\n  sendEventsInterval: 10000,\n  isTrackScreenViewEvents: true,\n  isTrackUserEngagementEvents: true,\n  isTrackAppExceptionEvents: false,\n  authCookie: \"your auth cookie\",\n  sessionTimeoutDuration: 1800000,\n  globalAttributes: {\n    \"_traffic_source_medium\": \"Search engine\",\n  },\n);\n```\n\nHere is an explanation of each option:\n\n- **appId (Required)**: the app id of your project in control plane.\n- **endpoint (Required)**: the endpoint path you will upload the event to Clickstream 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 screen view events in app, default is `true`\n- **isTrackUserEngagementEvents**: whether auto record user engagement events in app, default is `true`\n- **isTrackAppExceptionEvents**: whether auto track exception event in app, default is `false`\n- **authCookie**: your auth cookie for AWS application load balancer auth cookie.\n- **sessionTimeoutDuration**: the duration for session timeout millisecond, default is 1800000\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 can customize.\n\n```dart\nfinal analytics = ClickstreamAnalytics();\nanalytics.updateConfigure(\n    appId: \"your appId\",\n    endpoint: \"https://example.com/collect\",\n    isLogEvents: true,\n    isCompressEvents: false,\n    isTrackScreenViewEvents: false\n    isTrackUserEngagementEvents: false,\n    isTrackAppExceptionEvents: false,\n    authCookie: \"test cookie\");\n```\n\n#### Send event immediately\n\n```dart\nfinal analytics = ClickstreamAnalytics();\nanalytics.flushEvents();\n```\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```dart\nfinal analytics = ClickstreamAnalytics();\n\n// disable SDK\nanalytics.disable();\n\n// enable SDK\nanalytics.enable();\n```\n\n## How to build and test locally\n\n### Build\n\nInstall flutter packages\n\n```bash\nflutter pub get\n```\n\nBuild for Android \n\n```bash\ncd example \u0026\u0026 flutter build apk\n```\n\nBuild for iOS\n\n```dart\ncd example \u0026\u0026 flutter build ios\n```\n\n### Format and lint\n\n```bash\ndart format . \u0026\u0026 flutter analyze\n```\n\n### Test\n\n```bash\nflutter test\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).\n\n## Anonymous operational metrics\n\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-flutter-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws-solutions%2Fclickstream-analytics-on-aws-flutter-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws-solutions%2Fclickstream-analytics-on-aws-flutter-sdk/lists"}