feat: support disable and enable sdk (#2)

Co-authored-by: zhu-xiaowei <[email protected]>

Author: zhu-xiaowei

README.md

@@ -6,6 +6,8 @@ Clickstream Flutter SDK can help you easily collect and report events from your
 
 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.
 
+Visit our [Documentation site](https://awslabs.github.io/clickstream-analytics-on-aws/en/sdk-manual/flutter/) to learn more about Clickstream Flutter SDK.
+
 ## Integrate SDK
 
 ### Include SDK
@@ -81,7 +83,7 @@ analytics.setUserAttributes({
 });
 ```
 
-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.
+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 use the same api `analytics.setUserAttributes()` to update the current user's attribute when it changes.
 
 #### Add global attribute
 
@@ -91,6 +93,9 @@ analytics.addGlobalAttributes({
   "_traffic_source_name": "Summer promotion",
   "level": 10
 });
+
+// delete global attribute
+analytics.deleteGlobalAttributes(["level"]);
 ```
 
 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.
@@ -106,7 +111,7 @@ analytics.init(
   endpoint: "https://example.com/collect",
   isLogEvents: false,
   isCompressEvents: false,
-  sendEventsInterval: 5000,
+  sendEventsInterval: 10000,
   isTrackScreenViewEvents: true,
   isTrackUserEngagementEvents: true,
   isTrackAppExceptionEvents: false,
@@ -115,10 +120,10 @@ analytics.init(
 );
 ```
 
-Here is an explanation of each property:
+Here is an explanation of each option:
 
 - **appId (Required)**: the app id of your project in control plane.
-- **endpoint (Required)**: the endpoint path you will upload the event to AWS server.
+- **endpoint (Required)**: the endpoint path you will upload the event to Clickstream ingestion 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`
@@ -153,6 +158,21 @@ final analytics = ClickstreamAnalytics();
 analytics.flushEvents();
 ```
 
+#### 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.
+
+```dart
+final analytics = ClickstreamAnalytics();
+
+// disable SDK
+analytics.disable();
+
+// enable SDK
+analytics.enable();
+```
+
 ## How to build and test locally
 
 ### Build

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

@@ -95,6 +95,14 @@ class ClickstreamFlutterPlugin : FlutterPlugin, MethodCallHandler, ActivityAware
                 ClickstreamAnalytics.flushEvents()
             }
 
+            "disable" -> {
+                ClickstreamAnalytics.disable()
+            }
+
+            "enable" -> {
+                ClickstreamAnalytics.enable()
+            }
+
             else -> {
                 result.notImplemented()
             }

example/lib/main.dart

@@ -142,6 +142,24 @@ class _MyAppState extends State<MyApp> {
               },
               minLeadingWidth: 0,
             ),
+            ListTile(
+              leading: const Icon(Icons.disabled_by_default),
+              title: const Text('disable'),
+              onTap: () async {
+                analytics.disable();
+                log("disable");
+              },
+              minLeadingWidth: 0,
+            ),
+            ListTile(
+              leading: const Icon(Icons.check),
+              title: const Text('enable'),
+              onTap: () async {
+                analytics.enable();
+                log("enable");
+              },
+              minLeadingWidth: 0,
+            ),
           ],
         ),
       ),

ios/Classes/ClickstreamFlutterPlugin.swift

@@ -36,6 +36,10 @@ public class ClickstreamFlutterPlugin: NSObject, FlutterPlugin {
             updateConfigure(call.arguments as! [String: Any])
         case "flushEvents":
             ClickstreamAnalytics.flushEvents()
+        case "disable":
+            ClickstreamAnalytics.disable()
+        case "enable":
+            ClickstreamAnalytics.enable()
         default:
             result(FlutterMethodNotImplemented)
         }

ios/Clickstream

@@ -85,4 +85,12 @@ class ClickstreamAnalytics {
   Future<void> flushEvents() {
     return ClickstreamInterface.instance.flushEvents();
   }
+
+  Future<void> disable() {
+    return ClickstreamInterface.instance.disable();
+  }
+
+  Future<void> enable() {
+    return ClickstreamInterface.instance.enable();
+  }
 }

lib/clickstream_analytics.dart

@@ -53,4 +53,14 @@ class ClickstreamAnalyticsMethodChannel extends ClickstreamInterface {
   Future<void> flushEvents() async {
     await methodChannel.invokeMethod<void>('flushEvents');
   }
+
+  @override
+  Future<void> disable() async {
+    await methodChannel.invokeMethod<void>('disable');
+  }
+
+  @override
+  Future<void> enable() async {
+    await methodChannel.invokeMethod<void>('enable');
+  }
 }

lib/clickstream_analytics_method_channel.dart

@@ -39,22 +39,31 @@ abstract class ClickstreamInterface extends PlatformInterface {
   }
 
   Future<void> setUserAttributes(Map<String, Object?> attributes) {
-    throw UnimplementedError('setUserId() has not been implemented.');
+    throw UnimplementedError('setUserAttributes() has not been implemented.');
   }
 
   Future<void> addGlobalAttributes(Map<String, Object?> attributes) {
-    throw UnimplementedError('setUserId() has not been implemented.');
+    throw UnimplementedError('addGlobalAttributes() has not been implemented.');
   }
 
   Future<void> deleteGlobalAttributes(Map<String, Object?> attributes) {
-    throw UnimplementedError('setUserId() has not been implemented.');
+    throw UnimplementedError(
+        'deleteGlobalAttributes() has not been implemented.');
   }
 
   Future<void> updateConfigure(Map<String, Object?> configure) {
-    throw UnimplementedError('setUserId() has not been implemented.');
+    throw UnimplementedError('updateConfigure() has not been implemented.');
   }
 
   Future<void> flushEvents() {
-    throw UnimplementedError('setUserId() has not been implemented.');
+    throw UnimplementedError('flushEvents() has not been implemented.');
+  }
+
+  Future<void> disable() {
+    throw UnimplementedError('disable() has not been implemented.');
+  }
+
+  Future<void> enable() {
+    throw UnimplementedError('enable() has not been implemented.');
   }
 }

lib/clickstream_analytics_platform_interface.dart

@@ -38,6 +38,10 @@ void main() {
             return null;
           case "flushEvents":
             return null;
+          case "disable":
+            return null;
+          case "enable":
+            return null;
         }
         return null;
       },
@@ -89,7 +93,7 @@ void main() {
     expect(result, isNotNull);
   });
 
-  test('setGlobalAttributes', () async {
+  test('addGlobalAttributes', () async {
     Map<String, Object?> attributes = {
       "channel": "Play Store",
       "level": 5.1,
@@ -116,8 +120,18 @@ void main() {
     expect(result, isNotNull);
   });
 
-  test('setGlobalAttributes', () async {
+  test('flushEvents', () async {
     var result = platform.flushEvents();
     expect(result, isNotNull);
   });
+
+  test('disable', () async {
+    var result = platform.disable();
+    expect(result, isNotNull);
+  });
+
+  test('enable', () async {
+    var result = platform.enable();
+    expect(result, isNotNull);
+  });
 }

test/clickstream_flutter_method_channel_test.dart

@@ -37,6 +37,12 @@ class MockClickstreamFlutterPlatform
   @override
   Future<void> deleteGlobalAttributes(Map<String, Object?> attributes) =>
       Future.value();
+
+  @override
+  Future<void> disable() => Future.value();
+
+  @override
+  Future<void> enable() => Future.value();
 }
 
 void main() {
@@ -117,4 +123,14 @@ void main() {
     var result = analytics.flushEvents();
     expect(result, isNotNull);
   });
+
+  test('disable', () async {
+    var result = analytics.disable();
+    expect(result, isNotNull);
+  });
+
+  test('enable', () async {
+    var result = analytics.enable();
+    expect(result, isNotNull);
+  });
 }