Integrating iOS SDK

Getting Started

What is Prism SDK?

Prism SDK is visitor-facing iOS library to enable merchant integrate with Prism live chat widget in their own iOS application.

Variants

Currently there are two variants of the Prism SDK.

  • Core SDK : Provide basic functions to merchant who wants to integrate Prism onto their own User Interface
  • UI SDK : Provide chat widget UI - tailored for merchant who wants to integrate with minimum customisation

Integration

UI SDK

It's a variant of Prism iOS SDK for merchants who want to integrate Prism chat to buy capabilities easily into their application using provided UI.

1. System Requirements

There are some requirements for merchants who want to use this SDK

  • Must be native iOS project
  • Minimum supported OS is iOS 9
  • Using Cocoapods

2. Integration

2.1. Register as Prism Merchant

These are some basic requirements to integrate with Prism :

  1. Prism account. Please register here.
  2. Get your merchant id at Settings -> Account -> Merchant Account.
  3. Prepare your project
2.2. Install the SDK with Cocoapods

Add this to your Podfile

pod 'PrismUI'

Then run pod install. In any file you'd like to use PrismCore don't forget to import the framework with import PrismCore

2.3. Configure info.plist

To make the SDK runs well, you need to update your info.plist first

2.3.1 Setup Photo Library Permission

The SDK need this to access Photo Library, so you can send a photo to Agent

<key>NSPhotoLibraryUsageDescription</key>
<string>We need your permission to access Photo Library</string>
2.3.2 Setup Status Bar Appearance

The UI SDK have various themes, so we need to make sure that the status bar style match with the currently used theme

<key>UIViewControllerBasedStatusBarAppearance</key>
<true/>
2.4. Configure Environment & Merchant ID

Insert this code inside applicationDidFinishLaunching function, replace the environment and merchantID with yours

PrismUI.shared.configure(environment: environment,
                         merchantID: merchantID)
2.5. Present Prism View

To show Prism View, you only need to run this code, replace presenterViewController with your UIViewController

PrismUI.shared.present(on: presenterViewController)
2.6. Configure Push Notification

You can set up Push Notifications so that users can receive messages even when the app is inactive or in background state.

Follow this steps to enable push notifications for iOS

2.6.1 Create a Certificate Signing Request(CSR)

Open Keychain Access on your Mac (Applications -> Utilities -> Keychain Access). Select Request a Certificate From a Certificate Authority.

In the Certificate Information window, do the following:

  • In the User Email Address field, enter your email address.
  • In the Common Name field, create a name for your private key (e.g., John Doe Dev Key).
  • The CA Email Address field should be left empty.
  • In the Request is group, select the Saved to disk option.

2.6.2 Create a Push Notification SSL certificate

Log in to the Apple Developer Member Center and find the Certificates, Identifiers & Profiles menu. Select App IDs, find your target application, and click the Edit button.

Enable Push Notifications and create a development or production certificate to fit your purpose.

You should upload the CSR file that you created in section (1) in order to complete this process. After doing so, you should be able to download a SSL certificate.

Double-click the file and register it to your login keychain.

2.6.3 Export a p12

Under Keychain Access, click the Certificates category from the left menu. Find the Push SSL certificate you just registered and right-click it without expanding the certificate. Then select Export to save the file to your disk.

Keychain will ask you for a password, but just leave it empty.

NOTE: It is very important that your p12 has no password.

After that, please send the certificate to [email protected] so we can further register the certificate.

2.6.4 Request for Push Notification Permission

In the applicationDidFinishLaunching function, insert these codes to ask permission for Push Notification

if #available(iOS 10.0, *) {
    UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge]) {
        (granted, error) in
        if granted {
            UIApplication.shared.registerForRemoteNotifications()
        }
    }
} else {
    UIApplication.shared.registerUserNotificationSettings(UIUserNotificationSettings(types: [.badge, .sound, .alert], categories: nil))
    UIApplication.shared.registerForRemoteNotifications()
}
2.6.5 Register Device Token

In the application(_, didRegisterForRemoteNotificationsWithDeviceToken: _) function, insert these codes

let token = deviceToken.map { String(format: "%02.2hhx", $0) }.joined()
PrismUI.shared.sendDeviceToken(deviceToken: token)

Core SDK

Core SDK helps merchant who want to integrate with Prism using their own UI and custom experiences.

Requirements

There are some basic requirements to integrate with core SDK

  1. Prism account. Please register here.
  2. Get your merchant id at Settings -> Account -> Merchant Account.
  3. Our SDK is compatible with iOS apps supporting iOS 8.0 and above. It requires Xcode 8.0+ to build the source.

Install From Cococapods

Add this to your Podfile

pod 'PrismCore'

Then run pod install. In any file you'd like to use PrismCore don't forget to import the framework with import PrismCore

Initialize SDK

Before you can use the SDK, you need to specify merchant_id and environment as initial configuration

PrismCore.shared.configure(environment: enum of EnvironmentType,
                           merchantID: "merchant_id",
                           delegate: self)

Visitor Connect

Visitor connect is used to get credentials for your visitors so they can use Prism platform capabilities.

PrismCore.shared.visitorConnect(visitorName: "visitor_name",
                                userID: "visitor_identifier",
                                completionHandler: {(response, error) in
})

The response is ConnectResponse, it contains the following variables :

  • OAuth credentials is used to access more features such as initiate a conversation, upload attachment to Prism storage, etc.
  • MQTT credentials is used to access real time messaging broker that Prism use to hold a conversation.
  • Visitor contains visitor data that may be used to identify each visitor.

Create Conversation

Create conversation is used by visitor to initiate a conversation so it needs visitor credential obtained at visitor connect process.

PrismCore.shared.createConversation(visitorName: visitor.name,
                                    token: oAuth.accessToken,
                                    completionHandler: {(response, error) in

})

Connect to Messaging Broker

Before you can use real time messaging broker to send message or subscribe to a conversation, your visitor must connect to Prism messaging broker first.

You can get username & password from MQTT object in Connect Response

PrismCore.shared.connectToBroker(username: mqtt.username,
                                 password: mqtt.password,
                                 completionHandler: {(success, error) in

})

Subscribe to Conversation

Your visitor can subscribe to a conversation to receive new message by real time.

PrismCore.shared.subscribeToTopic(conversation.topic,
                                  completionHandler: {(success, error) in
}

Send Message to Conversation

Your visitor can send message to a conversation. Message that was sent to Prism messaging broker must follow Prism specification.

Before that, you need to create Message object first

Create Message Object

var message = Message(
    id: "",
    conversationID: "",
    merchantID: "",
    channel: "",
    channelInfo: channelInfo,
    visitor: visitor,
    sender: sender,
    type: enum of MessageType,
    content: content,
    brokerMetaData: broker
)

In Message object, you need to specify content object according to your need

Create Text Message Content
let contentText = ContentPlainText(text: "content text")

Create Attachment Message Content
ContentAttachment(name: "name",
                  mimeType: "mime_type",
                  url: "attachment_url",
                  previewURL: "attachment_preview_url")
Build Sticker Message Content
ContentSticker(
    name: "",
    imageURL: "image_url",
    id: "",
    packID: ""
)
Send The Message

Once your Message object is ready, you can publish/send it with publishMessage method

PrismCore.shared.publishMessage(topic: conversation.topic,
                                message: message,
                                completionHandler: {(message, error) in
})

Unsubscribe From Topic

In some case, your visitor can unsubscribe from a conversation when they don't want receive message.

PrismCore.shared.unsubscribeFromTopic(topic: conversation.topic) { (success, error) in

}

Disconnect

There is case when in merchant app, visitor is logged out, they need to disconnect from message broker because it's not used anymore.

PrismCore.shared.disconnectFromBroker { response in

}

Upload Attachment

Note: Currently Prism only supports images for attachment with maximum size is 2Mb.

To upload an image to Prism storage there are some steps to follow:

  1. Create attachment URL from Prism
  2. Upload selected image to Prism storage.
Create Attachment URL

To create attachment URL you must provide file name and its content type.

PrismCore.shared.getAttachmentURL(filename: "",
                                  conversationID: "",
                                  token: "",
                                  completionHandler: {(response, error) in

})
Upload Image to Prism Storage

To upload image you must provide a attachment_data based on your selected image and the same content type that you provide when creating attachment URL.

PrismCore.shared.uploadAttachment(with: attachment_data,
                                  url: attachment_url,
                                  completionHandler: {(success, error) in

})

Get Available Stickers

By default Prism has several Prism sticker packs that can be used freely. In order to use that, you must enable your sticker packs in Prism dashboard by selecting Settings -> Stickers menu.

PrismCore.shared.getStickers(token: access_token) { (response, error) in

}

Refresh Token

OAuth credentials can be expired. Visitor can request a new OAuth credentials by doing refresh token using current refresh token and client id obtained on visitor connect.

PrismCore.shared.refreshToken(clientID: "", refreshToken: "") { (response, error) in

}

Error

Prism iOS SDK has 2 error types

  • Expected, we produce these errors, the instance of the error is PrismError.
  • Unexpected, we didn't produce these errors, we only passed it to the callback/ completion handler.