feat: support record screen view event manually (#63)

Author: zhu-xiaowei

README.md

@@ -204,6 +204,27 @@ ClickstreamEvent event = ClickstreamEvent.builder()
 ClickstreamAnalytics.recordEvent(event);
 ```
 
+#### Record Screen View events manually
+
+By default, SDK will automatically track the preset `_screen_view` event when Activity triggers `onResume`.
+
+You can also manually record screen view events whether or not automatic screen view tracking is enabled, add the following code to record a screen view event with two attributes.
+
+* `SCREEN_NAME` Required. Your screen's name.
+* `SCREEN_UNIQUE_ID` Optional. Set the hashcode of your Activity, Fragment, or View. If you do not set, SDK will set a default value based on the current Activity's hashcode.
+
+```java
+import software.aws.solution.clickstream.ClickstreamAnalytcs;
+
+ClickstreamEvent event = ClickstreamEvent.builder()
+     .name(ClickstreamAnalytics.Event.SCREEN_VIEW)
+     .add(ClickstreamAnalytics.Attr.SCREEN_NAME, "HomeFragment")
+     .add(ClickstreamAnalytics.Attr.SCREEN_UNIQUE_ID, String.valueOf(HomeFragment.hashCode()))
+     .build();
+
+ClickstreamAnalytics.recordEvent(event);
+```
+
 #### Log the event json in debug mode
 
 ```java

clickstream/src/main/java/software/aws/solution/clickstream/AWSClickstreamPlugin.java

@@ -103,7 +103,7 @@ public synchronized void enable() {
     public void recordEvent(@NonNull String eventName) {
         final AnalyticsEvent event = analyticsClient.createEvent(eventName);
         if (event != null) {
-            analyticsClient.recordEvent(event);
+            recordAnalyticsEvent(event);
         }
     }
 
@@ -121,7 +121,15 @@ public void recordEvent(@NonNull AnalyticsEventBehavior analyticsEvent) {
                 }
             }
             clickstreamEvent.addItems(event.getItems());
-            analyticsClient.recordEvent(clickstreamEvent);
+            recordAnalyticsEvent(clickstreamEvent);
+        }
+    }
+
+    private void recordAnalyticsEvent(AnalyticsEvent event) {
+        if (event.getEventType().equals(Event.PresetEvent.SCREEN_VIEW)) {
+            activityLifecycleManager.onScreenViewManually(event);
+        } else {
+            analyticsClient.recordEvent(event);
         }
     }
 

clickstream/src/main/java/software/aws/solution/clickstream/ActivityLifecycleManager.java

@@ -26,6 +26,7 @@
 
 import com.amazonaws.logging.Log;
 import com.amazonaws.logging.LogFactory;
+import software.aws.solution.clickstream.client.AnalyticsEvent;
 import software.aws.solution.clickstream.client.AutoRecordEventClient;
 import software.aws.solution.clickstream.client.ClickstreamManager;
 import software.aws.solution.clickstream.client.ScreenRefererTool;
@@ -92,10 +93,18 @@ public void onActivityResumed(final Activity activity) {
                 autoRecordEventClient.resetLastEngageTime();
             }
         }
-        autoRecordEventClient.recordViewScreen(activity);
+        autoRecordEventClient.recordViewScreenAutomatically(activity);
         isFromForeground = false;
     }
 
+    /**
+     * Handle Screen View triggered manually.
+     * @param event the screen view event
+     */
+    public void onScreenViewManually(AnalyticsEvent event) {
+        autoRecordEventClient.recordViewScreenManually(event);
+    }
+
     @Override
     public void onActivityPaused(final Activity activity) {
         // onPause is always followed by onStop except when the app is interrupted by an event such

clickstream/src/main/java/software/aws/solution/clickstream/ClickstreamAnalytics.java

@@ -25,7 +25,8 @@
 import com.amazonaws.logging.LogFactory;
 import software.aws.solution.clickstream.client.AnalyticsClient;
 import software.aws.solution.clickstream.client.ClickstreamConfiguration;
-import software.aws.solution.clickstream.client.Event;
+import software.aws.solution.clickstream.client.Event.PresetEvent;
+import software.aws.solution.clickstream.client.Event.ReservedAttribute;
 import software.aws.solution.clickstream.client.util.ThreadUtil;
 
 /**
@@ -101,7 +102,7 @@ public static void deleteGlobalAttributes(@NonNull String... attributeName) {
      * @param userProfile user
      */
     public static void addUserAttributes(ClickstreamUserAttribute userProfile) {
-        Amplify.Analytics.identifyUser(Event.ReservedAttribute.USER_ID_UNSET, userProfile);
+        Amplify.Analytics.identifyUser(ReservedAttribute.USER_ID_UNSET, userProfile);
     }
 
     /**
@@ -213,4 +214,31 @@ public static class Item {
          */
         public static final String ITEM_CATEGORY5 = "item_category5";
     }
+
+    /**
+     * Preset Event.
+     */
+    public static class Event {
+
+        /**
+         * screen view.
+         */
+        public static final String SCREEN_VIEW = PresetEvent.SCREEN_VIEW;
+    }
+
+    /**
+     * Preset Attributes.
+     */
+    public static class Attr {
+
+        /**
+         * screen name.
+         */
+        public static final String SCREEN_NAME = ReservedAttribute.SCREEN_NAME;
+
+        /**
+         * screen unique id.
+         */
+        public static final String SCREEN_UNIQUE_ID = ReservedAttribute.SCREEN_UNIQUE_ID;
+    }
 }

clickstream/src/main/java/software/aws/solution/clickstream/client/AutoRecordEventClient.java

@@ -78,7 +78,7 @@ public AutoRecordEventClient(@NonNull final ClickstreamContext clickstreamContex
      *
      * @param activity the activity to record.
      */
-    public void recordViewScreen(Activity activity) {
+    public void recordViewScreenAutomatically(Activity activity) {
         if (!clickstreamContext.getClickstreamConfiguration().isTrackScreenViewEvents()) {
             return;
         }
@@ -93,6 +93,39 @@ public void recordViewScreen(Activity activity) {
         ScreenRefererTool.setCurrentScreenUniqueId(screenUniqueId);
         final AnalyticsEvent event =
             this.clickstreamContext.getAnalyticsClient().createEvent(Event.PresetEvent.SCREEN_VIEW);
+        recordScreenViewEvent(event);
+    }
+
+    /**
+     * record view screen event manually.
+     *
+     * @param event the screen view event to be recorded.
+     */
+    public void recordViewScreenManually(AnalyticsEvent event) {
+        String screenName = event.getStringAttribute(Event.ReservedAttribute.SCREEN_NAME);
+        if (screenName != null) {
+            if (ScreenRefererTool.getCurrentScreenName() != null) {
+                recordUserEngagement();
+            }
+            ScreenRefererTool.setCurrentScreenName(screenName);
+            String screenUniqueId = event.getStringAttribute(Event.ReservedAttribute.SCREEN_UNIQUE_ID);
+            if (screenUniqueId != null) {
+                ScreenRefererTool.setCurrentScreenUniqueId(screenUniqueId);
+            }
+            recordScreenViewEvent(event);
+        } else {
+            LOG.error("record an _screen_view event without the required screen name attribute");
+            final AnalyticsEvent errorEvent =
+                this.clickstreamContext.getAnalyticsClient().createEvent(Event.PresetEvent.CLICKSTREAM_ERROR);
+            errorEvent.addAttribute(Event.ReservedAttribute.ERROR_CODE,
+                Event.ErrorCode.SCREEN_VIEW_MISSING_SCREEN_NAME);
+            errorEvent.addAttribute(Event.ReservedAttribute.ERROR_MESSAGE,
+                "record an _screen_view event without the required screen name attribute");
+            this.clickstreamContext.getAnalyticsClient().recordEvent(errorEvent);
+        }
+    }
+
+    private void recordScreenViewEvent(AnalyticsEvent event) {
         long currentTimestamp = event.getEventTimestamp();
         startEngageTimestamp = currentTimestamp;
         event.addAttribute(Event.ReservedAttribute.SCREEN_ID, ScreenRefererTool.getCurrentScreenId());
@@ -111,8 +144,6 @@ public void recordViewScreen(Activity activity) {
         this.clickstreamContext.getAnalyticsClient().recordEvent(event);
         PreferencesUtil.savePreviousScreenViewTimestamp(preferences, currentTimestamp);
         isEntrances = false;
-        LOG.debug("record an _screen_view event, screenId:" + screenId + "lastScreenId:" +
-            ScreenRefererTool.getPreviousScreenId());
     }
 
     /**

clickstream/src/main/java/software/aws/solution/clickstream/client/Event.java

@@ -144,6 +144,11 @@ public static final class ErrorCode {
          */
         public static final int ITEM_CUSTOM_ATTRIBUTE_KEY_INVALID = 4005;
 
+        /**
+         * screen view event missing screen name attribute.
+         */
+        public static final int SCREEN_VIEW_MISSING_SCREEN_NAME = 5001;
+
         private ErrorCode() {
         }
     }

clickstream/src/test/java/software/aws/solution/clickstream/ActivityLifecycleManagerUnitTest.java

@@ -150,6 +150,6 @@ public void testScreenView() {
         callbacks.onActivityCreated(activity, bundle);
         callbacks.onActivityStarted(activity);
         callbacks.onActivityResumed(activity);
-        verify(autoRecordEventClient).recordViewScreen(activity);
+        verify(autoRecordEventClient).recordViewScreenAutomatically(activity);
     }
 }