This document is designed to provide detailed flows to demonstrate how the SDK and its methods should be implemented. As an example, this document will cover the standard use cases that a consumer would encounter whilst using a brand’s app and explain which SDK methods should be called as a result.
iOS and Android have very similar flows with some minor differences. For example, some method names are slightly different and whether delegate methods are used instead of callback methods does change the best practice implementations slightly. Please review the correct flow for the given OS.
Retry Policy
Many of the flows outlined in this document include how to handle errors or failures thrown by SDK methods. This usually involves calling the same method again. Our standard retry policy is to use exponential back-off for a given number of retries.
For example, if registering for push notifications throws an error, then we would recommend calling the same method again after 1 second. If that fails as well, call the method again after 2 seconds, then 4, then 8, and so on.In general, it is best practice to add a cap to how many retry attempts should take place. It is impossible to give a one size fits all approach here but as a general rule, 5 retries would take place over 31 seconds which is a decent amount of time to allow for some backend service to recover.
Some flows specify modifications to this retry policy, depending on the failing method. Some methods have their own retry mechanism built into the SDK. These can lead to multiple failures being seen in the app’s logs for a single method call, even if the method succeeds overall.
iOS Flows
Authenticated Only Flows
User Logs into the App
The below flow covers what SDK methods should be used every time a user logs in to the app. This flow covers the initialization of the SDK, the registration for push notifications, the retrieval of the current unread message count, as well as how to handle any failure flows that may be encountered.
- On every login, the “
initilialize” method should be called. “Initilialize” should be wrapped in a do-catch statement that will capture any failures. - If the SDK does fail to “
initilialize”, consumers will be unable to start a conversation so it is important to handle failure flows correctly. The solution here is to call the “logout” method to fully reset the SDK before attempting to retry the “initilialize” method.The most common failure when initilalizing the SDK is not providing the correct parameters (brandId or monitoringInitParams). Calling “logout” won’t solve this issue since this is an implementation problem. Hence, it is best to call “logout” once as a catch all and if “initilialize” fails again, disable all further SDK method calls. - If “
initilialize” completes successfully, the next step is to register the user push notifications using “registerPushNotifications”. Steps 4-5 can be skipped if push notifications are not to be implemented.It is highly recommended that the optional “authenticationParams” are provided to this method with a valid JWT in Implicit Flow or Auth Code in Code Flow. This will allow LivePerson to identify who the consumer is and allow the consumer to receive push notifications immediately.Without the “authenticationParams” the user will only receive push notifications after opening the messaging window. - In the case that registration for push notifications fails, the “
LPMessagingSDKPushRegistrationDidFail” optional delegate method will trigger. It is here that calls to “registerPushNotifications” should be retried. - On successful registration, “
LPMessagingSDKPushRegistrationDidFinish” optional delegate method will be called, informing the app that the next method call can take place.The next method is “getUnreadMessagesCount”. This method returns how many messages the consumer has yet to read and allows the setting of any badge counts in the app’s UI.Like “registerPushNotifications”, it is highly recommended to pass “authenticationParams”.
If the failure callback is called, follow the retry flow.
- In the event that the “
getUnreadMessagesCount” completion callback is called, the result can now be displayed in the UI as required. The unread count is only reset to zero once the user has opened the messaging window and the device has downloaded the unread messages. - In the event of the failure callback being called after “N” number of times, the simplest thing to do is to reset the count to 0.
User is logged out of the App
This flow is critical from a security perspective. The SDK’s logout method removes all data that the SDK has stored about a given user, as well as unregisters them from push notifications. This ensures that a second consumer using a device has no access to any information about the first user.
- There are several ways that a user may become logged out of an app
- User explicitly logs out
- The app times out and automatically logs the user out
- The user is forced to log out by logging in to another device
- Any remote log out flow
In all app logout flows, the SDK’s logout method should be called.
In newer SDKs, you can specify whether to fully unregister from push notifications, or only unregister from agent notifications. This will allow Proactive Messaging notifications to still be received by the user.
If the “logout” failure callback is called, it is recommended to follow the standard retry process.
User navigates about the App
The SDK uses the concept of engagements to control which groups of agents a consumer is routed to (skill routing), the language of system messages displayed and what survey is presented to the consumer.
- User navigates around the app.
- To ensure the consumer reaches the correctly skilled agents, the “
getEngagement” method must be called to let LP know what business area the user is in. The business area should be passed as part of the “entryPoints” array.If the failure callback is called, then the standard retry policy should be implemented. - If the “
getEngagement” completion callback is called, but the response does not contain “engagementDetails”, then no engagement should be displayed to the consumer in the app’s UI.Displaying and hiding engagements from the consumer is the responsibility of the app, rather than the SDK since it doesn’t have the ability to render the engagements itself. - If the “
getEngagement” completion callback is called and the response does contain “engagementDetails”, then those values should be stored for use with “showConversation” later on and an engagement should be displayed to the consumer in the app’s UI.
User clicks messaging button
The messaging button is the button that the consumer needs to press to open the messaging window. This button is designed and rendered by the brand and triggers the below flow when tapped.
- User presses the messaging button in the app’s UI.
- Call the SDK’s “
showConversation” method to open up the messaging window. - The most common failure when opening the messaging window is that of an authentication error.
- Once the messaging window finishes loading and has downloaded all unread agent messages, the “LPMessagingSDKConnectionStateChanged” optional delegate method is called. If there is some unread message notification being displayed to the consumer in the app, it is at that point that the unread message count badge should be reset to 0 or removed entirely.
The SDK encounters an authentication failure
Authentication failures can occur at any time.
- Authentication has been encountered.
- When a JWT/JWE expires, the “
LPMessagingSDKTokenExpired” delegate method will trigger. In Implicit Flow, this delegate method is where a new JWT/JWE should be retrieved from the brand’s IDP and provided to the SDK via the “reconnect” method in step 4. - In Code Flow, a new Auth Code instead of a JWT/JWE should be retrieved and passed to the SDK via the “
reconnect” method in step 4. - If the authentication token provided is invalid in any way, the “
LPMessagingSDKAuthenticationFailed'' delegate method is called. There are many ways a token can be invalid. These include:- The public key on Conversational Cloud does not correspond to the private key that the JWT/JWE was signed with
- The JWT/JWE is missing mandatory claims
- In Code Flow, the Auth Code has been used more than once
- In Code Flow, the incorrect Redirect Uri has been provided
- Once new authentication details have been retrieved, the new JWT/JWE or the new Auth Code should be passed to the SDK via the “
reconnect” method.
Agent sends a push notification whilst the app is foregrounded
When a push notification is dispatched to a device whilst it is foregrounded, the “application:didReceiveRemoteNotification” delegate method (or UNUserNotificationCenter:willPresent if implemented instead) will trigger which can then be used to control how the notification is displayed to the consumer.
- When the app is open on the user’s device but the messaging window is closed, so the user is made aware that the agent has sent a new message, a push notification will be dispatched via APNS.
- When a notification is received by the app, “
application:didReceiveRemoteNotification” will trigger and allow for the handling of the notification. - If the notification is from LivePerson, the current unread message count can be extracted from the “badge” value from the payload and use that value to update the UI as required.To understand if the push is from LivePerson, you can inspect the notification payload for LP specific values such as “
brandId” (the Conversational Cloud account id). - To display the SDK's default In-App notification banner, simply call “
handlePush” and the SDK will display a black banner with the message overlaid.Do not implement “customLocalPushNotificationView”, otherwise that optional delegate method will trigger expecting a custom UIView to display the message instead. - When the SDK’s default banner is tapped by the user, the SDKs “
notificationTapped” delegate method is called. Here, the “setPushNotificationTapped” method should be called. - Tapping the notification banner should be handled in the same way as the consumer pressing any messaging button. “
showConversation” should be called in the same way as the “User clicks messaging button” flow. - To display a custom notification banner, implement “customLocalPushNotificationView”. Just like in step 4, “
handlePush” should be called on “application:didReceiveRemoteNotification” to continue the flow. - After calling “handlePush”, the “customLocalPushNotificationView” will be called where a custom UIView can be provided for the SDK to render to the consumer.The new UIView should be tappable and lead the consumer back to the messaging window by calling “showConversation” as in the “User clicks messaging button” flow.
Agent sends a push notification whilst the app is backgrounded
Unlike when the app is foregrounded, the app has no control over the displaying of the notification. There is no concept of an in-app banner as seen when the app is foregrounded.
- When the app is backgrounded, so the user is made aware that the agent has sent a new message, a push notification will be dispatched via APNS.
- The notification is completely handled by iOS and is displayed in the Notification Centre of the device.
- When a user taps the notification, the app will automatically open and the “
application:didReceiveRemoteNotification” delegate method will be called. - When this delegate method is called, the SDK’s “handlePush” method should be called if the notification is from LivePerson.
- Immediately after, the “
setPushNotificationTapped” method should be called. - Finally, the “
showConversation” should be called in the same way as the “User clicks messaging button” flow.
User updates the app from the App Store
Consumers can update their apps at any time. These updates may or may not include an SDK upgrade. If the update does, then the below flow should be followed.
- A consumer updates their app and the update includes an SDK version bump.
- Although very unlikely, LP holds the right to update or change the structure of any data that the SDK stores on the device. This could cause incompatibility issues when upgrading.To resolve this it is suggested that on SDK upgrade, “
logout” should be called to remove all data stored on the device to ensure no clashes with old and new data schemas. - In some upgrade flows, the user may not have to log in to the app again after the update. In this case, the app will need to follow the “User Logs into the App” flow to reinitialise the SDK after the “logout” in step 2.
Deep linking
For iOS, there are two ways to support deep links to apps. It’s similar but subtly different to what Android can do and this often confuses brands, even though it’s standard iOS behaviour. There’s a commonly shared blog post explaining the two linking mechanisms.
- Universal Links are intended for linking to the app from an external source such as a web browser. They do not allow an app to link to itself, and this regularly confuses brands. Universal Links are HTTPS links and require the domain owner to create a metadata file in a well-known location indicating which links should be handled by an app, the app’s bundle id, and the app’s signing key. Since these apps are verified by the domain owner, there’s a level of anti-spoofing. If the link is opened from a browser and the app is not installed, the link can fall back to a web page, or through to the AppStore.
- URL Schemes allow an app to define its own URL scheme for links it can handle. This can be something standardised and external such as FTP or RDP, but is commonly also used for deep linking typically using the bundle id as a URL scheme, e.g. indicating that it handles links of the form com.example.app://screen#widget. These aren’t verified at all: any app can register any scheme, so there’s a risk of spoofing.
To create a Universal Link, the following steps are needed:
- Create the .well-known/apple-app-site-association file at the root of the server for your link hostnames.
- Update your AppDelegate to handle application(application:userActivity:restorationHandler)
- Add the Associated Domains entitlement to your app adding applinks: and webcredentials: with your domain name.
To create a URL scheme, the following steps are needed:
- Add the URL Scheme in the project settings in XCode.
- Update your AppDelegate to handle application(application:url:options)
Since deep links are links to an App on a specific platform, it’s important to send the right link to the right platform.
Linking standard URI schemes
Standard URI schemes such as http: and mailto: are recognised by default, but the SDK offers a custom regex option if the iOS one doesn’t meet needs (usually relates to URL Schemes). For email links, the link should follow RFC 2368, see this Apple dev page for details.
Authorization with PKCE
Proof Key for Code Exchange is an enhancement to OAUTH2 Code Flow which protects against an attacker stealing the OAUTH2 code and trying to use it with LP to obtain a JWT.
PKCE adds two new parameters to the Authorization Endpoint call, code_challenge, and code_challenge_method. It adds one new parameter to the Token Endpoint call, code_verifier. In order to use PKCE with the SDK, a new method, getPkceParams(accountID:completion:failure) was added to the SDK. This returns a LPPkceResponse object containing the parameters needed by the IDP. Brands thus need to modify their authorization implementation as follows:
- Call
LPMessaging.instance.getPkceParams() and cache the result. - Update the brand’s interaction with the Authorization Endpoint to add in the
code_challenge and code_challenge_method returned by the SDK. - Update the
LPAuthenticationParams object to set codeVerifier to the value that was returned by the SDK. The brand will also need to validate/update the issuerDisplayName value.
Android Flows
Authenticated Only Flows
User Logs in to the App
- The user logging in to an app marks the transition of the user from the unauthenticated part of the app, to the authenticated part of the app.
- On every login, the “
initilialize” method should be called. - If the SDK does fail to “
initilialize”, consumers will be unable to start a conversation so it is important to handle failure flows correctly. The solution here is to call the “logout” method to fully “reset” the SDK before attempting to retry the “initilialize” method.The most common failure when initilalizing the SDK is not providing the correct mandatory parameters to “InitLivePersonProperties” (brandId or appId). Calling “logout” won’t solve this issue since this is an implementation problem. Hence, it is best to call “logout” once as a catch all and if “initilialize” fails again, disable all further SDK method calls. - To be aware of authentication errors and other SDK events, the app must register a “
BroadcastReceiver” with the SDK. It is recommended to not register to all intents that the SDK has available since many are not required except for very specific use cases.It is recommended to only register for the following events:- LP_ON_CONNECTION_CHANGED_INTENT_ACTION - Alerts the app to when the messaging window is open and has finished loading successfully.
- LP_ON_TOKEN_EXPIRED_INTENT_ACTION - Alerts the app to when any authentication credentials have expired and a new token is required.
- LP_ON_ERROR_INTENT_ACTION - Alerts the app to multiple types of SDK error, including generic authentication failures other than token expiration.
- If “
initilialize” completes successfully, the next step is to register the user to push notifications using “registerLPPusher”. Step 4 can be skipped if push notifications are not to be implemented.It is highly recommended that the optional “authenticationParams” are provided to this method with a valid JWT in Implicit Flow or Auth Code in Code Flow. This will allow LivePerson to identify who the consumer is and allow the consumer to receive push notifications immediately.Without the “authenticationParams” the user will only receive push notifications after opening the messaging window.On failure to register, the “onError” callback is called. The standard retry policy should be implemented here. - The next method is “
getUnreadMessagesCount”. This method returns how many messages the consumer has yet to read and allows the setting of any badge counts in the app’s UI.Like “registerPushNotifications”, it is highly recommended to pass “authenticationParams”. - In the event that the “
getUnreadMessagesCount” completion callback is called, the result can now be displayed in the UI as required. The unread count is only reset to zero once the user has opened the messaging window and the device has downloaded the unread messages. - In the event of the failure callback being called, the simplest thing to do is to leave any unread message badges as they are. Of course, the standard retry policy can be implemented as well if required.
User is logged out of the App
This flow is critical from a security perspective. The SDK’s logout method removes all data that the SDK has stored about a given user, as well as unregisters them from push notifications. This ensures that a second consumer using a given device has no access to any information about the first user.
- There are several ways that a user may become logged out of an app
- User explicitly logs out
- The app times out and automatically logs the user out
- The user is forced to log out by logging in to another device
- Any remote log out flow
- In all app logout flows, the SDK’s logout method should be called.In newer SDKs, you can specify whether to fully unregister from push notifications, or only unregister from agent notifications. This will allow Proactive Messaging notifications to still be received by the user.If the “
logout” failure callback is called, it is recommended to follow the standard retry process. - On successful logout, the “
BroadcastReceiver” that was registered on login, should be unregistered. It is considered best-practices to remove any receivers once they're no longer needed to avoid any extra resource overhead. Simply calling “removeCallBack” will unregister from the events.
User navigates about the App
This flow for Android is identical to that of iOS.
User clicks messaging button
The messaging button is the button that the consumer needs to press to open the messaging window. This button is designed and rendered by the brand and triggers the below flow when tapped.
- User presses the messaging button in the app’s UI.
- Call the SDK’s “
showConversation” method to open up the messaging window. - The most common failure when opening the messaging window is that of an authentication error.
- Once the messaging window finishes loading and has downloaded all unread agent messages, the “
LP_ON_CONNECTION_CHANGED_INTENT_ACTION” intent is triggered. Using the “onConnectionChanged” callback, the connection state can be checked.If “onConnectionChanged” returns true, then the SDK has downloaded the unread messages and the unread message count badge in the UI can be reset to 0 or removed entirely.
The SDK encounters an authentication failure
Authentication failures can occur at any time.
- When a JWT/JWE expires, the “
LP_ON_TOKEN_EXPIRED_INTENT_ACTION” intent will trigger. Using the “onTokenExpired” callback, the app can get a new authentication token.In Implicit Flow, this callback is where a new JWT/JWE should be retrieved from the brand’s IDP and provided to the SDK via the “reconnect” method in step 4.In Code Flow, a new Auth Code instead of a JWT/JWE should be retrieved and passed to the SDK via the “reconnect” method in step 4. - If the authentication token provided is invalid in any way, the “
LP_ON_ERROR_INTENT_ACTION” intent is triggered. The “Error Intent” can be triggered for multiple SDK errors so the “onError” callback should be used to understand whether the type is IDP or not. If it is IDP, continue with this flow.There are many ways a token can be invalid. These include:- The public key on Conversational Cloud does not correspond to the private key that the JWT/JWE was signed with.
- The JWT/JWE is missing mandatory claims.
- In Code Flow, the Auth Code has been used more than once.
- In Code Flow, the incorrect Redirect Uri has been provided.
- Once new authentication details have been retrieved, the new JWT/JWE or the new Auth Code should be passed to the SDK via the “reconnect” method.
Push notification received by device
Unlike iOS, Android is very flexible when it comes to push notifications.
- If the user has an open conversation but the messaging window is closed when an agent sends a message, Conversational Cloud will dispatch the agent message as a push notification via Firebase or Huawei Push Kit.
- When a notification is received by the app, the appropriate notification service (Firebase/Huawei) will trigger allowing the app to handle how the notification should be displayed.
- The notification payload contains a “
badge” value that is a running count of how many unread messages the consumer has. This value can be used to update the unread count that may be displayed in the UI to the consumer. - By reviewing the notification payload for LP specific values such as “
brandId” (the Conversational Cloud account id), the app can then decide whether to use the “handlePushMessage” method or not.“handlePushMessage” can be used in two ways. By passing true for the “showNotification” argument, the SDK will handle displaying a default notification to the consumer. The default notification will simply display the agent's nickname and the message from the notification in the notification drawer.Passing false to “showNotification” will stop the SDK automatically displaying anything and allows the app to handle exactly how the notification should display. - After the message from the payload has been retrieved, the Push Message ID is then required via the “
getPushMessageId” method. This ID is required when calling “setPushNotificationTapped” as part of the “Consumer taps a push notification” flow. - If false is passed to “
handlePushMessage”, the returned value is the parsed agent message and allows the app to handle the displaying of the notification in whatever way the brand desires.
Consumer taps a push notification
- When a consumer taps a notification, the app will need to handle what happens next. This is usually handled by applying an intent to the notification when it is displayed to the consumer.When it’s tapped, the app is able to handle the LivePerson notifications separately from other notification sources.
- When the notification is tapped when the app is in the background, the app will be brought to the foreground automatically.Once the app is in the foreground, it is up to the brand to navigate the user to an appropriate part of the app, ready to automatically open the messaging window.
- Since the messaging window is being opened via a push notification “
setPushNotificationTapped” to tell the SDK how to handle the message scrolling when the window opens.By default, “showConversation” will scroll the user to the latest message. By calling “setPushNotificationTapped”, you can customise the default scrolling behaviour in this scenario.In addition to controlling the scrolling behaviour, passing the Push Message ID to “setPushNotificationTapped” allows LP to understand whether the notification was a Proactive/C2M message and if so, instructs the SDK to display the correct message on opening of the conversation window. - Finally, follow the same process that is laid out when a user clicks the messaging button.
User updates the app from the Play Store
This flow for Android is identical to that of iOS.
Deep Linking
For Android, deep links are simply Intents, but there are some parameters that can be applied to reduce the risk of spoofing. It’s similar but simpler than what iOS does. There’s a developers page explaining the three ways of handling links on Android. For deep linking, you should only need to use Android App Links.
- Deep Links are a way of declaring support for a custom URI scheme. They’re the same as URL Schemes on iOS, and suffer from the same spoofing risk that any app can register support for any URL Scheme. These are more useful for supporting standard external links such as FTP or RDP than for deep linking to or within a specific app.
- Web Links are like Deep Links, but the protocol is HTTP(S), and the app declares which domains it wants to handle, since it’s probably not a web browser. As with Deep Links, these can be spoofed, so they’re not that useful.
- Android App Links are like Web Links, but require verification. This means that the owner is required to create a metadata file in a well-known location indicating which links should be handled by an app, the app’s application id, and the app’s signing key. Since these apps are verified by the domain owner, there’s a level of anti-spoofing. If the link is opened from a browser and the app is not installed, the link can fall back to a web page, or through to the Play Store. This makes Android App Links equivalent to Universal Links on iOS, but there’s a key difference, which is that Android allows Android App Links to redirect an app to itself, whereas iOS Universal Links do not.
To create an Android App Link, the following steps are needed:
- Create the .well-known/assetlinks.json file at the root of the server for your link hostnames.
- Update your app to handle deep link intents, for example handling it in an appropriate Activity.
- Add the Intent filter declaration to your App Manifest.
Additionally, the SDK has a boolean config parameter structured_content_link_as_callback which will trigger a callback from a structured content link instead of using the deep link.
Since deep links are links to an App on a specific platform, it’s important to send the right link to the right platform.
Authorization with PKCE
Proof Key for Code Exchange is an enhancement to OAUTH2 Code Flow which protects against an attacker stealing the OAUTH2 code and trying to use it with LP to obtain a JWT.
PKCE adds two new parameters to the Authorization Endpoint call, code_challenge, and code_challenge_method. It adds one new parameter to the Token Endpoint call, code_verifier. In order to use PKCE with the SDK, a new method, getPKCEParams(final Context context, LPAuthenticationParams lpAuthParams, PKCEParamsCallBack pkceCallback) was added to the SDK. This takes a callback which returns a PKCEParams object containing the parameters needed by the IDP. Brands thus need to modify their authorization implementation as follows:
- Call LivePerson.getPKCEParams() and cache the result.
- Update the brand’s interaction with the Authorization Endpoint to add in the
code_challenge and code_challenge_method returned by the SDK. - Update the LPAuthenticationParams object by calling setCodeVerifier with the value that was returned by the SDK. The brand will also need to validate/update the call to
setIssuerDisplayName.
Appendix
Android Activity Mode and Fragment Mode
There are two ways to display the messaging window to consumers; “activity mode” and “fragment mode”. “Activity mode” is where the SDK creates a new activity and displays it to the consumer. The SDK is in control of the entire activity and any branding or customisation must be done via the SDK.To use this presentation mode, the “showConversation” method should be used.
Alternatively, “fragment mode” means the app needs to create and display the activity itself, then attach a fragment that the SDK provides to said activity. The SDK only controls the portion of the screen that contains transcript messages and the text box for consumer responses. This allows the app itself to customise the toolbar and menu options of the messaging window.
To use this mode, the “getConversationFragment” method should be used to retrieve the messaging window fragment, but it is up to the app to attach that fragment to an activity and to display it to the consumer.
Opening the Fragment
For the purposes of this document, it is assumed that “activity mode” is being used. If that is not the case, calling “showConversation” can be replaced with the three steps below.
When Using fragment mode, it is highly recommended to offer consumers a way to resolve conversations from their side if support is no longer required. This can be done by adding a button to the toolbar that calls the “resolveConversation” method.
Closing the Fragment
When the consumer presses the “back button”, “super.onBackPressed()” should be called to destroy the fragment and activity, rather than simply backgrounding it. This is so the web socket that the fragment establishes when it’s opened, to properly close. When the socket is closed, the device will receive push notifications.
iOS Window Mode and View Controller Mode
These two modes work quite similarly to Activity and Fragment modes for Android, but with some key differences. Again, the benefits of using “View Controller Mode” are that the app has more control over the messaging window, such as giving complete control of the navigation bar to the app, rather than using LivePerson’s implementation.
Opening the View Controller
In both Window Mode and View Controller Mode, the “showConversation” method should be called, however, a valid view controller must be provided to the “containerViewController” parameter of “LPConversationViewParams” if view controller mode is to be used. The “showConversation” method must then be called with the “LPConversationViewParams” object to use “View Controller Mode”.
Closing the View Controller
When the consumer presses the “back button”, the View Controller needs to be popped to return to the previous screen. Before it is popped, the connection between the SDK and LivePerson services needs to be disconnected. This can be achieved by calling the “removeConversation” method.
“removeConversation” closes the web socket between the SDK and LivePerson. This improves device performance as well as allowing notifications to work as described here.
Authentication Params when and why
There are currently four places where the SDKs can use authentication parameters. Depending on the SDK method, they may be optional. Brands usually want to minimise the number of calls to their IDP. This is important for code-flow authentication where the authentication codes cannot be reused. This is not a concern with implicit flow where the tokens can be reused until they expire.
Showing the conversation
The SDK will always need authentication parameters to call showConversation, so for code-flow it will need to ask the IDP for a fresh code every time the method is called. Brands should try to avoid UX flows allowing the consumer to close and reopen the conversation window unnecessarily if they want to avoid too many IDP requests.
Registering for push notifications
The SDK needs to authenticate to communicate with the pusher service. For proactive messaging, or where a user has an active conversation, the app should (re)register the push token on app start. The app will also need to register for push notifications if APNs or Firebase send an event notifying that the token has changed.
Authentication parameters are optional in the SDK call. If no authentication parameters are provided, then the token will be registered the next time the SDK authenticates, typically when showConversation is called. If proactive messaging is not in use, and the call to getEngagement indicates that there is no active conversation, it’s probably safe to defer push registration until showConversation is called.
Checking for unread messages
The SDK uses the pusher service to check for unread messages and it needs to authenticate to communicate with the pusher service. If no authentication parameters are provided, then the SDK method will first use any existing credentials and return an error callback if it can’t connect. Since the unread count is contained in the payload of new push notifications, if the app is registering for push notifications either on app start or after showConversation, the brand can safely call getUnreadCount after registering for push without needing to get credentials twice. Future unread message updates can be made using the number in the push notification payload.
The unread count is tightly coupled to the pusher service, so it’s important to (re)register for push if the unread count method needs to be used reliably.
Getting an authenticated engagement using JWE token id
The Monitoring API does not require authentication, so authentication parameters are usually not required. If the brand needs to provide the consumer identity using a JWE id token instead of providing the JWT subject claim, then they should pass an authentication params object. Most brands do not use JWE token ids, so they will not need to pass authentication parameters here.
Ready to move on? Click here to proceed.
