Refactor new Identity System to User Hub in android/iOS (#151)

* Update new Identity section to User Hub * android - Refactor identity-users page to identity-user-hub * iOS - Refactor identity-users page to identity-user-hub * android - Update release note page * Unity - Update fullPrivacy code snippet to pass bool instead of string * Refactor section name from updating to adding user identities * android/iOS - Move tracking apis to user hub * android/iOS - Update max char limits applicable in identities/attributes * Update ss for dashboard identity secret key * Apply suggestions from code review * iOS - Refactor identity-users page to identity-user-hub * android/iOS - Refactor Support to Customer Success
helpshift · Nov 29, 2024 · ef10627 · ef10627
1 parent 64190eb
commit ef10627
Show file tree

Hide file tree

Showing 16 changed files with 328 additions and 182 deletions.
diff --git a/docs/sdkx-unity/sdk-configuration-android.mdx b/docs/sdkx-unity/sdk-configuration-android.mdx
@@ -347,7 +347,7 @@ public class MyGameControl : MonoBehaviour
 
     void OpenHelpshift() {
       Dictionary<string, object> configMap = new Dictionary<string, object>();
-      configMap.Add("fullPrivacy", "true");
+      configMap.Add("fullPrivacy", true);
       help.ShowConversation(configMap);
     }
 }

diff --git a/docs/sdkx-unity/sdk-configuration-ios.mdx b/docs/sdkx-unity/sdk-configuration-ios.mdx
@@ -225,7 +225,7 @@ public class MyGameControl : MonoBehaviour
 
     void OpenHelpshift() {
       Dictionary<string, object> configMap = new Dictionary<string, object>();
-      configMap.Add("fullPrivacy", "true");
+      configMap.Add("fullPrivacy", true);
       help.ShowConversation(configMap);
     }
 }

diff --git a/docs/sdkx_android/delegates.mdx b/docs/sdkx_android/delegates.mdx
@@ -509,6 +509,16 @@ Locally saved unread message count are useful for saving an additional network c
 When using Identity system related APIs, the related events are communicated to your app using the events mentioned in this section. Events can have associated data which gives more information on the corresponding event.
 The constants for value of data is present in `InvalidDataErrorReason` file.
 
+Where applicable, the max permissible limits are defined as follows -
+
+- Key length - Max 255 chars
+- Value length for identity - Max 300 chars
+- Value length for UID identity - Max 750 chars
+- Value length for CUF - Max 255 chars
+- Value length for multiline CUF - Max 100000 chars
+- Value length for user tags - Max 100 chars
+- Collection size - Max 30 entries
+
 ### INVALID_IDENTITY_TOKEN
 
 Identities JWT not in valid format
@@ -600,7 +610,7 @@ Identity feature is not enabled for your domain
 ### USER_SESSION_EXPIRED
 
 Sent when the SDK's user session expires. Once the session expires, SDK will keep sending this event to your app on each foreground.
-In response to this event, you should refresh the JWT for the current user and [log them in](/sdkx_android/identity-users.mdx) again with the new JWT.
+In response to this event, you should refresh the JWT for the current user and [log them in](/sdkx_android/identity-user-hub/) again with the new JWT.
 
 Data - null
 

diff --git a/docs/sdkx_android/getting-started.mdx b/docs/sdkx_android/getting-started.mdx
@@ -38,8 +38,9 @@ If you are on SDK X or migrating to SDK X please note the following requirements
 
 <Admonition type="info" title="Note">
 
-  - From 10.4.0, SDK compiles on Java 8 to support Android 15 compilation.
-  - SDK 10.4.0 functions and is supported on Android 7 and above (API level 24 and above). You can still compile your app using a minimum API level of 19, but the support starts for API level 24 and above.
+  - From 10.4.0, SDK is compiled using Java 8 to ensure compatibility with Android 15 build tool chain.
+  - SDK 10.3.0 and above functions and is supported on Android 7 and above (API level 24 and above). 
+  - You can still compile your app using a minimum API level of 19, but the support starts for API level 24 and above.
     For details regarding Helpshift SDK's Android OS support policy, please refer to [this article](https://support.helpshift.com/hc/en/13-helpshift-technical-support/faq/1217-sdk-x-os-technical-support-policy/).
 
 </Admonition>

diff --git a/docs/sdkx_android/identity-users.mdx → docs/sdkx_android/identity-user-hub.mdx b/docs/sdkx_android/identity-users.mdx → docs/sdkx_android/identity-user-hub.mdx
@@ -1,6 +1,6 @@
 ---
 sidebar_position: 45
-title: Identity User Management
+title: User Hub
 description: Learn more about identifying and managing users.
 ---
 
@@ -20,12 +20,12 @@ All the public APIs in the SDK should be called after initializing the SDK via [
 
 ## Managing users with the Identity System
 
-Setting up the Identity System requires some development effort, but provides many advantages over the legacy method in the form of faster context collection, easier agent experience, enhanced security, and spam protection.
+Setting up the new Identity System ( "User Hub" ) requires some development effort, but provides many advantages over the legacy method in the form of faster context collection, easier agent experience, enhanced security, and spam protection.
 
 ### Prerequisites
 
 <Admonition type="info" title="NOTE">
-  This feature is in closed beta. Contact Helpshift Support team to enable this
+  This feature is in closed beta. Contact Helpshift Customer Success team to enable this
   feature.
 </Admonition>
 
@@ -79,6 +79,14 @@ loginWithIdentity(
  )
 ```
 
+Following rules apply depending on the value of `full_privacy_enabled` flag in config.
+
+- If full privacy flag is false, one of uid or email is mandatory in the identities array.
+- If full privacy flag is true, no identity keys are mandatory. However the behaviour changes depending on the presence of uid key -
+  - If uid is present - SDK will use the uid to identify the user.
+  - If uid is absent - SDK will generate an anonymous ID and use this ID to identify the user.
+- Full privacy is assumed to be false if no value is specified, or if the passed value can’t be parsed as a boolean type.
+
 The failure reasons and possible recovery steps are documented in the [Login failure reasons](#login-failure-reasons) section.
 
 ### Identity token format
@@ -103,13 +111,6 @@ The identity token must be a JWT signed using the shared secret from your app se
 
 Note that `identities` key expects an array in this contract, allowing you to specify more than one identity objects.
 
-Additionally, following rules apply depending on the value of `full_privacy_enabled` flag in config.
-
-- If full privacy flag is false, one of uid or email is mandatory in the identities array.
-- If full privacy flag is true, no identity keys are mandatory. However the behaviour changes depending on the presence of uid key -
-  - If uid is present - SDK will use the uid to identify the user.
-  - If uid is absent - SDK will generate an anonymous ID and use this ID to identify the user.
-- Full privacy is assumed to be false if no value is specified, or if the passed value can’t be parsed as a boolean type.
 
 <Admonition type="info" title="Important">
 
@@ -150,7 +151,7 @@ If you wish to proactively refresh your logged in user’s credentials with Help
 
 For more details on these events, please check the [Delegates](/sdkx_android/delegates/#helpshifteventusersessionexpired) page.
 
-### Updating user identities
+### Adding user identities
 
 Use the `addUserIdentities` API to update the identities associated with the logged in user. This API updates the identities for a non-anonymous logged in user only. If your current user has been logged in with an empty JWT (aka an anonymous user), this API will be no-op.
 
@@ -162,6 +163,98 @@ You need to obtain a JWT for new identities from your dedicated endpoint. Please
 
 This API leverages the existing Helpshift delegates system to notify the app in case of any errors. For more details on the error events that can be triggered by this API, please refer the [Delegates](/sdkx_android/delegates.mdx/#user-identity-system-events) page.
 
+### Troubleshooting and tips
+Login failure can be detected by listening to the [HelpshiftUserLoginEventsListener](/sdkx_android/identity-user-hub/#logging-in-your-end-users) listener. The possible reasons for login failure are cited in the [Login failure reasons](/sdkx_android/identity-user-hub/#login-failure-reasons) section.
+
+If your login is still failing, you can investigate these other potential reasons:
+
+- Ensure that your JWT endpoint is generating tokens in the accepted format
+- Ensure that your JWT endpoint is signing tokens with the shared secret
+- Ensure that your JWT endpoint has an iat (issued_at_time) value that is NOT older than 24h
+- In case you are caching the JWT, ensure that you do not cache it for longer than 24h.
+
+### Update global user data
+
+Use this API to update global attributes associated with the logged in user.
+
+```java
+  Map<String, Object> masterAttributes = new HashMap<>();
+  // put appropriate master attribute key and its value
+  masterAttributes.put("<master-attribute-key>", "<master-attribute-value>");
+  Helpshift.updateMasterAttributes(masterAttributes);
+```
+
+Global attributes must be one of the following types -
+
+- `first_name` - String
+- `last_name` - String
+- `display_name` - String
+- `full_name` - String
+- `last_country` - String
+- `last_city` - String
+- `age` - Int or String
+- `lifetime_value` - String
+- `user_persona` - String
+- `user_vip_segment` - String
+- `user_support_status` - String
+- `last_active_date` - String // UNIX epoch time in seconds
+- `accepted_t_and_c` - String
+- `preferred_language` - String
+- `new_tags` - List< String >
+- `tags_to_remove` - List< String >
+- `reset_tags` - List< String >
+- `custom_user_fields` - Map<String, String>
+
+This API leverages the existing Helpshift delegates system to notify the app in case of any errors.
+For more details on the error events that can be triggered by this API, please refer the [Delegates](/sdkx_android/delegates/#user-identity-system-events) page.
+
+If the attributes map contains an unsupported key, an error event will be communicated via the delegate.
+If the attributes map contains supported key, but with unsupported value type, the entry will be ignored.
+
+### Update app specific user data
+
+Use this API to update app specific attributes associated with the logged in user.
+
+```java
+  Map<String, Object> appAttributes = new HashMap<>();
+  // put appropriate app attribute key and its value
+  appAttributes.put("<app-attribute-key>", "<app-attribute-value>");
+  Helpshift.updateAppAttributes(appAttributes);
+```
+
+App specific attributes must be one of the following types -
+
+- `device_model` - String
+- `os_version` - String
+- `app_version` - String
+- `sdk_version` - String
+- `country` - String
+- `city` - String
+- `user_vip_segment` - String
+- `language` - String
+- `app_rating` - String
+- `user_paying_segment` - String
+- `user_support_status` - String
+- `user_persona` - String
+- `accepted_t_and_c` - String
+- `user_level` - String
+- `app_status` - String
+- `lifetime_value` - String
+- `custom_user_fields` - Map<String,String>
+
+This API leverages the existing Helpshift delegates system to notify the app in case of any errors.
+For more details on the error events that can be triggered by this API, please refer the [Delegates](/sdkx_android/delegates/#user-identity-system-events) page.
+
+If the attributes map contains an unsupported key, an error event will be communicated via the delegate.
+If the attributes map contains supported key, but with unsupported value type, the entry will be ignored.
+
+<Admonition type="info" title="Note">
+
+Attributes update APIs sync attributes with Helpshift servers in batches. There is a chance of attribute updates
+being lost in case the user is logged out from the SDK before the current batch update is synced.
+
+</Admonition>
+
 ## Login failure reasons
 
 Identity system login can fail for any of the reasons mentioned below. A reason may have associated errors that may help pinpoint the exact cause of the failure. As an example, if the failure is due to an invalid key in identities JWT, the errors dictionary will contain the exact key (or keys) found to be invalid. The value against this key will indicate what failed (value too big, value type not supported, etc).
@@ -170,9 +263,14 @@ The constants for these failure reasons are defined in `UserLoginFailureReason`
 
 Where applicable, the max permissible limits are defined as follows -
 
-- Key length - Max 1000 chars
-- Value length - Max 10,000 chars
-- Collection size - Max 100 entries
+- Key length - Max 255 chars
+- Value length for identity - Max 300 chars
+- Value length for UID identity - Max 750 chars
+- Value length for CUF - Max 255 chars
+- Value length for multiline CUF - Max 100000 chars
+- Value length for user tags - Max 100 chars
+- Collection size - Max 30 entries
+
 
 ### LOGIN_IN_PROGRESS
 

diff --git a/docs/sdkx_android/release-notes.mdx b/docs/sdkx_android/release-notes.mdx
@@ -29,17 +29,17 @@ _November 27th, 2024_
 
 ** Release Notes **
 
-- Helpshift SDK now supports Android 15.
-- Helpshift SDK now compiles with API level 35.
-- Helpshift SDK now compiles on JAVA 8.
-- Helpshift SDK `minSDKVersion` is now updated to 19.
-- Added support for user identities and related user data collection APIs.
-  - For more details on user identities, refer [User Identities](/sdkx_android/identity-users/) page.
+- Added support for Android 15.
+- SDK now compiles with API level 35, i.e compileSdk 35.  
+- The SDK artefact is now compiled with Java 8.
+- `minSDKVersion` is now updated to 19.
+- Added support for User Hub (User Identity & Profiles) and related user data collection APIs.
+  - For more details on user identities, refer [User Identities](/sdkx_android/identity-user-hub/) page.
   - For more details on user data collection, refer [Tracking](/sdkx_android/tracking/#update-global-user-data) page.
 - Fixed an edge case bug where message count was incorrect when login and unread message count APIs were invoked in quick succession.
-- Error logs from SDK will always get logged. 
-- Debug build for debug logs is not required any more, only enableLogging flag needs to be set to true.
-- Webviews will now load with enhanced security flag MIXED_CONTENT_NEVER_ALLOW.
+- Error logs from SDK will always get logged on logcat.
+- Debug build for debug logs is not required any more, only `enableLogging` flag needs to be set to `true`.
+- Webviews will now load with enhanced security flag [MIXED_CONTENT_NEVER_ALLOW.](https://developer.android.com/reference/android/webkit/WebSettings#MIXED_CONTENT_NEVER_ALLOW)
 
 ## 10.3.0
 

diff --git a/docs/sdkx_android/support-tools.mdx b/docs/sdkx_android/support-tools.mdx
@@ -166,3 +166,6 @@ This API is available from 10.3.0 version.
   // closes Helpshift sdk session
   Helpshift.closeSession();
 ```
+
+## User Hub APIs
+Our new Identity system - [User Hub](/sdkx_android/identity-user-hub/), introduces various APIs for managing users and their data. Refer to the linked section for details.
diff --git a/docs/sdkx_android/tracking.mdx b/docs/sdkx_android/tracking.mdx
@@ -205,9 +205,11 @@ Debug logs are collected within the set debug logs limit. The limit is set under
 
 </Admonition>
 
-## Update global user data
+## Tracking user-specific metadata
 
-This API is meant to be used along with the new [User Identity system](/sdkx_android/identity-users). Use this API to update global attributes associated with the logged in user.
+### Update global user data
+
+This API is meant to be used along with the new [User Identity system](/sdkx_android/identity-user-hub). Use this API to [update global attributes](/sdkx_android/identity-user-hub/#update-global-user-data) associated with the logged in user.
 
 ```java
   Map<String, Object> masterAttributes = new HashMap<>();
@@ -216,74 +218,13 @@ This API is meant to be used along with the new [User Identity system](/sdkx_and
   Helpshift.updateMasterAttributes(masterAttributes);
 ```
 
-Global attributes must be one of the following types -
-
-- `first_name` - String
-- `last_name` - String
-- `display_name` - String
-- `full_name` - String
-- `last_country` - String
-- `last_city` - String
-- `age` - Int or String
-- `lifetime_value` - String
-- `user_persona` - String
-- `user_vip_segment` - String
-- `user_support_status` - String
-- `last_active_date` - UNIX epoch time in seconds
-- `accepted_t_and_c` - Boolean or String
-- `preferred_language` - String
-- `full_privacy_enabled` - Boolean or String
-- `new_tags` - String Array
-- `tags_to_remove` - String Array
-- `reset_tags` - String Array
-- `custom_user_fields` - Map<String,String>
-
-This API leverages the existing Helpshift delegates system to notify the app in case of any errors.
-For more details on the error events that can be triggered by this API, please refer the [Delegates](/sdkx_android/delegates/#user-identity-system-events) page.
-
-If the attributes map contains an unsupported key, an error event will be communicated via the delegate.
-If the attributes map contains supported key, but with unsupported value type, the entry will be ignored.
-
-## Update app specific user data
-
-This API is meant to be used along with the new [User Identity system](/sdkx_android/identity-users). Use this API to update app specific attributes associated with the logged in user.
+### Update app specific user data
+
+This API is meant to be used along with the new [User Identity system](/sdkx_android/identity-user-hub). Use this API to [update app specific attributes](/sdkx_android/identity-user-hub/#update-app-specific-user-data) associated with the logged in user.
 
 ```java
   Map<String, Object> appAttributes = new HashMap<>();
   // put appropriate app attribute key and its value
   appAttributes.put("<app-attribute-key>", "<app-attribute-value>");
   Helpshift.updateAppAttributes(appAttributes);
-```
-
-App specific attributes must be one of the following types -
-
-- `device_model` - String
-- `os_version` - String
-- `app_version` - String
-- `sdk_version` - String
-- `country` - String
-- `city` - String
-- `user_vip_segment` - String
-- `language` - String
-- `app_rating` - String
-- `user_paying_segment` - String
-- `user_support_status` - String
-- `user_persona` - String
-- `accepted_t_and_c` - String
-- `user_level` - String
-- `app_status` - String
-- `lifetime_value` - String
-- `custom_user_fields` - String → String Dictionary
-
-This API leverages the existing Helpshift delegates system to notify the app in case of any errors.
-For more details on the error events that can be triggered by this API, please refer the [Delegates](/sdkx_android/delegates/#user-identity-system-events) page.
-
-If the attributes map contains an unsupported key, an error event will be communicated via the delegate.
-If the attributes map contains supported key, but with unsupported value type, the entry will be ignored.
-
-<Admonition type="info" title="Note">
-
-Attributes update APIs sync attributes with Helpshift servers in batches. There is a chance of attribute updates
-being lost in case the user is logged out from the SDK before the current batch update is synced.
-
-</Admonition>
+```
diff --git a/docs/sdkx_android/users.mdx b/docs/sdkx_android/users.mdx
@@ -27,7 +27,7 @@ All the public APIs in the SDK should be called after initializing the SDK via [
 
 <Admonition type="warning" title="Before you proceed">
 
-This section describes how you can integrate users with the legacy method. For integrating with the new Identity System, please refer [this page](/sdkx_android/identity-users).
+This section describes how you can integrate users with the legacy method. For integrating with the new Identity System `User Hub`, please refer [this page](/sdkx_android/identity-user-hub).
 
 We recommend using the new Identity System if you require faster context collection, an easier agent experience, and enhanced security and spam protection.
 

diff --git a/docs/sdkx_ios/delegates.mdx b/docs/sdkx_ios/delegates.mdx
@@ -733,6 +733,16 @@ Locally saved unread message count are useful for saving an additional network c
 
 When using Identity system related APIs, the related events are communicated to your app using the events mentioned in this section. Events can have associated data which gives more information on the corresponding event.
 
+Where applicable, the max permissible limits are defined as follows -
+
+- Key length - Max 255 chars
+- Value length for identity - Max 300 chars
+- Value length for UID identity - Max 750 chars
+- Value length for CUF - Max 255 chars
+- Value length for multiline CUF - Max 100000 chars
+- Value length for user tags - Max 100 chars
+- Collection size - Max 30 entries
+
 ### HelpshiftIdentityTokenInvalid
 
 Identities JWT not in valid format
@@ -825,7 +835,7 @@ Identity feature is not enabled for your domain
 ### HelpshiftEventUserSessionExpired
 
 Sent when the SDK's user session expires. Once the session expires, SDK will keep sending this event to your app on each foreground.
-In response to this event, you should refresh the JWT for the current user and [log them in](/sdkx_ios/identity-users.mdx) again with the new JWT.
+In response to this event, you should refresh the JWT for the current user and [log them in](/sdkx_ios/identity-user-hub/) again with the new JWT.
 
 - Data - nil