Examples of how to interact with the LivePerson Messaging SDK
Current Version: v1.0
Running with the following versions of the LivePerson Messaging SDK
To use the LivePerson In-App Messaging SDK, the following are required:
- XCode 11 or later
- Swift 5.0, or Objective-C
For latest information please refer to LivePerson Developers Site
The SDK is also compatible with CocoaPods, a dependency manager for Swift and Objective-C Cocoa projects. CocoaPods has thousands of libraries and is used in over 2 million apps. It can help you scale your projects elegantly and provides a standard format for managing external libraries.
- Install cocoapods using the following command:
$ gem install cocoapods
- Navigate to your project folder and init new pod using the following command:
$ pod init
- Podfile should be created under your project’s folder.
To integrate Liveperson Messaging SDK into your Xcode project using CocoaPods, specify it in your Podfile:
- Run the following command in the terminal under your project folder:
$ pod install
- Incase you wish to upgrade to the latest SDK version and you have already ran 'pod install', Run the following command:
$ pod update
Copy all framework and bundle files into the project, including the bundle file In project settings, navigate to the General tab, and add all Framework files to the Embedded Binaries section.
In project settings, navigate to the Build Phases tab, and click the + button to add a New Run Script Phase. Add the script below in order to loop through the frameworks embedded in the application and remove unused architectures (used for simulator). This step is a workaround for known iOS issue http://www.openradar.me/radar?id=6409498411401216 and is necessary for archiving your app before publishing it to the App Store.
If frameworks installed using CocoaPods, use the following script:
bash "${SRCROOT}/Pods/LPMessagingSDK/LPMessagingSDK/LPInfra.framework/frameworks-strip.sh"
If frameworks installed using copy to Xcode project, use the following script:
bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/LPInfra.framework/frameworks-strip.sh"
Follow the usual steps for adding the embedded binary .frameworks
and .bundle
files into the iOS app via Xcode. Check the
Video Link for examples of how this can be done.
- Add SDK plugin with latest version
-
Open project workspace in XCODE
- accept all recommend project settings
- select project
- add embedded binaries for the SDK and frameworks
- CLEAN PROJECT!
- BUILD PROJET! == should pass & you will warnings about missing cordova libs as we have not "built in cordova" yet!
-
go back to CLI
-
run
cordova build ios
command which should now succeed -
run in xcode or CLI
if you get a build/run error about missing simulators, then edit this file --
<your app folder>/platforms/ios/cordova/lib/start-emulator
and change the default iOS emulator to run or add iPhone 5s to your list of emulated devices
The plugin itself does NOT include any copies of the Android SDK aars
libraries. You should download the latest version of the Android SDK from here on github.
https://developers.liveperson.com/android-quickstart.html
filename: plugins/MessagingSDKPlugin/www/LPMessagingSDK.js
This is where we expose the different function names within the wrapper to call the native code for starting, configuring a messaging conversation. In the current version there is just one function exposed which takes in an "action" arg for telling the native code what to do. You must also supply a successCallback js func / errorCallback js func / account id (clone or prod) + any arguments needed by the function.
lp_conversation_api: function(action, args, successCallback, errorCallback)
Supported values for action
:
sample call:
lpMessagingSDK.lp_conversation_api(
'close_conversation_screen', [accountNumber],
function (data) {
var eventData = JSON.parse(data);
console.log('@@@ js ... unique close_conversation_screen SDK callback');
},
function (data) {
var eventData = JSON.parse(data);
console.log('@@@ js ... unique close_conversation_screen SDK error callback');
}
);
can be triggered if the callbacks you bind to trigger an error response and you want to close the conversation screen as a result and provide the user with instructions within the web layer.
Must be called before trying to use any other methods.
Requires the account number to be passed within args
parameter
sample call...
var success = function(message) {
console.log("OnEvent JS: " + message);
}
var failure = function() {
console.log("Error calling lp_conversation_api Plugin");
}
lpMessagingSDK.lp_conversation_api("lp_sdk_init", ["123456"], success, failure);
Used to register device tokens with the SDK for handling push notifications
-
api method :
lpMessagingSDK.lp_conversation_api
-
action :
'register_pusher'
-
args : [
accountId
,deviceToken
]deviceToken
should be obtained by your app using relevant cordova plugin
-
Reccomend this method is called within the success callback of
lp_sdk_init
to ensure SDK is ready to receive the token.
lpMessagingSDK.lp_conversation_api(
"lp_sdk_init", [this.settings.accountId, sdkConfig],
function(data) {
var eventData = JSON.parse(data);
console.log("@@@ js ... unique lp_sdk_init SDK callback");
lpMessagingSDK.lp_conversation_api(
"register_pusher", [app.settings.accountId,app.deviceToken],
function(data) {
//var eventData = JSON.parse(data);
console.log("@@@ js ... unique register_pusher SDK callback .."+data);
},
function(data) {
// var eventData = JSON.parse(data);
console.log("@@@ js ... unique register_pusher SDK error callback ..."+data);
}
);
},
function(data) {
var eventData = JSON.parse(data);
console.log("@@@ js ... unique lp_sdk_init SDK error callback");
}
);
Used to open the Messaging conversation window and connect to LivePerson.
Includes support for authentication JWT token for implicit flow
var authenticationCode = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIrOTcyLTMtNTU1NS01NTUiLCJpc3MiOiJodHRwczovL2lkcC5saXZlcGVyc29uLm5ldCIsImF1ZCI6ImFjYzpxYTU3MjIxNjc2IiwiZXhwIjoxNTM0OTcxOTMwLCJpYXQiOjE0NzE4OTk5NDIsIm5hbWUiOiJFaXRhbiJ9.Fh0sG-iu-VMZRFRbUNK0kEzb7Y1BXtQHOKaHL2y40y_c4mBvmQDCOYNWJ1ZEeayTNuLboYx6L8xEoC5xZIFnVv2N4a36BBU88fNuhe9Em2b5qNdVbdBtIJQoBY5ep5O2geAaCVA7A7oS8ysWVGn9CV4btH_D5sU2jGr3ml8yfJA"
lpMessagingSDK.lp_conversation_api(
"start_lp_conversation",
[
"123456",
authenticationCode
],
success,
failure);
authenticationCode
is optional arg parameter. If omitted then the conversation will be unauthenticated
Used to clear the current user data and unregister the device from push notifications.
Calling this method will mean the device is no longer going to receive push notifications until the next user logs back in and opens the conversation screen to send the latest JWT token to the SDK and establish a connection. After that point the device will receive push notifications again for that user when not viewing the conversation screen.
- When the customer logs out of your app, call this method to clear the local device SDK history and unregister the device from push notifications.
- Then once the next user logs in, remember to call
lp_sdk_init
before starting a new conversation for the next user when you supply the updated and relevant JWT token - see example below for doing this in the callback for logout ready for the next user.
- You must supply the account id for your LivePerson account number into this method
lpMessagingSDK.lp_conversation_api(
"lp_clear_history_and_logout", [this.settings.accountId],
function(data) {
var eventData = JSON.parse(data);
console.log("@@@ js ... unique clearDeviceHistoryAndLogout SDK callback ...data => "+data);
console.log("@@@ js ... post logout...now auto reinitialise the SDK for next user to save button press in demo!");
app.lpMessagingSdkInit();
},
function(data) {
var eventData = JSON.parse(data);
console.log("@@@ js ... unique clearDeviceHistoryAndLogout SDK error callback ...data => "+data);
}
);
- callback event name :
LPMessagingSDKClearHistoryAndLogout
- args : [
token
]in that specific order!accountId
is required for iOS version of the function
within your javascript successCallback
function, you must listen for the specific eventName
that tells you the SDK has detected that the customer JWT has expired and must be refreshed.
- Listen for the correct event in your
successCallback
method and call your relevant app function to get the new token
successCallback: function(data) {
var eventData = JSON.parse(data);
if (eventData.eventName == 'LPMessagingSDKTokenExpired') {
console.log("authenticated token has expired...refreshing...");
this.lpGenerateNewAuthenticationToken();
}
},
- generate your new token calling your IDP / JWT service via javascript
lpGenerateNewAuthenticationToken: function() {
// code to generate new fresh JWT would go here...
// this example uses a hard coded JWT which has the new expiry time.
var jwt = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJUQUxLVEFMSy1JRC0xMjM0NTY3ODkwIiwiaXNzIjoiaHR0cHM6Ly93d3cudGFsa3RhbGsuY28udWsiLCJleHAiOjE1MTQ3MTg2NzEwMDAsImlhdCI6MTQ4NzE1OTMzNzAwMCwicGhvbmVfbnVtYmVyIjoiKzEtMTAtMzQ0LTM3NjUzMzMiLCJscF9zZGVzIjpbeyJ0eXBlIjoiY3RtcmluZm8iLCJpbmZvIjp7ImNzdGF0dXMiOiJjYW5jZWxsZWQiLCJjdHlwZSI6InZpcCIsImN1c3RvbWVySWQiOiIxMzg3NjZBQyIsImJhbGFuY2UiOi00MDAuOTksInNvY2lhbElkIjoiMTEyNTYzMjQ3ODAiLCJpbWVpIjoiMzU0MzU0NjU0MzU0NTY4OCIsInVzZXJOYW1lIjoidXNlcjAwMCIsImNvbXBhbnlTaXplIjo1MDAsImFjY291bnROYW1lIjoiYmFuayBjb3JwIiwicm9sZSI6ImJyb2tlciIsImxhc3RQYXltZW50RGF0ZSI6eyJkYXkiOjE1LCJtb250aCI6MTAsInllYXIiOjIwMTR9LCJyZWdpc3RyYXRpb25EYXRlIjp7ImRheSI6MjMsIm1vbnRoIjo1LCJ5ZWFyIjoyMDEzfX19LHsidHlwZSI6InBlcnNvbmFsIiwicGVyc29uYWwiOnsiZmlyc3RuYW1lIjoiSm9objc3IiwibGFzdG5hbWUiOiJCZWFkbGU3NyIsImFnZSI6eyJhZ2UiOjM0LCJ5ZWFyIjoxOTgwLCJtb250aCI6NCwiZGF5IjoxNX0sImNvbnRhY3RzIjpbeyJlbWFpbCI6ImpiZWFkbGU5OUBsaXZlcGVyc29uLmNvbSIsInBob25lIjoiKzEgMjEyLTc4OC04ODc3In1dLCJnZW5kZXIiOiJNQUxFIn19XX0.i-PFEBjgXR-rEM30iGJAV-4l0P58wysMEZxyoYdwOCTpIkmfkXtnztfyYRNdaBkpaF1AmZVtgEBIFEYWLcSmcRWkMvnSUAKV0dv9QhR9tDbILsdyd-DEFB_RcmW8rXB7rWSoSJa4z3EMatpoC7CzaUrih8IycB2X4FuKuxL9mOg";
// pass the
lpMessagingSDK.lp_conversation_api(
"reconnect_with_new_token", [jwt,app.settings.accountId],
this.successCallback,
this.errorCallback
);
console.log('lpGenerateNewAuthenticationToken completed --> new jwt --> ', jwt);
},
- once you have the new token pass it back down into the native application using the following cordova API call
lpMessagingSDK.lp_conversation_api(
"reconnect_with_new_token",
[jwt,app.settings.accountId],
this.successCallback,
this.errorCallback
);
- The SDK will pass the token back to LivePerson using the
reconnect
method of the SDK to refresh the token and continue authenticated conversations.
Used to send unauthenticated customer information to the agent where authenticated equivalents are not being sent.
PLEASE NOTE : unclear which of these values are still being used on server side so subject to change/deprecation in subsequent versions.
args
array parameter mapping:
-
0
: accountId : "123456" -
1
: first name : "John" -
2
: last name : "Doe" -
3
: nickname : "JD" -
4
: profile image url : "https://s-media-cache-ak0.pinimg.com/564x/a2/c7/ee/a2c7ee8982de3bae503a730fe4562cf9.jpg"
(Android Deprecated in v2.5 - value will be ignored - send null if not applicable)
(iOS still supported in v2.5)
5
: customer phone number : "555-444-12345"
(iOS Only)
6
: uid : "UID123145"7
: employeeID : "employeeId123123123"
^ Both of the above seemingly not being read on server side for iOS so use with caution.
lpMessagingSDK.lp_conversation_api(
'set_lp_user_profile',
[
accountId,
'John',
'Doe',
'NickName:JD',
'https://s-media-cache-ak0.pinimg.com/564x/a2/c7/ee/a2c7ee8982de3bae503a730fe4562cf9.jpg',
'tel:555-444-12345',
'uid_5678',
'employeeId_1234'
],
function(data) {
var eventData = JSON.parse(data);
console.log('@@@ js ... unique set_lp_user_profile SDK callback');
},
function(data) {
var eventData = JSON.parse(data);
console.log('@@@ js ... unique set_lp_user_profile SDK error callback');
}
);
If you wish to send secure, authenticated information about the customer to your agent, it should be encoded and encrypted within your JWT token
https://s3-eu-west-1.amazonaws.com/ce-sr/CA/security/Authenticated+Interactions+with+oAuth+2.0.pdf
For a list of supported engagement attributes within a JWT token payload, see the following example JWT:
{
"sub": "MY_UNIQUE_CUSTOMER_IDENTIFIER_GOES_HERE",
"iss": "https://www.talktalk.co.uk",
"exp": 1514718671,
"iat": 1487159337,
"phone_number": "+1-10-344-3765333",
"lp_sdes": [
{
"type": "ctmrinfo",
"info": {
"cstatus": "cancelled",
"ctype": "vip",
"customerId": "138766AC",
"balance": -400.99,
"socialId": "11256324780",
"imei": "3543546543545688",
"userName": "user000",
"companySize": 500,
"accountName": "bank corp",
"role": "broker",
"lastPaymentDate": {
"day": 15,
"month": 10,
"year": 2014
},
"registrationDate": {
"day": 23,
"month": 5,
"year": 2013
}
}
},
{
"type": "personal",
"personal": {
"firstname": "AN",
"lastname": "Other",
"age": {
"age": 34,
"year": 1980,
"month": 4,
"day": 15
},
"contacts": [
{
"email": "another@liveperson.com",
"phone": "+1 212-788-8877"
}
],
"gender": "MALE"
}
}
]
}
This video shows step by step how to replace the existing iOS frameworks and bundles in your app when their is a new version / hotfix released and you do not want to have to remove and add the plugin back into the app again...
The following callbacks are fired from the iOS / Android apps back up into the Cordova plugin for processing / actions in Javascript
lpMessagingSDK.lp_register_event_callback: function(args, successCallback, errorCallback)
- register your global async callback handler for monitoring these events.
lpMessagingSDK.lp_register_event_callback(
[accountId],
this.globalAsyncEventsSuccessCallback,
this.globalAsyncEventsErrorCallback
);
In your js successCallback function you will receive a data
object that must be parsed from a string into JSON
var eventData = JSON.parse(data);
This object has an eventName
property which matches the above callbacks we support.
eventData.eventName
There may be other additional data points depending on the callback and context.
Certain events are now returning immediate responses by triggering the respective, unique success/error callbacks passed into certain API functions.
lpMessagingSDK.lp_conversation_api
with the following actions
will return success/failure ASAP.
- action:
start_lp_conversation
| eventName:LPMessagingSDKStartConversation
- based on the SDK API call not failing - does not mean the conversation screen has loaded without errors etc, just means we called the method successfully.
- action:
set_lp_user_profile
| eventName:LPMessagingSDKSetUserProfile
- called the API method and did/did not throw errors as a result.
- action:
lp_sdk_init
| eventName:LPMessagingSDKInit
- SDK has initialised successfully based on calling the method and not throwing any errors.
- action:
lp_clear_history_and_logout
| eventName:LPMessagingSDKClearHistoryAndLogout
- SDK has cleared device history and unregistered push notifications for the device.
- action:
register_pusher
| eventName:LPMessagingSDKRegisterLpPusher
- successully registered the push token via the API call. Should only be called once
lp_sdk_init
has succeeded. Suggest triggering within the success callback oflp_sdk_init
- Refer to
register_pusher
section for exact details, usage and implications
- successully registered the push token via the API call. Should only be called once
- This will be the single handler for all the following async events
- example function that JSON parses the data to get the eventData.eventName property listed below
globalAsyncEventsSuccessCallback: function(data) {
var eventData = JSON.parse(data);
console.log(
'@@@ globalAsyncEventsSuccessCallback --> ' + data
);
if (eventData.eventName == 'LPMessagingSDKTokenExpired') {
console.log("@@@ authenticated token has expired...refreshing...");
app.lpGenerateNewAuthenticationToken();
}
},
eventData.eventName values listed below. additional eventData
properties are indented
"LPMessagingSDKCustomButtonTapped"
(iOS Only)"LPMessagingSDKAgentDetails"
agentName
: String
"LPMessagingSDKActionsMenuToggled"
(iOS Only)toggled
: true|false
"LPMessagingSDKHasConnectionError"
(iOS Only)error
: String
"LPMessagingSDKCSATScoreSubmissionDidFinish"
"LPMessagingSDKAuthenticationFailed"
error
: String
"LPMessagingSDKTokenExpired"
accountId
: string
"LPMessagingSDKError"
error
: String
"LPMessagingSDKAgentIsTypingStateChanged"
isTyping
:true|false
"LPMessagingSDKConversationStarted"
conversationID
: string
"LPMessagingSDKConversationEnded"
conversationID
: string
"LPMessagingSDKConversationCSATDismissedOnSubmission"
conversationID
: string
"LPMessagingSDKConnectionStateChanged"
isReady
: true|false
"LPMessagingSDKOffHoursStateChanged"
isOffHours
: true|false
"LPMessagingSDKConversationViewControllerDidDismiss"
(iOS only)
Immediate response callback execution:
"LPMessagingSDKInit"
"LPMessagingSDKClearHistoryAndLogout"
"LPMessagingSDKSetUserProfile"
"LPMessagingSDKReconnectWithNewToken"
"token"
: new jwt"LPMessagingSDKRegisterLpPusher"
"deviceToken"
: device token supplied"LPMessagingSDKStartConversation"
"type"
: "authenticated" | "unauthenticated"
Triggering asynchronously -- register your global async callback handler for monitoring these events.
"LPMessagingSDKObseleteVersion"
(iOS Only)"LPMessagingSDKCsatDismissed"
(Android Only)
"LPMessagingSDKAgentAvatarTapped"
"LPMessagingSDKCSATCustomTitleView"
Refer to native documentation and if you are missing a specific callback pleae let us know!