[Feature] Anonymous User Tracking

AnonymousUserEventTracking.md

@@ -0,0 +1,124 @@
+# AnonymousUserManager Class
+
+## Class Introduction
+
+The `AnonymousUserManager` class is responsible for managing anonymous user sessions and tracking events in an Android application.
+It includes methods for updating sessions, tracking events, and handling criteria for transitioning to known users.
+
+## Class Structure
+
+The `AnonymousUserManager` class includes the following key components:
+
+- **Fields:**
+    - `TAG`: A constant String for logging.
+
+- **Methods:**
+    - `updateAnonSession()`: Updates the anonymous user session.
+    - `trackAnonEvent(String eventName, JSONObject dataFields)`: Tracks an anonymous event.
+    - `trackAnonPurchaseEvent(double total, List<CommerceItem> items, JSONObject dataFields)`: Tracks an anonymous purchase event.
+    - `trackAnonUpdateCart(List<CommerceItem> items)`: Tracks an anonymous cart update.
+    - `getCriteria()`: Retrieves criteria for user transition.
+    - `checkCriteriaCompletion()`: Checks if criteria for user transition are met.
+    - `createKnownUser()`: Creates a known user after criteria are met.
+    - `syncEvents()`: Syncs tracked events with the server.
+    - `clearLocallyStoredData()`: Clears locally stored data.
+    - `storeEventListToLocalStorage(JSONObject newDataObject)`: Stores event data in local storage.
+    - `getEventListFromLocalStorage()`: Retrieves event data from local storage.
+    - `getCurrentTime()`: Gets the current time in milliseconds.
+    - `getCurrentDateTime()`: Gets the current date and time in UTC format.
+
+## Methods Description
+
+### `updateAnonSession()`
+
+This method updates the anonymous user session. It does the following:
+
+* Retrieves the previous session data from SharedPreferences.
+* Increments the session number.
+* Stores the updated session data in SharedPreferences.
+
+### `trackAnonEvent(eventName, dataFields)`
+
+This method tracks an anonymous event. It does the following:
+
+* Creates a JSON object with event details, including the event name, timestamp, data fields, and tracking type.
+* Stores the event data in local storage.
+* Checks criteria completion and creates a known user if criteria are met.
+
+### `trackAnonPurchaseEvent(total, items, dataFields)`
+
+This method tracks an anonymous purchase event. It does the following:
+
+* Converts the list of commerce items to JSON.
+* Creates a JSON object with purchase event details, including items, total, timestamp, data fields, and tracking type.
+* Stores the purchase event data in local storage.
+* Checks criteria completion and creates a known user if criteria are met.
+
+### `trackAnonUpdateCart(items)`
+
+This method tracks an anonymous cart update. It does the following:
+
+* Converts the list of commerce items to JSON.
+* Creates a JSON object with cart update details, including items, timestamp, and tracking type.
+* Stores the cart update data in local storage.
+* Checks criteria completion and creates a known user if criteria are met.
+
+### `getCriteria()`
+
+This method is responsible for fetching criteria data. It simulates calling an API and saving data in SharedPreferences.
+
+### `checkCriteriaCompletion()`
+
+This private method checks if criteria for creating a known user are met. It compares stored event data with predefined criteria and returns `true` if criteria are completed.
+
+### `createKnownUser()`
+
+This  method is responsible for creating a known user in the Iterable API. It does the following:
+
+* Sets a random user ID using a UUID (Universally Unique Identifier).
+* Retrieves user session data from SharedPreferences.
+* If user session data exists, it updates the user information in the Iterable API.
+* Calls the syncEvents() method to synchronize tracked events.
+* Finally, it clears locally stored data using the clearLocallyStoredData() method.
+
+### `syncEvents()`
+
+This method is used to synchronize tracked events stored in local storage with the Iterable API. It performs the following tasks:
+
+* Retrieves the list of tracked events from local storage using the getEventListFromLocalStorage() method.
+* Iterates through the list of events and processes each event based on its type.
+* Supported event types include regular event tracking, purchase event tracking, and cart update tracking.
+* For each event, it extracts relevant data, including event name, data fields, items (for purchase and cart update events), and timestamps.
+* It uses the Iterable API to track these events or update the user's cart.
+* After processing all events, it calls the clearLocallyStoredData() method to clear locally stored event data.
+
+### `clearLocallyStoredData()`
+
+This method is responsible for clearing locally stored data in SharedPreferences. It removes both the anonymous session data and the event list data, effectively cleaning up after successful synchronization with the Iterable API.
+
+### `storeEventListToLocalStorage(JSONObject newDataObject)`
+
+This method is used to add a new event to the list of events stored in local storage. It takes a JSON object representing the new event data and performs the following steps:
+
+* Retrieves the existing list of events from local storage using the getEventListFromLocalStorage() method.
+* Appends the new event data to the list.
+* Updates the event list data in SharedPreferences.
+
+### `getEventListFromLocalStorage()`
+
+This method retrieves the list of tracked events from local storage in SharedPreferences. It returns a JSONArray containing the stored event data. If no data is found or an error occurs during retrieval, it returns an empty JSONArray.
+
+### `getCurrentTime()`
+
+This method returns the current timestamp as a long value, representing the number of milliseconds
+
+## Usage
+
+You can use the `AnonymousUserManager` class to manage anonymous user sessions, track events, and determine when to create known users based on predefined criteria.
+
+```java
+// Example usage
+AnonymousUserManager userManager = new AnonymousUserManager();
+userManager.updateAnonSession();
+userManager.trackAnonEvent("UserLoggedIn", userData);
+userManager.trackAnonPurchaseEvent(100.0, items, otherData);

AnonymousUserMerge.md

@@ -0,0 +1,38 @@
+# AnonymousUserMerge Class
+
+## Class Introduction
+
+The `AnonymousUserMerge` class is responsible for merging anonymous user with logged-in one.
+It includes methods for merge user by userId and emailId.
+We call methods of this class internally to merge user when setUserId or setEmail method call. After merge we sync events through Iterable API.
+
+## Class Structure
+
+The `AnonymousUserMerge` class includes the following key components:
+
+- **Methods:**
+  - `mergeUserUsingUserId(apiClient: IterableApiClient, destinationUserId: String)`: Merge user using userID if anonymous user exists and sync events
+  - `mergeUserUsingEmail(apiClient: IterableApiClient, destinationEmail: String)`: Merge user using emailId if anonymous user exists and sync events
+  - `callMergeApi(apiClient: IterableApiClient, sourceEmail: String, sourceUserId: String, destinationEmail: String, destinationUserId: String)`: Call API to merge user and sync remaining events.
+
+## Methods Description
+
+### `mergeUserUsingUserId(apiClient: IterableApiClient, destinationUserId: String)`
+
+This method merge the anonymous user with the logged-in one. It does the following:
+
+* Check for user exists using userId.
+* If user exists then call the merge user API.
+
+### `mergeUserUsingEmail(apiClient: IterableApiClient, destinationEmail: String)`
+
+This method merge the anonymous user with the logged-in one. It does the following:
+
+* Check for user exists using emailId.
+* If user exists then call the merge user API.
+
+### `callMergeApi(apiClient: IterableApiClient, sourceEmail: String, sourceUserId: String, destinationEmail: String, destinationUserId: String)`
+
+This method call API to merge user. It does the following:
+
+* Call the Iterable API and sync remaining events.

app/build.gradle

@@ -53,6 +53,7 @@ dependencies {
     implementation 'androidx.multidex:multidex:2.0.1'
     implementation 'androidx.annotation:annotation:1.1.0'
     implementation 'androidx.fragment:fragment:1.2.4'
+    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
     debugImplementation 'androidx.fragment:fragment-testing:1.2.4'
 
     implementation project(':iterableapi')

app/src/main/AndroidManifest.xml

@@ -1,21 +1,28 @@
 <?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     xmlns:tools="http://schemas.android.com/tools">
-    <uses-sdk tools:overrideLibrary="androidx.security"/>
+
+    <uses-sdk tools:overrideLibrary="androidx.security" />
+
     <application
         android:allowBackup="true"
         android:icon="@mipmap/ic_launcher"
         android:label="@string/app_name"
         android:supportsRtl="true"
         android:theme="@style/AppTheme">
+        <activity
+            android:name="com.iterable.androidsdk.AnonTrackingTestActivity"
+            android:exported="false" />
         <activity
             android:name="com.iterable.androidsdk.MainActivity"
             android:label="@string/app_name"
             android:theme="@style/AppTheme.NoActionBar">
             <intent-filter>
                 <action android:name="android.intent.action.MAIN" />
+
                 <category android:name="android.intent.category.LAUNCHER" />
             </intent-filter>
         </activity>
     </application>
+
 </manifest>

app/src/main/java/com/iterable/androidsdk/AnonTrackingTestActivity.java

@@ -0,0 +1,129 @@
+package com.iterable.androidsdk;
+
+import androidx.appcompat.app.AppCompatActivity;
+
+import android.content.Context;
+import android.content.SharedPreferences;
+import android.os.Bundle;
+import android.os.Handler;
+import android.util.Log;
+import android.widget.EditText;
+import com.iterable.iterableapi.CommerceItem;
+import com.iterable.iterableapi.IterableApi;
+import com.iterable.iterableapi.IterableConfig;
+import com.iterable.iterableapi.IterableConstants;
+import com.iterable.iterableapi.testapp.R;
+import org.json.JSONArray;
+import org.json.JSONException;
+import org.json.JSONObject;
+import java.util.ArrayList;
+import java.util.List;
+
+public class AnonTrackingTestActivity extends AppCompatActivity {
+
+    @Override
+    protected void onCreate(Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        setContentView(R.layout.activity_test);
+
+        IterableConfig iterableConfig = new IterableConfig.Builder().setEnableAnonTracking(true).build();
+
+        // clear data for testing
+        SharedPreferences sharedPref = getSharedPreferences(IterableConstants.SHARED_PREFS_FILE, Context.MODE_PRIVATE);
+        SharedPreferences.Editor editor = sharedPref.edit();
+        editor.putString(IterableConstants.SHARED_PREFS_ANON_SESSIONS, "");
+        editor.putString(IterableConstants.SHARED_PREFS_EVENT_LIST_KEY, "");
+        editor.apply();
+
+        new Handler().postDelayed(() -> {
+            IterableApi.initialize(getBaseContext(), "18845050c4774b7c9dc48beece2f6d8b", iterableConfig);
+            IterableApi.getInstance().setUserId(null);
+            IterableApi.getInstance().setEmail(null);
+
+        }, 1000);
+
+        findViewById(R.id.updateCart).setOnClickListener(view -> {
+            EditText updateCart_edit = findViewById(R.id.updateCart_edit);
+            if(updateCart_edit == null) return;
+            Log.d("TEST_USER", String.valueOf(updateCart_edit.getText()));
+            try {
+                JSONArray cartJSOnItems = new JSONArray(String.valueOf(updateCart_edit.getText()));
+                List<CommerceItem> items = new ArrayList<>();
+                for(int i = 0; i < cartJSOnItems.length(); i++) {
+                    final JSONObject item = cartJSOnItems.getJSONObject(i);
+                    items.add(new CommerceItem(item.getString("id"), item.getString("name"), item.getDouble("price"), item.getInt("quantity")));
+                }
+                IterableApi.getInstance().updateCart(items);
+            } catch (JSONException e) {
+                throw new RuntimeException(e);
+            }
+        });
+        findViewById(R.id.trackPurchase).setOnClickListener(view -> {
+            EditText purchase_items = findViewById(R.id.trackPurchase_edit);
+            if(purchase_items == null) return;
+            Log.d("TEST_USER", String.valueOf(purchase_items.getText()));
+
+            int total;
+
+            try {
+                JSONObject jsonData = new JSONObject(String.valueOf(purchase_items.getText()));
+                total = (int) jsonData.get("total");
+                  JSONArray items_array = jsonData.getJSONArray("items");
+                  List<CommerceItem> items = new ArrayList<>();
+                  for(int i = 0; i < items_array.length(); i++) {
+                      final JSONObject item = items_array.getJSONObject(i);
+                      items.add(new CommerceItem(item.getString("id"), item.getString("name"), item.getDouble("price"), item.getInt("quantity")));
+                  }
+                IterableApi.getInstance().trackPurchase(total, items);
+            } catch (JSONException e) {
+                throw new RuntimeException(e);
+            }
+        });
+        findViewById(R.id.customEvent).setOnClickListener(view -> {
+            EditText customEvent_edit = findViewById(R.id.customEvent_edit);
+            if(customEvent_edit == null) return;
+            Log.d("TEST_USER", String.valueOf(customEvent_edit.getText()));
+
+            try {
+              JSONObject customEventItem = new JSONObject(String.valueOf(customEvent_edit.getText()));
+              JSONObject items = new JSONObject(customEventItem.get("dataFields").toString());
+              if(customEventItem.has("eventName")) {
+                  items.put("eventName", customEventItem.getString("eventName"));
+              }
+              IterableApi.getInstance().track("customEvent", 0, 0, items);
+            } catch (JSONException e) {
+                throw new RuntimeException(e);
+            }
+        });
+        findViewById(R.id.updateUser).setOnClickListener(view -> {
+            EditText updateUser_edit = findViewById(R.id.updateUser_edit);
+            if(updateUser_edit == null) return;
+            Log.d("TEST_USER", String.valueOf(updateUser_edit.getText()));
+
+            try {
+                JSONObject updateUserItem = new JSONObject(String.valueOf(updateUser_edit.getText()));
+                IterableApi.getInstance().updateUser(updateUserItem);
+
+            } catch (JSONException e) {
+                throw new RuntimeException(e);
+            }
+        });
+        findViewById(R.id.setUser).setOnClickListener(view -> {
+            EditText setUser_edit = findViewById(R.id.setUser_edit);
+            if(setUser_edit == null) return;
+
+            IterableApi.getInstance().setUserId(String.valueOf(setUser_edit.getText()));
+        });
+        findViewById(R.id.setEmail).setOnClickListener(view -> {
+            EditText setEmail_edit = findViewById(R.id.setEmail_edit);
+            if(setEmail_edit == null) return;
+
+            IterableApi.getInstance().setEmail(String.valueOf(setEmail_edit.getText()));
+        });
+
+        findViewById(R.id.btn_logout).setOnClickListener(view -> {
+            IterableApi.getInstance().setUserId(null);
+        });
+
+    }
+}