chore: update readme with usage guide (#13)

1. update readme for usage doc 2. fix publishing.gradle with no keyFile. --------- Co-authored-by: xiaoweii <[email protected]>
aws-solutions · May 19, 2023 · 42dfd3f · 42dfd3f
1 parent 923502d
commit 42dfd3f
Show file tree

Hide file tree

Showing 4 changed files with 204 additions and 26 deletions.
diff --git a/README.md b/README.md
@@ -1,6 +1,7 @@
 # AWS Solution Clickstream Analytics SDK for Android
-
+[![Maven Central](https://img.shields.io/maven-central/v/software.aws.solution/clickstream.svg)](https://search.maven.org/artifact/software.aws.solution/clickstream)
 ## Introduction
+
 Clickstream Android SDK can help you easily report in-app events on Android. After the event is reported, statistics and analysis of specific scenario data can be completed on AWS Clickstream solution.
 
 The SDK relies on the Amplify for Android SDK Core Library and is developed according to the Amplify Android SDK plug-in specification, while using the same event definitions and attribute specifications as amplifyframework analytics. In addition to this, we've added commonly used preset event statistics to make it easier to use.
@@ -9,26 +10,200 @@ The SDK relies on the Amplify for Android SDK Core Library and is developed acco
 
 The Clickstream SDK supports Android API level 16 (Android 4.1) and above.
 
+## Integrate SDK
+
+**1.Include SDK**
+
+Add the following dependency to your `app` module's `build.gradle` file.
+
+```groovy
+dependencies {
+    implementation 'software.aws.solution:clickstream:0.4.1'
+}
+```
+
+then sync your project.
+
+**2.Parameter configuration**
+
+Find the res directory under your  `project/app/src/main` , and manually create a raw folder in the res directory. 
+
+![](images/raw_folder.png)
+
+Downlod your `amplifyconfiguration.json` file from your clickstream control plane, and paste it to raw floder, the json file will be as following:
+
+```json
+{
+  "analytics": {
+    "plugins": {
+      "awsClickstreamPlugin": {
+        "appId": "appId",
+        "endpoint": "https://example.com/collect",
+        "isCompressEvents": true,
+        "autoFlushEventsInterval": 10000,
+        "isTrackAppExceptionEvents": false
+      }
+    }
+  }
+}
+```
+
+Your `appId` and `endpoint` are already set up in it, here's an explanation of each property:
+
+- **appId**: the app id of your project in control plane.
+- **endpoint**: the endpoint url you will upload the event to AWS server.
+- **isCompressEvents**: whether to compress event content when uploading events, default is `true`
+- **autoFlushEventsInterval**: event sending interval, the default is `10s`
+- **isTrackAppExceptionEvents**: whether auto track exception event in app, default is `true`
+
+**3.Initialize the SDK**
+
+Please Initialize the SDK in the Application `onCreate()` method.
+
+```java
+import software.aws.solution.clickstream.ClickstreamAnalytics;
+
+public void onCreate() {
+    super.onCreate();
+
+    try{
+        ClickstreamAnalytics.init(this);
+        Log.i("MyApp", "Initialized ClickstreamAnalytics");
+    } catch (AmplifyException error){
+        Log.e("MyApp", "Could not initialize ClickstreamAnalytics", error);
+    } 
+}
+```
+
+**4.Config the SDK**
+
+After initial the SDK we can use the following code to custom configure it.
+
+```java
+import software.aws.solution.clickstream.ClickstreamAnalytics;
+
+// config the SDK after initialize.
+ClickstreamAnalytics.getClickStreamConfiguration()
+            .withAppId("appId")
+            .withEndpoint("https://example.com/collect")
+            .withAuthCookie("your authentication cookie")
+            .withSendEventsInterval(10000)
+            .withSessionTimeoutDuration(1800000)
+            .withTrackAppExceptionEvents(false)
+            .withLogEvents(true)
+            .withCustomDns(CustomOkhttpDns.getInstance())
+            .withCompressEvents(true);
+```
+
+> note: this configuration will override the default configuration in `amplifyconfiguration.json` file.
+
+### Start using
+
+Now that you've integrated the SDK, let's start using it in your app.
+
+#### Record event
+
+Add the following code where you need to report an event.
+
+```java
+import software.aws.solution.clickstream.ClickstreamAnalytics;
+import com.amplifyframework.analytics.AnalyticsEvent;
+
+AnalyticsEvent event = AnalyticsEvent.builder()
+    .name("PasswordReset")
+    .add("Channel", "SMS")
+    .add("Successful", true)
+    .add("ProcessDuration", 78.2)
+    .add("UserAge", 20)
+    .build();
+ClickstreamAnalytics.recordEvent(event);
+
+// for record an event directly
+ClickstreamAnalytics.recordEvent("button_click");
+```
+
+#### Add global attribute
+
+```java
+import software.aws.solution.clickstream.ClickstreamAttribute;
+import software.aws.solution.clickstream.ClickstreamAnalytics;
+
+ClickstreamAttribute globalAttribute = ClickstreamAttribute.builder()
+    .add("channel", "HUAWEI")
+    .add("level", 5.1)
+    .add("class", 6)
+    .add("isOpenNotification", true)
+    .build();
+ClickstreamAnalytics.addGlobalAttributes(globalAttribute);
+
+// for delete an global attribute
+ClickstreamAnalytics.deleteGlobalAttributes("level");
+```
+
+#### Login and logout
+
+```java
+import software.aws.solution.clickstream.ClickstreamAnalytics;
+
+// when user login success.
+ClickstreamAnalytics.setUserId("UserId");
+
+// when user logout
+ClickstreamAnalytics.setUserId(null);
+```
+
+When we log into another user, we will clear the before user's user attributes, after `setUserId()` you need add your user's attribute.
+
+#### Add user attribute
+
+```java
+import software.aws.solution.clickstream.ClickstreamAnalytcs;
+import software.aws.solution.clickstream.ClickstreamUserAttribute;
+
+ClickstreamUserAttribute clickstreamUserAttribute = ClickstreamUserAttribute.builder()
+    .add("_user_age", 21)
+    .add("_user_name", "carl")
+    .build();
+ClickstreamAnalytics.addUserAttributes(clickstreamUserAttribute);
+```
+
+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 update the current user's attribute when it changes.
+
+#### Log the event json in debug mode
+
+```java
+import software.aws.solution.clickstream.ClickstreamAnalytics;
+
+// log the event in debug mode.
+ClickstreamAnalytics.getClickStreamConfiguration()
+            .withLogEvents(BuildConfig.DEBUG);
+```
+
+after config `.withLogEvents(true)` and when you record an event, you can see the event json at your AndroidStudio **Logcat** by filter `EventRecorder`.
+
+#### Config custom DNS
+
+```java
+import software.aws.solution.clickstream.ClickstreamAnalytics;
+
+// config custom dns.
+ClickstreamAnalytics.getClickStreamConfiguration()
+            .withCustomDns(CustomOkhttpDns.getInstance());
+```
+
+If you want to use custom DNS for network request, you can create your `CustomOkhttpDns` which implementaion `okhttp3.Dns`, then config `.withCustomDns(CustomOkhttpDns.getInstance())` to make it works.
+
+#### Send event immediately
+
+```java
+// for send event immediately.
+ClickstreamAnalytics.flushEvent();
+```
+
 ## How to build locally
-### Config your local environment
-First of all you should install the latest version of [Android Studio](https://developer.android.com/studio).
-####  Config your checkstyle:
-1. Open your Android Studio -> Preferences -> Tools -> check style window.
-2. Change the check style version to 8.29.
-3. Add config file from ./configuration/checkstyle.gradle. then check and apply.
-
-####  Config your code format
-1. Open your Android Studio -> Preferences -> Editor -> Code Style -> Java window.
-2. Click the top setting icon -> import scheme -> checkstyle configuration
-3. Select ./configuration/checkstyle.gradle file, then click ok to submit.
-4. Config your Reformat code keymap to format your code with checkstyle configured above.
-
-#### Config your java version
-1. Open your Android Studio -> Preferences ->  Build, Execution, Deployment -> Build Tools -> Gradle window.
-2. make sure you `Gradle JDK` version is set to the 1.8, then click apply and ok.
-
-###  Build aar
-open an terminal window,at the root project folder to execute:
+
+open an terminal window, at the root project folder to execute:
+
 ```shell
 ./gradlew build -p clickstream
 ```

diff --git a/build.gradle b/build.gradle
@@ -75,6 +75,7 @@ subprojects { project ->
     afterEvaluate {
         configAndroidLibrary(project)
         project.apply from: '../jacoco.gradle'
+        project.apply from: '../publishing.gradle'
     }
 }
 

diff --git a/images/raw_folder.png b/images/raw_folder.png
diff --git a/publishing.gradle b/publishing.gradle
@@ -21,7 +21,7 @@ version = project.ext.VERSION_NAME
 group = POM_GROUP
 def keyFile = rootProject.file("key.properties")
 def keyProp = new Properties()
-keyProp.load(keyFile.newInputStream())
+keyFile.exists() ? keyProp.load(keyFile.newInputStream()) : keyProp
 
 afterEvaluate { project ->
     publishing {
@@ -89,10 +89,12 @@ afterEvaluate { project ->
     }
 
     signing {
-        def signingPassword = keyProp.getProperty("signing.password")
-        def keyId = keyProp.getProperty("signing.keyId")
-        def signingKey = keyProp.getProperty("signing.inMemoryKey").replace("\\n", "\n")
-        useInMemoryPgpKeys(keyId, signingKey, signingPassword)
-        sign publishing.publications.library
+        if (keyFile.exists()) {
+            def signingPassword = keyProp.getProperty("signing.password")
+            def keyId = keyProp.getProperty("signing.keyId")
+            def signingKey = keyProp.getProperty("signing.inMemoryKey").replace("\\n", "\n")
+            useInMemoryPgpKeys(keyId, signingKey, signingPassword)
+            sign publishing.publications.library
+        }
     }
 }