iOS
Updated
Step 1 - Getting Started
1.) Creating Live Chat controller, adding live chat URL and injecting javascript to listen to webview events
appId=60c1d169c96beb5bf5a326f3_app_950954 → It indicates the live chat application ID; please ask Sprinlr services team to get you the correct app ID.
device=MOBILE → It indicates that the page is Mobile Responsive.
enableClose = true → It indicates a close button has been added to live chat, on pressing that close button onClose sdk will be called. You will need to set enableClose to true before you try to access it.
zoom = false → It indicates zoom has been disabled inside the webview.
skin = MODERN → It indicates modern theme of live chat widow
webview = true → It indicates sprinklr code that implemetation is webview and based on this flag we can handle the webview specific things seperately i.e. To support downloading of the attachement.
Please check with success team on the environment you are part of, it can be prod, prod2, prod4 etc. and use the URL accordingly.
NOTE → Example Projects can be viewed here
let liveChatUrl = "http://prod-live-chat.sprinklr.com/page?appId=60c1d169c96beb5bf5a326f3_app_950954&device=MOBILE&enableClose=true&zoom=false"; // example url, use one provided by sprinklr |
let jsString = """ |
override func viewDidLoad() { contentController.add(self, name: "OnExternalEventReceived")
// this is required to allow video streaming through webview webConfiguration.allowsInlineMediaPlayback = true; func userContentController(_ userContentController: WKUserContentController, didReceive message: WKScriptMessage) {// edit: changed fun to func |
2.) Add these permissions if you want to support uploading and downloading of media
Include the following permissions in info plist file:
<key>NSCameraUsageDescription</key> |
3.) Initialize Messenger
Sprinklr Messenger can be initialized for both unauthenticated and authenticated users:
For Anonymous Users:
If a user is not logged into your mobile app, you can open live chat without passing user information. The profile created into sprinklr will be an anonymous user.
URL -
For Authenticated Users:
If a user is already logged into your mobile app, you can pass the authenticated details securely to the chat to authenticate the user on the chat itself. This process is called pre-authentication. In pre-authentication you can pass following information securely from the mobile app to the chat -
URL -
In the above URL,
user_id = “pass required value” → It indicates the ID which is passed to profile of user
user_firstName = “pass required value” → It indicates the first name which is passed to profile of user
user_lastName = “pass required value” → It indicates the last name which is passed to profile of user
user_profileImageUrl = “pass required value” → It indicates the profile image which is passed to profile of user
user_email = “pass required value” → It indicates the email ID which is passed to profile of user
user_phoneNo = “pass required value” → It indicates the phone number which is passed to profile of user
user_hash = “pass required value” → It indicates the hash generated for profile of user
Note: If you want to pass more values, please use user context i.e. scenario 3 |
How to generate userHash?
The userHash is a generated HMAC or Hash-based Message Authentication Code. For HMAC, Sprinklr uses the sha256 hash function. You need to generate HMAC for the following "string" of user details. User details are concatenated to form a string, separated by underscore as shown below -
userId_firstName_lastName_profileImageUrl_phoneNo_email |
So for the above example, the string for which you need to generate the hash would be
12345_John_Doe_https://example.com/profilePic.jpg_9876543210_John.Doe@example.com |
Sample code to generate HMAC is given below for following languages - PHP, Python 2.7, Python 3.6.1, Ruby (Rails), Java, Node.js
PHP
$key = "acf32e61-14a6-291b-3a1b-cc8854134ea1"; |
Run the above PHP code online - https://repl.it/@AbhishekPriyam/HMACPHPExample
Python 2.7/3.6.1
import hmac |
Run the above Python code online - https://repl.it/@AbhishekPriyam/HMACPythonExample
Ruby (Rails)
require 'openssl' |
Run the above Ruby code online - https://repl.it/@AbhishekPriyam/HMACRubyExample
Java
import javax.crypto.Mac; |
Run the above Java code online - https://repl.it/@AbhishekPriyam/HMACJavaExample
C#
using System; using System.Security.Cryptography; using System.Text;
class Program { static void Main(string[] args) { string key = "acf32e61-14a6-291b-3a1b-cc8854134ea1"; string userId = "12345"; string firstName = "John"; string lastName = "Doe"; string profileImageUrl = "https://example.com/profilePic.jpg"; string phoneNo = "9876543210"; string email = "John.Doe@example.com";
string userDetails = $"{userId}_{firstName}_{lastName}_{profileImageUrl}_{phoneNo}_{email}";
using (HMACSHA256 hmac = new HMACSHA256(Encoding.UTF8.GetBytes(key))) { byte[] hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(userDetails)); string userHash = BitConverter.ToString(hashBytes).Replace("-", "").ToLower();
Console.WriteLine(userHash); } } } |
Run the above Java code online - https://replit.com/@RoshanDash1/HmacCExample
Node.js
var crypto = require('crypto'); |
Run the above Node.js code online - https://repl.it/@AbhishekPriyam/HMACNodeExample
Note:
firstName, hash and one of email or phoneNumber are mandatory
User details are supposed to be concatenated to form a string, separated by underscore as shown below:
userId_firstName_lastName_profileImageUrl_phoneNo_email |
If you don’t have a few values, you need not send anything but keep the underscores as is. For example, let’s say you don’t have profileimageUrl, there will be 2 underscores after lastName. The string will be as shown below:
userId_firstName_lastName__phoneNo_email |
Step 2 - Configurations
1.) Localization support
To achieve localization in live chat via webview approach, you can pass certain “locale” string in query parameters of URL; this will be in addition to ones discussed in Step 1
In the above URL,
locale = en → It indicates the locale which you want to send for this app ID
2.) Opening live chat with different landing screen
To open live chat in different states at different locations, you can use pass the relevant string in the query parameters of URL; this will be in addition to ones discussed in Step 1
Scenario 1: Directly landing on the home screen
Scenario 2: Directly landing on the new conversation screen
URL -
In the above URL,
scope = CONVERSATION → It indicates the the scope of live chat is limited to conversation screen
landingScreen = NEW_CONVERSATION → It indicates the landing screen i.e. new conversation is opened
Scenario 3: Directly landing on the last conversation screen
URL -
In the above URL,
scope = CONVERSATION → It indicates the the scope of live chat is limited to conversation screen
landingScreen = LAST_CONVERSATION → It indicates the landing screen i.e. last conversation is opened
Note: landingScreen: "LAST_CONVERSATION allows brands to get users to land the customer on the last interacted open conversation. If there are no open conversations, the customer lands on a new conversation window |
3.) Passing contextual information of users to live chat from mobile
Scenario 1: Capture customer context from the mobile app on all cases of the user
Sometimes you might want to pass some contextual information in case custom fields for all conversations started by the user. (clientContext)
URL -
In the above URL,
context_fieldId = “pass required value” → It indicates the context which is passed to all cases of user
Scenario 2: Update the profile context from mobile app on profile of user
Sometimes you might want to capture some context on the profile/user during the conversation or after the conversation. (userContext)
URL -
In the above URL,
userContext_fieldId = “pass required value” → It indicates the context which is passed to profile of user
4.) Blocking URLs which does not contain live chat URL domain to open it in the external browser
let domainsToWhiteList = ["prod-live-chat.sprinklr.com", "live-chat-static.sprinklr.com"] // urls to whitelist |
func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) { |
5.) Add support to download attachment
Whenever user clicks on the download button, we will redirect to a URL which contains fileUrl and fileName which looks like this ->
“livechat-app:url=${fileUrl}?fileName=${fileName}” [when there are no query parameters present in the fileUrl, fileName is added as a new query parameter]
OR“livechat-app:url=${fileUrl}&fileName=${fileName}” [when there are query parameters present in the fileUrl already, fileName is added as an extra query parameter]
You need to intercept the requests that have URLs starting with the “livechat-app:” prefix and parse these URLs to properly download the attachment. The steps to parse are:
Strip the “livechat-app:url=” prefix.
From the remaining URL, extract and remove the “fileName” query parameter. Use its value to name your file.
Using the remaining URL to fetch and download content.
Please note: While extracting the file URL we need to strip the fileName query Param from the original query because if we do not remove the fileName query parameter then it will lead to signature mismatch and will throw SignatureDoesNotMatch error or BlobNotFound error.
For Example, when receiving a URL like “livechat-app:url= https://prod-sprcdn-assets.sprinklr.com/1234/sample.pdf?signature=XYZ&fileName=sample_name.pdf”, follow the above steps i.e.
Strip the prefix to get “https://prod-sprcdn-assets.sprinklr.com/1234/sample.pdf?signature=XYZ& fileName=sample_name.pdf”
Extract fileName query param and name the file sample_name.pdf.
Use the remaining URL “https://prod-sprcdn-assets.sprinklr.com/1234/sample.pdf?signature=XYZ” to download file.
func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) { let url = navigationAction.request.url; var urlString = url?.absoluteString;
if(urlString == nil){ urlString=""; } if (urlString != nil && urlString!.starts(with: "livechat-app:")) {
if var urlComponents = URLComponents(string: strippedUrl) { var fileName: String? if let queryItems = urlComponents.queryItems { for queryItem in queryItems { if queryItem.name == "fileName" { fileName = queryItem.value break } } }
urlComponents.queryItems = urlComponents.queryItems?.filter { $0.name != "fileName"}
let cdnUrl = urlComponents.url?.absoluteString ?? ""
// put your download logic here } } decisionHandler(.allow); } |
Step 3 - Push Notifications
For more details on mobile push notifications, please refer here
Prerequisite
Android: FCM Servey Key
iOS: APNS certificate (P12) along with its credentials
Note:
FCM Server key can be different for staging/prod env
APNS certificate (P12) and its credentials must be different for staging/prod env
If you are testing the push notification setup on prod mobile application(iOS), plesae ensure to use test flight build
If the FCM server key is different sandbox/prod env and you are testing the push notification setup on prod mobile application(Android), plesae ensure to use Android release build.
Configuration
To enable push notifications, please raise a support ticket to tickets@sprinklr.com with the following information:
FCM Server Key (copy it from your Firebase Console)
APNS certificate (P12) along with its credentials
Live Chat AppID
Partner ID
Env
1) Register for push notifications
You can register the messenger for sending push notifications by providing push token received from apns/fcm as below:
Create a function in the following way and pass token, deviceId and deviceName as arguments to it to register your device for push notification.
|
2) Unregister for push notifications
If you ever want to stop receiving notifications, then you can deregister your device in the following way:
|
3) Handle Messenger Push Notifications
Once you have registered for messenger push notifications, then you might receive notifications from your platform as well as messenger. To check if notification is messenger notification you can check as below:
Note: When the user is on the Live Chat app, they will always receive the Live Chat messenger push notifications. However, you can define whether users should receive the messenger notifications when they are on the brand app and not the Live Chat app. That is, the brand app is in the foreground and the Live Chat app is running in the background.
To do that, you can check whether the notification is a Live Chat notification and handle it according to brand requirements. For example, you can choose not to display Live Chat notifications when the user is on the brand app.
Once you have identified if the notification is messenger notification you need open the messenger and call handle notification method as described below:
|
Troubleshooting
Issue 1: Sprinklr webview URL is not working
Check network connections establishing or not; to verify this you can simply try to open google.com in your webview
Check whitelisng is done properly inn live chat builder in Sprinklr platform.
Steps: Sprinklr Service → Live Chat Care → “ three dots” next to your Live chat Application → Edit → Application Configuration Screen
Check example URL are loading like https://prod0-live-chat.sprinklr.com/page?appId=app_1000073145
Issue 2: LiveChat not showing up while passing authenticated user details
Check the expected hash for any authenticated user passed inside chat settings.
Hover over the Options icon alongside your Live Chat Application and select Validate User Hash.
On the Validate User Hash window, enter User ID, Profile Image URL, First Name, Last Name, Phone Number and Email. Click Copy Generated Hash and verify it with the hash generated by you.
Issue 3: Attachment icon not working
Please check is user is having permission like camera and photo
Please check step 1.3