clickstream_analytics

Description:

clickstream analytics

AWS Solution Clickstream Analytics SDK for Flutter #

Introduction #
Clickstream 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, which provisions data pipeline to ingest and process event data into AWS services such as S3, Redshift.
The SDK relies on the Clickstream Android SDK and Clickstream 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.
Visit our Documentation site to learn more about Clickstream Flutter SDK.
Integrate SDK #
Include SDK #
flutter pub add clickstream_analytics
copied to clipboard
After complete, rebuild your Flutter application:
flutter run
copied to clipboard
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.
import 'package:clickstream_analytics/clickstream_analytics.dart';

final analytics = ClickstreamAnalytics();
analytics.init(
appId: "your appId",
endpoint: "https://example.com/collect"
);
copied to clipboard
Please note：

Your appId and endpoint are already set up in it.
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.
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.
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");
copied to clipboard
Login and logout
/// when user login success.
analytics.setUserId("userId");

/// when user logout
analytics.setUserId(null);
copied to clipboard
Add user attribute
analytics.setUserAttributes({
"userName": "carl",
"userAge": 22
});
copied to clipboard
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


Add global attributes when initializing the SDK
The following example code shows how to add traffic source fields as global attributes when initializing the SDK.
analytics.init({
appId: "your appId",
endpoint: "https://example.com/collect",
globalAttributes: {
Attr.TRAFFIC_SOURCE_SOURCE: "amazon",
Attr.TRAFFIC_SOURCE_MEDIUM: "cpc",
Attr.TRAFFIC_SOURCE_CAMPAIGN: "summer_promotion",
Attr.TRAFFIC_SOURCE_CAMPAIGN_ID: "summer_promotion_01",
Attr.TRAFFIC_SOURCE_TERM: "running_shoes",
Attr.TRAFFIC_SOURCE_CONTENT: "banner_ad_1",
Attr.TRAFFIC_SOURCE_CLID: "amazon_ad_123",
Attr.TRAFFIC_SOURCE_CLID_PLATFORM: "amazon_ads",
Attr.APP_INSTALL_CHANNEL: "amazon_store"
}
});
copied to clipboard


Add global attributes after initializing the SDK
analytics.addGlobalAttributes({
Attr.TRAFFIC_SOURCE_MEDIUM: "Search engine",
"level": 10
});
copied to clipboard


Delete global attribute
analytics.deleteGlobalAttributes(["level"]);
copied to clipboard
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.
Record event with items
You can add the following code to log an event with an item. you can add custom item attribute in attributes object.
Note: Only pipelines from version 1.1+ can handle items with custom attribute.
var itemBook = ClickstreamItem(
id: "123",
name: "Nature",
category: "book",
price: 99,
attributes: {
"book_publisher": "Nature Research"
}
);

analytics.record(
name: "view_item",
attributes: {
Attr.VALUE: 99,
Attr.CURRENCY: "USD"
"event_category": "recommended"
},
items: [itemBook]
);
copied to clipboard
Record Screen View events manually
By default, SDK will automatically track the preset _screen_view event when Android Activity triggers onResume or iOS ViewController triggers viewDidAppear.
You 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.

screenName Required. Your screen's name.
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.

analytics.recordScreenView(
screenName: 'Main',
screenUniqueId: '123adf',
attributes: { ... }
);
copied to clipboard
Other configurations
In addition to the required appId and endpoint, you can configure other information to get more customized usage:
final analytics = ClickstreamAnalytics();
analytics.init(
appId: "your appId",
endpoint: "https://example.com/collect",
isLogEvents: false,
isCompressEvents: false,
sendEventsInterval: 10000,
isTrackScreenViewEvents: true,
isTrackUserEngagementEvents: true,
isTrackAppExceptionEvents: false,
authCookie: "your auth cookie",
sessionTimeoutDuration: 1800000,
globalAttributes: {
"_traffic_source_medium": "Search engine",
},
);
copied to clipboard
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 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
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
globalAttributes: the global attributes when initializing the SDK.

Configuration update
You can update the default configuration after initializing the SDK, below are the additional configuration options you can customize.
final analytics = ClickstreamAnalytics();
analytics.updateConfigure(
appId: "your appId",
endpoint: "https://example.com/collect",
isLogEvents: true,
isCompressEvents: false,
isTrackScreenViewEvents: false
isTrackUserEngagementEvents: false,
isTrackAppExceptionEvents: false,
authCookie: "test cookie");
copied to clipboard
Send event immediately
final analytics = ClickstreamAnalytics();
analytics.flushEvents();
copied to clipboard
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.
final analytics = ClickstreamAnalytics();

// disable SDK
analytics.disable();

// enable SDK
analytics.enable();
copied to clipboard
How to build and test locally #
Build #
Install flutter packages
flutter pub get
copied to clipboard
Build for Android
cd example && flutter build apk
copied to clipboard
Build for iOS
cd example && flutter build ios
copied to clipboard
Format and lint #
dart format . && flutter analyze
copied to clipboard
Test #
flutter test
copied to clipboard
Security #
See CONTRIBUTING for more information.
License #
This library is licensed under the Apache 2.0 License.