Campaigns are the cornerstone of Conversational Cloud — the place where every digital engagement is created and organized. By using campaigns, brands can target specific audiences to achieve their business goals, such as increasing sales or generating leads.

Use the Monitoring APIs to:

  • Report on the customer's journey inside the app

  • Retrieve engagements based on the reported SDEs

  • Report on engagement attributes

  • Route conversations to a specific skill (based on engagements)

While web messaging allows automatic capturing of events (using the Web Tag), when using campaigns for In-App Messaging, it is up to the app to report the various events by using the In-App Monitoring APIs.

Prerequisites

  • Follow the steps in the Campaigns for Messaging guide before adding the implementation to a mobile app.

  • The SDK must be initialized with the LPMonitoringInitParams object.

Notes and best practices

  • To start a conversation with a specific campaign and engagement, provide an LPCampaignInfo object to the LPConversationViewParams object.

  • A monitoring session is a 6-hours window. All SDEs that report during the session get aggregated.

  • If not reporting any SDEs (idle) for 30 minutes, a new session starts when reporting the next SDE.

Monitoring APIs

The Monitoring APIs provide brands access to the LivePerson monitoring system. The eligibility of an engagement is based on campaigns and an engagement's definitions. Monitoring APIs include:

  • sendSDE - Sends engagement attributes to LivePerson. Use whenever the app would like to report on an engagement attribute.

  • getEngagement (default method with identities and monitoringParams only) - Returns an engagement if there is a matching campaign and engagement. Use to send engagement attributes (as part of the request body) as well.

  • getEngagement (with additional authParams) - Same as the default method above, and this new method provide additional option for brands to supply authParams when calling our monitoring module. Available since: SDK v6.14.0. !Important: This method only works with the Implicit and Code Flow authentication method.

Please refer to the code samples for more information.

Code samples

This sample code demonstrates the usage of sendSDE and getEngagement (default method with identities and monitoringParams only).

// 1. Init SDK with Monitoring
let monitoringInitParams = LPMonitoringInitParams(appInstallID: "appInstallID")
do {
    try LPMessaging.instance.initialize("accountNumber", monitoringInitParams: monitoringInitParams)
} catch let error as NSError {
    print("initialize error: \(error)")
    return
}

// 2. APIs
let entryPoints = ["https://www.liveperson-test.com/",
                   "sec://Food",
                   "lang://De"]
let engagementAttributes = [
    ["type": "purchase",
     "total": 11.7,
     "orderId": "DRV1534XC"],
    ["type": "lead",
     "lead": ["topic": "luxury car test drive 2015",
              "value": 22.22,
              "leadId": "xyz123"]]
]

let monitoringParams = LPMonitoringParams(entryPoints: entryPoints, engagementAttributes: engagementAttributes, pageId: "pageId")
let identity = LPMonitoringIdentity(consumerID: "consumerID", issuer: "BrandIssuer")
// Note: if consumerID is nil / empty string, SDK will try to retrieve un-auth engagement; else SDK will try to retrieve auth engagement. 

// SendSDE
LPMessaging.instance.sendSDE(identities: [identity], monitoringParams: monitoringParams, completion: { (sendSdeResponse) in
    print("received send sde response: \(String(describing: sendSdeResponse))")
    })
    { [weak self] (error) in
    print("send sde error: \(error.userInfo.description)")
    }

// GetEngagement (default method with identities and monitoringParams only)
LPMessaging.instance.getEngagement(identities: [identity], monitoringParams: monitoringParams, completion: { (getEngagementResponse) in
    print("received get engagement response: \(String(describing: getEngagementResponse))")
}) { [weak self] (error) in
    print("get engagement error: \(error.userInfo.description)")
}

// 3. Show Conversation using Campaign
// LPCampaignInfo parameters are based on the response of getEngagement() using getEngagementResponse (of Type //LPGetEngagementResponse) and includes LPEngagementDetails

let campaignInfo = LPCampaignInfo(campaignId: campaignID, engagementId: engagementID, contextId: contextID)
// Add campaignInfo to conversationQuery
let conversationQuery = LPMessaging.instance.getConversationBrandQuery(accountNumber, campaignInfo: campaignInfo)
let conversationViewParam = LPConversationViewParams(conversationQuery: conversationQuery, isViewOnly: false)
// show conversation using campaignInfo
LPMessaging.instance.showConversation(conversationViewParam)

Code samples

This sample code demonstrates the usage of getEngagement (with additional authParams). !Important: This method only works with the Implicit and Code Flow authentication method.

// 1. Init SDK with Monitoring
let monitoringInitParams = LPMonitoringInitParams(appInstallID: "appInstallID")
do {
    try LPMessaging.instance.initialize("accountNumber", monitoringInitParams: monitoringInitParams)
} catch let error as NSError {
    print("initialize error: \(error)")
    return
}

// 2. APIs
let entryPoints = ["https://www.liveperson-test.com/",
                   "sec://Food",
                   "lang://De"]
let engagementAttributes = [
    ["type": "purchase",
     "total": 11.7,
     "orderId": "DRV1534XC"],
    ["type": "lead",
     "lead": ["topic": "luxury car test drive 2015",
              "value": 22.22,
              "leadId": "xyz123"]]
]

let monitoringParams = LPMonitoringParams(entryPoints: entryPoints, engagementAttributes: engagementAttributes, pageId: "pageId")

let issuer = "idpIssuerName"
//Note: 'issuer' can use empty string value/ nil for single-identity-provider (IDP); or specify the issuer name for multiple IDPs.
let consumerJWE = "eyJhbG..."
//Note : SDK supports JWT / JWE tokens

let identity = LPMonitoringIdentity(consumerID: nil, issuer: issuer)
// Note: supply consumerID as nil / empty string for this getEngagement method

// GetEngagement (with additional authParams)
let authenticationParams = LPAuthenticationParams(authenticationCode: nil,
                                                  jwt: consumerJWE,
                                                  issuerDisplayName: issuer,
                                                  authenticationType: .authenticated)
LPMessaging.instance.getEngagement(identities: [identity], monitoringParams: monitoringParams, authParams: authenticationParams, completion: { (getEngagementResponse) in
    print("received get engagement response: \(String(describing: getEngagementResponse))")
}) { [weak self] (error) in
    print("get engagement error: \(error.userInfo.description)")
}

// 3. Show Conversation using Campaign
// LPCampaignInfo parameters are based on the response of getEngagement() using getEngagementResponse (of Type //LPGetEngagementResponse) and includes LPEngagementDetails

let campaignInfo = LPCampaignInfo(campaignId: campaignID, engagementId: engagementID, contextId: contextID)
// Add campaignInfo to conversationQuery
let conversationQuery = LPMessaging.instance.getConversationBrandQuery(accountNumber, campaignInfo: campaignInfo)
let conversationViewParam = LPConversationViewParams(conversationQuery: conversationQuery, isViewOnly: false)
// show conversation using campaignInfo
LPMessaging.instance.showConversation(conversationViewParam)