Document Identity System changes for Web Chat (#145)

* Specify error event listener for Web Chat developers + This error event can be subscribed to for handling runtime errors programmatically * Add Web Chat Identity System integration instructions * Document the Web Chat runtime error event + This describes all the errors, their reasons, as well as the details that can occur via the onWebChatRuntimeError event. + The tables are not "formatted" because MDX does not compile correctly due to whitespaces. * Recommend the usage of the Web Chat runtime error event * Document all the new Identity System JS APIs * Document the Logout API * Add callout for onLoginRequest event + This is to let the devs know user session expiry conditions + Ref: https://helpshift.atlassian.net/browse/HS-18282 * Add identity token schema + The identity token schema is necessary for developers to understand what the backend endpoint should return and to reduce back and forth between KB articles and Dev Docs * Centralize all user identity APIs + Instead of documenting the profile update APIs separately, we are centralizing them on a new page + We're linking the entire page on the APIs page to ensure consistency and discoverability + Also addressed these review comments: + Mentioned that the feature is in closed beta + Changed "support" to "Customer Success" + Moved "addUserIdentities" API documentation right after the login information + Removed the TODO + Changed Users title to add "Legacy" for clear bifurcation * Add full privacy scenarios and login best practices * Update section title for user specific metadata
helpshift · Nov 29, 2024 · 64190eb · 64190eb
1 parent c1fcbb2
commit 64190eb
Show file tree

Hide file tree

Showing 5 changed files with 790 additions and 3 deletions.
diff --git a/docs/web-chat/api.mdx b/docs/web-chat/api.mdx
@@ -137,6 +137,12 @@ You should call this API before a conversation starts. In other words, it works
 
 </Admonition>
 
+## User Hub APIs {#user-hub-apis}
+
+Our new Identity system - [User Hub](/web-chat/identity-users), introduces various
+APIs for managing users and their data. Refer to the linked section for details.
+
+
 ## Events {#events}
 
 The Helpshift Widget fires the following events across different scenarios. You can use the `addEventListener` and `removeEventListener` APIs to manage the events.
@@ -520,3 +526,50 @@ Helpshift(
   userClickOnActionEventHandler
 );
 ```
+
+### On Login Request Event {#on-login-request}
+
+The `onLoginRequest` event is used to request you to login your end-user. This event is intended
+to work with the new Identity system - [User Hub](/web-chat/identity-users).
+You can refer to the linked section for details.
+
+### On Web Chat Runtime Error {#on-webchat-runtime-error}
+
+<Admonition type="danger" title="Note">
+
+We highly recommend enabling this event listener since it can help you catch and handle important errors.
+
+</Admonition>
+
+This event is fired when there is a runtime error from Web Chat which requires your attention. Such events may be generated if there is an issue with the integration which can be handled programmatically.
+To listen to this event, add the following code after the embed code.
+
+#### Adding the On Web Chat Runtime Error event handler
+
+```typescript
+interface WebChatRuntimeError {
+  error: string;
+  reason?: string;
+  details?: object;
+}
+
+const onWebChatRuntimeErrorHandler = function ({error, reason, details}: WebChatRuntimeError) {
+  console.log({error, reason, details});
+};
+
+Helpshift(
+  "addEventListener",
+  "onWebChatRuntimeError",
+  onWebChatRuntimeErrorHandler
+);
+```
+
+#### Removing the Web Chat Runtime Error event handler
+
+```javascript
+Helpshift(
+  "removeEventListener",
+  "onWebChatRuntimeError",
+  onWebChatRuntimeErrorHandler
+);
+```
diff --git a/docs/web-chat/getting-started.mdx b/docs/web-chat/getting-started.mdx
@@ -69,6 +69,13 @@ In case you don't have a prepared embed code, add this snippet just before the c
 1. Replace `YOUR_PLATFORM_ID` with details found at `Settings` > `SDKs (for Developers)`
    <Image src="/static/books/web-chat/wc-embed-sdk.png" width="full" />
 
+<Admonition type="info" title="Best practice">
+
+We highly recommend attaching the **Web Chat runtime error** event listener after the embed script.
+This can help you discover integration errors as well as handle certain error scenarios programmatically.
+Ref: [On Web Chat Runtime Error](/web-chat/api/#on-webchat-runtime-error)
+</Admonition>
+
 ## **Step 2:** Start using Helpshift Web Chat {#start-using}
 
 Helpshift Web Chat is now available on your website. Test it out by starting a chat.