feat: add readme

.gitignore

@@ -28,3 +28,4 @@ migrate_working_dir/
 .dart_tool/
 .packages
 build/
+coverage/

.pubignore

@@ -0,0 +1,9 @@
+*.iml
+test
+coverage
+build
+android/src/test
+ios/Clickstream/*
+!ios/Clickstream/Sources
+example/integration_test
+example/test

CHANGELOG.md

@@ -1,3 +1,3 @@
-## 0.0.1
+## 0.1.0
 
-* TODO: Describe initial release.
+* feat: add basic android and swift SDK APIs.

README.md

@@ -1,14 +1,182 @@
-# clickstream_flutter
+# AWS Solution Clickstream Analytics SDK for Flutter
 
-clickstream flutter SDK
+## Introduction
 
-## Getting Started
+Clickstream Flutter 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](https://github.com/awslabs/clickstream-analytics-on-aws), which provisions data pipeline to ingest and process event data into AWS services such as S3, Redshift.
 
-This project is a starting point for a Flutter
-[plug-in package](https://flutter.dev/developing-packages/),
-a specialized package that includes platform-specific implementation code for
-Android and/or iOS.
+The SDK relies on the [Clickstream Android SDK](https://github.com/awslabs/clickstream-android) and [Clickstream Swift SDK](https://github.com/awslabs/clickstream-swift). 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.
 
-For help getting started with Flutter development, view the
-[online documentation](https://flutter.dev/docs), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
+## Integrate SDK
+
+### Include SDK
+
+```bash
+flutter pub add clickstream_analytics
+```
+
+After complete, rebuild your Flutter application:
+
+```bash
+flutter run
+```
+
+### Initialize the SDK
+
+Copy 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.
+
+```dart
+import 'package:clickstream_analytics/clickstream_analytics.dart';
+
+final analytics = ClickstreamAnalytics();
+analytics.init({
+   appId: "your appId",
+   endpoint: "https://example.com/collect"
+});
+```
+
+Please note：
+
+1. Your `appId` and `endpoint` are already set up in it.
+2. 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.
+3. We can use `bool result = await analytics.init()` to get the boolean value of the initialization result.
+
+### Start using
+
+#### Record event
+
+Add the following code where you need to record event.
+
+```dart
+import 'package:clickstream_analytics/clickstream_analytics.dart';
+
+final analytics = ClickstreamAnalytics();
+
+// record event with attributes
+analytics.record(name: 'button_click', attributes: {
+  "event_category": "shoes",
+  "currency": "CNY",
+  "value": 279.9
+});
+
+//record event with name
+analytics.record(name: "button_click");
+```
+
+#### Login and logout
+
+```dart
+/// when user login success.
+analytics.setUserId("userId");
+
+/// when user logout
+analytics.setUserId(null);
+```
+
+#### Add user attribute
+
+```dart
+analytics.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 native disk, 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 `analytics.setUserAttributes()` to update the current user's attribute when it changes.
+
+#### Add global attribute
+
+```dart
+analytics.addGlobalAttributes({
+  "_traffic_source_medium": "Search engine",
+  "_traffic_source_name": "Summer promotion",
+  "level": 10
+});
+```
+
+It is recommended to set global attributes after each SDK initialization, global attributes will be included in all events that occur after it is set.
+
+#### Other configurations
+
+In addition to the required `appId` and `endpoint`, you can configure other information to get more customized usage:
+
+```dart
+final analytics = ClickstreamAnalytics();
+analytics.init(
+  appId: "your appId",
+  endpoint: "https://example.com/collect",
+  isLogEvents: false,
+  isCompressEvents: false,
+  sendEventsInterval: 5000,
+  isTrackScreenViewEvents: true,
+  isTrackUserEngagementEvents: true,
+  isTrackAppExceptionEvents: false,
+  authCookie: "your auth cookie",
+  sessionTimeoutDuration: 1800000
+);
+```
+
+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.
+- **isLogEvents**: whether to print out event json for debugging, default is false.
+- **isCompressEvents**: whether to compress event content when uploading events, default is `true`
+- **sendEventsInterval**: event sending interval millisecond, works only bath send mode, the default value is `5000`
+- **isTrackScreenViewEvents**: whether auto record screen view events in app, default is `true`
+- **isTrackUserEngagementEvents**: whether auto record user engagement events in app, default is `true`
+- **isTrackAppExceptionEvents**: whether auto track exception event in app, default is `false`
+- **authCookie**: your auth cookie for AWS application load balancer auth cookie.
+- **sessionTimeoutDuration**: the duration for session timeout millisecond, default is 1800000
+
+#### Configuration update
+
+You can update the default configuration after initializing the SDK, below are the additional configuration options you can customize.
+
+```dart
+final analytics = ClickstreamAnalytics();
+analytics.updateConfigure(
+		appId: "your appId",
+  	endpoint: "https://example.com/collect",
+    isLogEvents: true,
+    isCompressEvents: false,
+    isTrackScreenViewEvents: false
+    isTrackUserEngagementEvents: false,
+    isTrackAppExceptionEvents: false,
+    sessionTimeoutDuration: 100000,
+    authCookie: "test cookie");
+```
+
+#### Send event immediately
+
+```dart
+final analytics = ClickstreamAnalytics();
+analytics.flushEvents();
+```
+
+## How to build and test locally
+
+### Build
+
+```bash
+flutter pub get
+```
+
+### Format and lint
+
+```bash
+dart format . && flutter analyze
+```
+
+### Test
+
+```bash
+flutter test
+```
+
+## Security
+
+See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
+
+## License
+
+This library is licensed under the [Apache 2.0 License](./LICENSE).

android/build.gradle

@@ -1,4 +1,4 @@
-group 'software.aws.solution.clickstream_flutter'
+group 'software.aws.solution.clickstream_analytics'
 version '1.0-SNAPSHOT'
 
 buildscript {
@@ -26,7 +26,7 @@ apply plugin: 'kotlin-android'
 
 android {
     if (project.android.hasProperty("namespace")) {
-        namespace 'software.aws.solution.clickstream_flutter'
+        namespace 'software.aws.solution.clickstream_analytics'
     }
 
     compileSdkVersion 33

android/settings.gradle

@@ -1 +1 @@
-rootProject.name = 'clickstream_flutter'
+rootProject.name = 'clickstream_analytics'

android/src/main/AndroidManifest.xml

@@ -1,3 +1,3 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
-  package="software.aws.solution.clickstream_flutter">
+  package="software.aws.solution.clickstream_analytics">
 </manifest>

android/src/main/kotlin/software/aws/solution/clickstream_flutter/ClickstreamFlutterPlugin.kt → android/src/main/kotlin/software/aws/solution/clickstream_analytics/ClickstreamFlutterPlugin.kt

@@ -1,4 +1,18 @@
-package software.aws.solution.clickstream_flutter
+/*
+ * Copyright 2023 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+package software.aws.solution.clickstream_analytics
 
 import android.app.Activity
 import com.amazonaws.logging.Log

android/src/test/kotlin/software/aws/solution/clickstream_flutter/ClickstreamFlutterPluginTest.kt → android/src/test/kotlin/software/aws/solution/clickstream_analytics/ClickstreamFlutterPluginTest.kt

@@ -1,4 +1,4 @@
-package software.aws.solution.clickstream_flutter
+package software.aws.solution.clickstream_analytics
 
 import io.flutter.plugin.common.MethodCall
 import io.flutter.plugin.common.MethodChannel

example/integration_test/plugin_integration_test.dart

@@ -1,16 +1,10 @@
-// This is a basic Flutter integration test.
-//
-// Since integration tests run in a full Flutter application, they can interact
-// with the host side of a plugin implementation, unlike Dart unit tests.
-//
-// For more information about Flutter integration tests, please see
-// https://docs.flutter.dev/cookbook/testing/integration/introduction
-
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
 
 import 'package:flutter_test/flutter_test.dart';
 import 'package:integration_test/integration_test.dart';
 
-import 'package:clickstream_flutter/clickstream_flutter.dart';
+import 'package:clickstream_analytics/clickstream_analytics.dart';
 
 void main() {
   IntegrationTestWidgetsFlutterBinding.ensureInitialized();

example/ios/Podfile.lock

@@ -2,10 +2,10 @@ PODS:
   - Amplify (1.30.3):
     - Amplify/Default (= 1.30.3)
   - Amplify/Default (1.30.3)
-  - clickstream_flutter (0.0.1):
-    - clickstream_flutter/Clickstream (= 0.0.1)
+  - clickstream_analytics (0.0.1):
+    - clickstream_analytics/Clickstream (= 0.0.1)
     - Flutter
-  - clickstream_flutter/Clickstream (0.0.1):
+  - clickstream_analytics/Clickstream (0.0.1):
     - Amplify (= 1.30.3)
     - Flutter
     - GzipSwift (= 5.1.1)
@@ -19,7 +19,7 @@ PODS:
   - SQLite.swift/standard (0.13.2)
 
 DEPENDENCIES:
-  - clickstream_flutter (from `.symlinks/plugins/clickstream_flutter/ios`)
+  - clickstream_analytics (from `.symlinks/plugins/clickstream_analytics/ios`)
   - Flutter (from `Flutter`)
   - integration_test (from `.symlinks/plugins/integration_test/ios`)
 
@@ -30,16 +30,16 @@ SPEC REPOS:
     - SQLite.swift
 
 EXTERNAL SOURCES:
-  clickstream_flutter:
-    :path: ".symlinks/plugins/clickstream_flutter/ios"
+  clickstream_analytics:
+    :path: ".symlinks/plugins/clickstream_analytics/ios"
   Flutter:
     :path: Flutter
   integration_test:
     :path: ".symlinks/plugins/integration_test/ios"
 
 SPEC CHECKSUMS:
   Amplify: 516e5da5f256f62841b6bc659e1644bc999d7b6e
-  clickstream_flutter: d5dd3ad04cb641b27c1014c23b4cdbc98f6956dc
+  clickstream_analytics: 22312ed8d353813f1f6847aecb4e04b62bdda478
   Flutter: f04841e97a9d0b0a8025694d0796dd46242b2854
   GzipSwift: 893f3e48e597a1a4f62fafcb6514220fcf8287fa
   integration_test: 13825b8a9334a850581300559b8839134b124670