From d3473ade581a4a9f3db51385331116f814ef0d66 Mon Sep 17 00:00:00 2001 From: Xiaowei Zhu <33129495+zhu-xiaowei@users.noreply.github.com> Date: Tue, 7 Nov 2023 12:17:12 +0800 Subject: [PATCH] feat: support disable and enable sdk (#2) Co-authored-by: zhu-xiaowei --- README.md | 28 ++++++++++++++++--- .../ClickstreamFlutterPlugin.kt | 8 ++++++ example/lib/main.dart | 18 ++++++++++++ ios/Classes/ClickstreamFlutterPlugin.swift | 4 +++ ios/Clickstream | 2 +- lib/clickstream_analytics.dart | 8 ++++++ lib/clickstream_analytics_method_channel.dart | 10 +++++++ ...ckstream_analytics_platform_interface.dart | 19 +++++++++---- ...ickstream_flutter_method_channel_test.dart | 18 ++++++++++-- test/clickstream_flutter_test.dart | 16 +++++++++++ 10 files changed, 119 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 227213a..b1a9cea 100644 --- a/README.md +++ b/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 diff --git a/android/src/main/kotlin/software/aws/solution/clickstream_analytics/ClickstreamFlutterPlugin.kt b/android/src/main/kotlin/software/aws/solution/clickstream_analytics/ClickstreamFlutterPlugin.kt index 9390d02..9f21d6e 100644 --- a/android/src/main/kotlin/software/aws/solution/clickstream_analytics/ClickstreamFlutterPlugin.kt +++ b/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() } diff --git a/example/lib/main.dart b/example/lib/main.dart index 547e002..18fcae0 100644 --- a/example/lib/main.dart +++ b/example/lib/main.dart @@ -142,6 +142,24 @@ class _MyAppState extends State { }, 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, + ), ], ), ), diff --git a/ios/Classes/ClickstreamFlutterPlugin.swift b/ios/Classes/ClickstreamFlutterPlugin.swift index 0e6613e..03ad5ce 100644 --- a/ios/Classes/ClickstreamFlutterPlugin.swift +++ b/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) } diff --git a/ios/Clickstream b/ios/Clickstream index 87f3837..a25a37b 160000 --- a/ios/Clickstream +++ b/ios/Clickstream @@ -1 +1 @@ -Subproject commit 87f38370f35d5df19014a5fbbefbbf4c6d4975c6 +Subproject commit a25a37bab1d59bc39d30e946575ba18638937b5e diff --git a/lib/clickstream_analytics.dart b/lib/clickstream_analytics.dart index 6f92790..76165da 100644 --- a/lib/clickstream_analytics.dart +++ b/lib/clickstream_analytics.dart @@ -85,4 +85,12 @@ class ClickstreamAnalytics { Future flushEvents() { return ClickstreamInterface.instance.flushEvents(); } + + Future disable() { + return ClickstreamInterface.instance.disable(); + } + + Future enable() { + return ClickstreamInterface.instance.enable(); + } } diff --git a/lib/clickstream_analytics_method_channel.dart b/lib/clickstream_analytics_method_channel.dart index 9973ac0..f8e6d8d 100644 --- a/lib/clickstream_analytics_method_channel.dart +++ b/lib/clickstream_analytics_method_channel.dart @@ -53,4 +53,14 @@ class ClickstreamAnalyticsMethodChannel extends ClickstreamInterface { Future flushEvents() async { await methodChannel.invokeMethod('flushEvents'); } + + @override + Future disable() async { + await methodChannel.invokeMethod('disable'); + } + + @override + Future enable() async { + await methodChannel.invokeMethod('enable'); + } } diff --git a/lib/clickstream_analytics_platform_interface.dart b/lib/clickstream_analytics_platform_interface.dart index 68edaf6..033d9dd 100644 --- a/lib/clickstream_analytics_platform_interface.dart +++ b/lib/clickstream_analytics_platform_interface.dart @@ -39,22 +39,31 @@ abstract class ClickstreamInterface extends PlatformInterface { } Future setUserAttributes(Map attributes) { - throw UnimplementedError('setUserId() has not been implemented.'); + throw UnimplementedError('setUserAttributes() has not been implemented.'); } Future addGlobalAttributes(Map attributes) { - throw UnimplementedError('setUserId() has not been implemented.'); + throw UnimplementedError('addGlobalAttributes() has not been implemented.'); } Future deleteGlobalAttributes(Map attributes) { - throw UnimplementedError('setUserId() has not been implemented.'); + throw UnimplementedError( + 'deleteGlobalAttributes() has not been implemented.'); } Future updateConfigure(Map configure) { - throw UnimplementedError('setUserId() has not been implemented.'); + throw UnimplementedError('updateConfigure() has not been implemented.'); } Future flushEvents() { - throw UnimplementedError('setUserId() has not been implemented.'); + throw UnimplementedError('flushEvents() has not been implemented.'); + } + + Future disable() { + throw UnimplementedError('disable() has not been implemented.'); + } + + Future enable() { + throw UnimplementedError('enable() has not been implemented.'); } } diff --git a/test/clickstream_flutter_method_channel_test.dart b/test/clickstream_flutter_method_channel_test.dart index 466cd81..c41cba4 100644 --- a/test/clickstream_flutter_method_channel_test.dart +++ b/test/clickstream_flutter_method_channel_test.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 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); + }); } diff --git a/test/clickstream_flutter_test.dart b/test/clickstream_flutter_test.dart index 7074dd9..e387cfc 100644 --- a/test/clickstream_flutter_test.dart +++ b/test/clickstream_flutter_test.dart @@ -37,6 +37,12 @@ class MockClickstreamFlutterPlatform @override Future deleteGlobalAttributes(Map attributes) => Future.value(); + + @override + Future disable() => Future.value(); + + @override + Future 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); + }); }