The LivePerson SDK provides brands with a simple, yet enterprise-grade and secure Mobile App Messaging solution. Through Mobile App Messaging, brands will foster connections with their customers and increase app engagement and retention.

This Quick Start will quickly get you up and running with a project powered by LivePerson. When you're done, you'll be able to send messages between an iOS device and LiveEngage. To complete this Quick Start, you will need a LiveEngage account. You can get the number and login information from the LivePerson account team.

Prerequisites

To use the LivePerson Mobile App Messaging SDK, the following are required:

Version 3.1.1 and above

  • XCode 9.3 or later
  • Swift 4.1 or later, or Objective-C

Version 3.1 and below

  • XCode 9.2 or lower
  • Swift 4.0 or lower, or Objective-C

Note: For information on supported operating systems and devices, refer to System Requirements.

Step 1: Installing the SDK into your project

LiveEngage Mobile App Messaging SDK for iOS supports multiple methods of installations.

Option 1: Using CocoaPods

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.

  1. Install cocoapods using the following command:
$ gem install cocoapods
  1. Navigate to your project folder and init new pod using the following command:
$ pod init
  1. 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:
source 'https://github.com/LivePersonInc/iOSPodSpecs.git'
platform :ios, '9.0'
use_frameworks!

target '<Your Target Name>' do
  pod 'LPMessagingSDK'
end
  1. Run the following command in the terminal under your project folder:
$ pod install
  1. In case you wish to upgrade to the latest SDK version and you have already run 'pod install', run the following command:
$ pod update
  1. 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 and is necessary for archiving your app before publishing it to the App Store.
bash "${SRCROOT}/Pods/LPMessagingSDK/LPMessagingSDK/LPInfra.framework/frameworks-strip.sh"

Option 2: Using Libraries Copy to Xcode Project

  1. Click here to download the SDK package.

  2. Once downloaded, extract the ZIP file to a folder on your Mac.

  3. Copy (Drag and Drop) all framework and bundle files into the project.

  4. In project settings, navigate to the Build Phases tab, and make sure to have LPMessagingSDKModels.bundle under Copy Bundle Resources.

  5. 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 and is necessary for archiving your app before publishing it to the App Store.
bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/LPInfra.framework/frameworks-strip.sh"

Step 2: Configure project settings to connect LiveEngage SDK

If using CocoaPods open the Workspace created by CocoaPods rather than your Project and skip steps 1 and 2 below

  1. In project settings, navigate to the General tab, and add all Framework files to the Embedded Binaries section.

  2. In the General tab, make sure that the framework files are under Embedded Libraries.

  3. In Build settings, make sure Always Embed Swift Standard Libraries is set to YES.

  4. Due to a new Apple policy for iOS 10 (or later), apps must declare in their project settings which privacy settings may be used. For more information, refer to Apple’s website. In Xcode info.plist of the project, add two new privacy keys and values:

  • Key: NSPhotoLibraryUsageDescription, Value: "Photo Library Privacy Setting for LiveEngage Mobile App Messaging SDK for iOS",

  • Key: NSCameraUsageDescription, Value: "Camera Privacy Setting for LiveEngage Mobile App Messaging SDK for iOS",

  • Key: NSMicrophoneUsageDescription, Value: "Microphone Privacy Setting for LiveEngage Mobile App Messaging SDK for iOS"

This step is required in order to be able to upload your host app into the App Store, as SDK 2.0 has the ability to share photos from the camera and/or photo library. From version 3.2, the SDK has the ability to send audio messages, hence, the microphone permission is required for upload to app store, even if you are not using this feature.

Note: Due to Apple policy, this step is mandatory even if the photo sharing feature is disabled in the SDK.

  1. Some XCode Project's Capabilities need to be switched on in order to support SDK specific features. In XCode, navigate to project's Targets settings and select the relevant target of your app, then navigate to 'Capabilities' tab.
    • Push Notifications: SDK uses remote push notification to notify the user whenever a new message from remote user has been received. To use remote push notifications, switch on 'Push Notifications' toggle.
    • Structured Content: map items require MapKit framework to show location in map. To use map items, switch on 'Maps' toggle.

Step 3: Initialization

  1. Inside viewController add the following imports:
import LPMessagingSDK
import LPInfra
  1. Also inside ViewController, under viewDidLoad, add the following code:
do {
  try LPMessagingSDK.instance.initialize("Your account ID")
} catch {
  return
}
  1. Set up and call the conversation view. You’ll need to provide your LivePerson account number and a container view controller.
  let conversationQuery = LPMessagingSDK.instance.getConversationBrandQuery("Your account ID")
  let conversationViewParams = LPConversationViewParams(conversationQuery: conversationQuery, isViewOnly: false)
  LPMessagingSDK.instance.showConversation(conversationViewParams, authenticationParams: nil)
  1. In order to remove the conversation view when your container is deallocated, run the following code:
  let conversationQuery = LPMessagingSDK.instance.getConversationBrandQuery(accountNumber)
  LPMessagingSDK.instance.removeConversation(conversationQuery)
When using Custom View Controller Mode, the Conversation view must be removed when leaving the App. To avoid dismissing the View when CSAT/SecureForms/PhotoSharing View is presented, you should only dismiss the Conversation view if Moving From ParentView, as demonstrated below.
if (self.conversationQuery != nil && self.isMovingToParentViewController){
  LPMessagingSDK.instance.removeConversation(self.conversationQuery!)
}

Note: When ViewController Mode is used, on the Navigation Bar Back Button, you can simply call LPMessagingSDK.instance.removeConversation(self.conversationQuery!).

Step 4 (Optional): Initialization with Monitoring Params

To get the App key or appInstallationId, a new Conversation Source needs to be added on LiveEngage, for more information about it, contact your Account Team.
  1. Inside viewController add the following imports:
import LPMessagingSDK
import LPInfra
  1. Also inside ViewController, under viewDidLoad, add the following code:
do {
  let monitoringParams = LPMonitoringInitParams(appInstallID: "appInstallationId")
  try LPMessagingSDK.instance.initialize("Your account ID", monitoringInitParams: monitoringParams)
} catch {
  return
}
  1. Create LPMonitoringParams. The entry points and engagement attributes used here are dummies:
  let entryPoints = ["tel://972737004000",
                     "http://www.liveperson.com",
                     "sec://Sport",
                     "lang://Eng"]

  let engagementAttributes = [
    ["type": "purchase", "total": 20.0],
    ["type": "lead",
    "lead": ["topic": "luxury car test drive 2015",
          "value": 22.22,
          "leadId": "xyz123"]]
  ]

  let monitoringParams = LPMonitoringParams(entryPoints: entryPoints, engagementAttributes: engagementAttributes)
  1. Using the LPMonitoringParams, get the Engagement for the User. This is needed to start a new conversation with a specific campaign.
 LPMonitoringAPI.instance.getEngagement(consumerID: self.consumerID, monitoringParams: monitoringParams, completion: {
      if let first = engagement.engagementDetails?.first {
        let campaign = first.campaignId
        let id = first.engagementId
        let context : String = first.contextId!
        self.campaignInfo = LPCampaignInfo(campaignId: campaign, engagementId: id, contextId: context)
      } else {
        self.campaignInfo = nil
      }
    }) { (error) in
      self.campaignInfo = nil
    }
  }
  1. Set up and call the conversation view. You’ll need to provide your LivePerson account number, a container view controller and the campaign information.
let conversationQuery = LPMessagingSDK.instance.getConversationBrandQuery("Your account ID", campaignInfo: campaignInfo)
let conversationViewParams = LPConversationViewParams(conversationQuery: conversationQuery, isViewOnly: false)
LPMessagingSDK.instance.showConversation(conversationViewParams, authenticationParams: nil)
  1. In order to remove the conversation view when your container is deallocated, run the following code:
let conversationQuery = LPMessagingSDK.instance.getConversationBrandQuery(accountNumber)
LPMessagingSDK.instance.removeConversation(conversationQuery)
When using Custom View Controller Mode, the Conversation view must be removed when leaving the App. To avoid dismissing the View when CSAT/SecureForms/PhotoSharing View is presented, you should only dismiss the Conversation view if Moving From ParentView, as demonstrated below.
if (self.conversationQuery != nil && self.isMovingToParentViewController){
  LPMessagingSDK.instance.removeConversation(self.conversationQuery!)
}

Note: When ViewController Mode is used, on the Navigation Bar Back Button, you can simply call LPMessagingSDK.instance.removeConversation(self.conversationQuery!).