Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Mobile Messaging SDK configuration in your iOS app project

Updated on June 29, 2022

Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide Pega Customer Service Implementation Guide
Before you begin:

To configure Mobile Messaging SDK in your iOS app project in Xcode, you need the following artifacts:

  • Pega Platform™: 8.7 or higher
  • CRM/CS: 8.7 or higher
  • iOS: 13 or higher
  • Xcode: 12.3 or higher

Installing Mobile Messaging App SDK manually on iOS application

  1. Download the Pega Mobile Messaging SDKfor iOS from the Digital Messaging Manager.
    The downloaded package bundles two files: DM Communication SDK and DM Chat SDK.
  2. Extract the contents of the downloaded SDK file.
  3. Drag the folder containing the Package.swift file into your workspace.
  4. In the target settings of your iOS app, navigate to Build Phases, and then add  DigitalMessagingChatSDK and  DigitalMessagingCommunicationSDK under Link Binary with Libraries build phase.
  5. Perform code-level integration. For more information, see Adding Mobile Messaging App SDK to your iOS Application.
    Note:   Make the added frameworks visible in your Xcode project by adjusting the FRAMEWORK_SEARCH_PATHS build setting.

Adding Mobile Messaging App SDK to your iOS Application

You launch messaging inside your iOS app by importing the DigitalMessagingChatSDK framework and configuring the PDMChatViewController.

Use the following SWIFT code to launch the messaging in your iOS application:


import DigitalMessagingChatSDK 
func launchChat() { 
let configuration = PDMChatViewController.Configuration(apiURL: <#T##URL#>, 
                                                        apiID: <#T##String#>, 
                                                        customerToken: <#T##String#>) 
    let chatController = PDMChatViewController(configuration: configuration) 
    navigationController?.pushViewController(chatController, animated: true) 
} 

In your Swift code, ensure that you provide values for the apiURL and apiID variables based on what the system generated in step 5a in the Creating an iOS app connection section.

UI customization

You can localize and customize strings that the Mobile Messaging SDK uses in the UI of your iOS app. The base localization of Pega Mobile Messaging SDK is English. You can modify or override the strings as described below:

Customize existing strings and adding localizations

If the integrating iOS app project does not yet have a Localizable.strings file in the localization language of choice, perform the following steps:

  1. In Xcode, in your iOS app project, click FileNewFile, and then select Resource in the iOS category in the sidebar.
  2. Select Strings File from the files, and then click Next.
  3. Name the file Localizable, and then click Create.

    After the system creates the file, examine the string definitions as shown in the following table, and then customize the definitions that you want in the Localizable.strings file.

List of localized strings

String definitionsLabel Description
"ios.attachments.error.general" = "Failed to attach";Attachment error caused by internal failure of attachment validation
"ios.attachments.error.filetypeNotAllowed" = "Failed to upload - file type not allowed";Attachment error caused by picking not allowed file type
"ios.attachments.error.fileSizeLimitExceeded" = "Failed to upload - Exceeded max file size %@";Attachment error caused by exceeding file size limit
"ios.attachments.permissions.error.cameraPermissionMissing" = "Capturing images requires camera permission. To enable access, tap Settings."; Missing camera permission error alert message
"ios.attachments.permissions.error.settings" = "Settings";Missing permission error alert "Go to settings" action
"ios.attachments.permissions.error.title" = "Missing permission";Missing permission error alert title
"ios.attachments.picker.source.camera" = "Take Photo";Attachment source selection - camera
ios.attachments.picker.source.files" = "Browse";Attachment source selection - a file attachment
"ios.attachments.picker.source.gallery" = "Select Photo";Attachment source selection - a photo library item attachment
"ios.attachments.picker.source.prompt" = "Select an action you want to perform";Attachment source selection prompt
"ios.general.cancel" = "Cancel";Cancel action
"ios.general.messages.prompt" = "Type a message";Input bar prompt
"ios.general.messages.newMessages" = "New messages";New messages indicator view
"ios.general.messages.typingAuthor" = "%@ is typing...";Typing indicator message subtitle when author is known
"ios.general.messages.typing" = "Typing...";Typing indicator message subtitle
"ios.general.messages.delivered" = "Delivered";Message delivered status

Customizing Chat appearance

You can also customize the appearance of the messaging screen in your iOS app.

The interface of the PDMTheme class contains the available customizations. You can combine the properties into major groups that group style elements of similar semantics.


 /// The main chat view styles configuration. 
    public let chatView: DigitalMessagingChatSDK.PDMTheme.ChatView 
 /// The message view styles configuration. 
    public let message: DigitalMessagingChatSDK.PDMTheme.Message 
 /// The chat input bar view styles configuration. 
    public let inputBar: DigitalMessagingChatSDK.PDMTheme.InputBar 

You can examine the PDMTheme interface to learn which customizations you can use.

The following SWIFT code sample shows how to customize the messaging screen appearance by changing the background and foreground color:

        let configuration = ... 
        let theme = PDMTheme() 
        theme.message.outgoing.background = UIColor.systemGreen 
        theme.message.outgoing.foreground = UIColor.white 
        theme.inputBar.buttons.attachButtonImage = UIImage(systemName: "rectangle.and.paperclip") 
        let chatController = PDMChatViewController(configuration: configuration, theme: theme)

After you pass the PDMTheme instance to the PDMChatViewController instance constructor, the system applies the messaging screen changes. The system does not refelct further changes.

Attributes

You can customize the chat view by specifying new values for the defined attributes.

Chat view

The following figure illustrates the common attributes for messages, such as text size, margins, message background, font family, and other attributes mentioned in the table.

Chat view

AttributeFormatDescription
theme.chatView.chatBackgroundColorUIColorThe background color of the chat view
theme.chatView.separatorColorUIColorThe color of the separator between input bar and the messages’ view

Attributes common for all messages

The following figure illustrates the common attributes for all messages, such as text size, message background, font family, and other attributes explained in the table:

Attributes common for all messages
Attributes common for all messages

Attribute FormatDescription
theme.message.outgoing.backgroundUIColorBackground color of the outgoing message
theme.message.outgoing.foregroundUIColorThe color of the outgoing message view's foreground elements (text and icons)
theme.message.outgoing.messageTextFont UIColorFont used for the outgoing message text content. User can define all attributes for UIFont including the selected Font (Family), of size, weight, etc
theme.message.incoming.backgroundUIColorBackground color of the incoming message
theme.message.incoming.foregroundUIColorThe color of the incoming message view's foreground elements (text and icons)
theme.message.incoming.messageTextFont UIFontFont used for the incoming message text content. User can define all attributes for UIFont including the selected Font (Family), of size, weight, etc
theme.message.typingIndicator.fontUIFont Typing indicator label font. User can define all attributes for UIFont including the selected Font (Family), of size, weight, etc
theme.message.typingIndicator.colorUIColorTyping indicator label text color
theme.message.typingIndicator.primaryUIColorColor of the typing indicator's active dot (for progress animation)
theme.message.typingIndicator.secondaryUIColorColor of the typing indicator's secondary dots (for progress animation)
theme.message.dateLabel.fontUIFontFont used for displaying the date label for all messages
theme.message.dateLabel.colorUIColorText color of the date label

Document message

The following figure illustrates the attributes of document attachments, such as attachment name font, attachment icon, download button icon, and other attributes explained in the table:

Attributes for document attachments
Attributes for document attachments

AttributeFormatDescription
theme.message.outgoing.attachmentNameFontUIFontFont used for displaying the name for the outgoing document message
theme.message.outgoing.attachmentMetadataFontUIFontFont used for displaying the metadata text of the outgoing document message
theme.message.outgoing.attachmentIconUIImageIcon used for the outgoing document message
theme.message.outgoing.downloadButtonIconUIImageIcon used for the download button of the outgoing document message
theme.message.incoming.attachmentNameFontUIFontFont used for displaying the name for the incoming document message
theme.message.incoming.attachmentMetadataFontUIFontFont used for displaying the metadata text of the incoming document message
theme.message.incoming.attachmentIconUIImageIcon used for the incoming document message
theme.message.incoming.downloadButtonIconUIImageIcon used for the download button of the incoming document message

Menu message

The following figure illustrates the attributes of a menu, such as font family, text size, and text color that the following table explains:

Attributes for menu messages
Attributes for menu messages

AttributeFormatDescription
theme.message.menuOption.fontUIFontFont used for the menu option label
theme.message.menuOption.primaryBackgroundUIColorBackground of menu items
theme.message.menuOption.primaryTintUIColorDefault text color of menu items
theme.message.menuOption.secondaryBackgroundUIColorBackground color of the selected menu option
theme.message.menuOption.secondaryTintUIColorText color of the selected option

Link button

The following figure illustrates the attributes of a link button, such as font, background color and other attributes explained in the following table:

Attributes for link button
Attributes for link button

AttributeFormatDescription
theme.message.linkButton.fontUIFontFont used for the link button text
theme.message.linkButton.backgroundUIColorBackground color of the link button
theme.message.linkButton.tintUIColorTint color used for foreground elements (Text and Icon) on the link button
theme.message.linkButton.iconUIImageIcon displayed after link button text

Input text area

The following figure illustrates the attributes of the input text area where the CSR types the message and sends it to the user. The attributes in the following table are of the input text area:

Attributes for input text area
Attributes for input text area

theme.inputBar.textInput.placeholderFontUIFontFont of the placeholder label
theme.inputBar.textInput.placeholderTextColorUIColorColor used for the placeholder text
theme.inputBar.textInput.inputFontUIFontFont used for the input text
theme.inputBar.textInput.inputTextColorUIColorColor used for the input text
theme.inputBar.buttons.sendButtonImageUIImageThe image used on the send button
theme.inputBar.buttons.attachButtonImageUIImageThe image used on the attachment button
theme.inputBar.buttons.primaryButtonBackgroundUIColorColor used as background for the send button
theme.inputBar.buttons.primaryButtonTintUIColorColor used as the tint color for the send button
theme.inputBar.buttons.secondaryButtonTintUIColorColor used as the tint color for the attachment button

Selected attachments

The following figure illustrates the attributes of selected attachments, such as border color, background color, foreground color and other attributes displayed in the following table:

Attributes for selected attachments
Attributes for selected attachments

AttributeFormatDescription
theme.inputBar.attachments.(normal || error || uploading).borderColorUIColorColor of the selected attachment view’s border. This can be defined for each of the attachment states (i.e., normal, error, uploading)
theme.inputBar.attachments.(normal || error || uploading).backgroundColorUIColorBackground color of the selected attachment view. This can be defined for each of the attachment states (i.e., normal, error, uploading)
theme.inputBar.attachments.(normal || error || uploading). foregroundColorUIColorColor of the view's foreground elements (text and icons). This can be defined for each of the attachment states (i.e., normal, error, uploading)
theme.inputBar.attachments.titleFontUIFontFont used for the attachment’s filename label. (Used only for non-image type attachments)
theme.inputBar.attachments.attachmentIconUIImageIcon used for representing attachments other that images
theme.inputBar.attachments.errorIconUIImageIcon indicating attachment upload failure
theme.inputBar.attachments. attachmentProgressBackgroundUIColorAttachment's progress indicator view’s background color
theme.inputBar.attachments. attachmentProgressTint UIColorAttachment's progress indicator view’s progress color
theme.inputBar.attachments. deleteButtonTintColorUIColorAttachment's delete button's tint color
theme.inputBar.attachments. deleteButtonBackgroundColor UIColorBackground color used for the attachment's delete button
theme.inputBar.attachments. deleteButtonImageUIImageImage used in the attachment's delete button

KM articles

The following figure illustrates the attributes of selected attachments, such as border color, background color, foreground color and other attributes displayed in the following table:

KM articles in iOS app
KM articles in iOS app

AttributeFormatDescription
theme.message.article.font UIFont Font used for KM article label
theme.message.article.primaryBackground UIColor KM article primary background color
theme.message.article.primaryTint UIColor KM article primary tint color
theme.message.article.iconLink UIImage KM article icon for link
theme.message.article.iconArticle UIImage KM article icon for text
theme.message.article.primaryLinkIconTint UIColor Link icon primary tint color.
theme.message.article.primaryArticleIconTint UIColor Article icon primary tint color
theme.message.article.itemAlignment Enum AlignItemsTo KM article message items alignment
theme.message.article.linkIconAlignment Enum AlignItemsTo Link icon supports left or right alignment
theme.message.article.articleIconAlignment Enum AlignItemsTo Article icon supports left or right alignment

KM articles preview

The following figure illustrates the attributes of selected attachments, such as border color, background color, foreground color and other attributes displayed in the following table:

Preview of a KM article in an iOS app

AttributeFormatDescription
theme.message.article.articlePreview.titleFont UIFont Font used for the preview title
theme.message.article.articlePreview.textFont UIFont Font used for the preview message
theme.message.article.articlePreview.linkFont UIFont Font used for the link in the preview
theme.message.article.articlePreview.titleTint UIColor The color for title in the article preview
theme.message.article.articlePreview.textTint UIColor Color used for the message in article preview
theme.message.article.articlePreview.linkTint UIColor Color used for the link in article preview
theme.message.article.articlePreview.iconLink UIImage Image used for the link in article preview
theme.message.article.articlePreview.iconRemoveButton UIImage Image used for the close button in article preview
theme.message.article.articleText.removeIconTintColor UIColor Color used for the close icon in article preview
theme.message.article.articlePreview.iconTint UIColor Color used for the icon in link in article preview
theme.message.article.articlePreview.backgroundCornerRadius Number

Border radius for the outermost background view

(i.e. black background)

theme.message.article.articlePreview.textViewCornerRadius Number

Border radius for the inner view that holds the text

(i.e. white background)

theme.message.article.articleText.linkIconAlignment Enum AlignItemsTo (.left or .right to align icons to the left side of the link or the right side respectively)

Action menu

The following figure illustrates the attributes of the Action Menu, such as font family, text size, text color of the button, and other attributes:

Action menu in an iOS app
Action menu in an iOS app

AttributeFormatDescription
theme.actionMenu.menuBackgroundColor UIColor The actions menu background color
theme.actionMenu.menuBorderColor UIColor Border color for the action menu
theme.actionMenu.menuItemIconTint UIColor The actions menu icon primary tint color
theme.actionMenu.menuItemTextTint UIColor The actions menu item text color
theme.actionMenu.endSessionButtonImage UIImage The action menu image to be applied on the end session button
theme.actionMenu.transcriptDownloadButtonImage UIImage The action menu image to be applied on the download transcript button

Chat dialog

The following figure illustrates the attributes of the Chat Dialog, such as font family, text size, text color of the button, and other attributes:

Chat dialog in an iOS app
Chat dialog in an iOS app

AttributeFormatDescription
theme.dialog.bannerColor UIColor The banner color shown at the top of the dialog
theme.dialog.icon UIImage The icon for the dialog
theme.dialog.titleFont UIFont The font for the dialog title
theme.dialog.titleTextColor UIColor The text color for the dialog title
theme.dialog.messageFont UIFont The font for the dialog message
theme.dialog.messageTextColor UIColor The font color for the dialog message
theme.dialog.actionButtonTextColor UIColor The text color for the action button
theme.dialog.actionButtonBackgroundColor UIColor The background color for the action button
theme.dialog.actionButtonFont UIFont The font for the dialog button
theme.dialog.dismissButtonTextColor UIColor The text color for the dismiss button
theme.dialog.dismissButtonBackgroundColor UIColor The background color for the dismiss button
theme.dialog.dismissButtonFont UIFont The font for the dialog button

Handling new messages when chat is inactive

You can handle new messages when the chat is inactive. When the system calls thelaunchChat() method, it starts a chat session and sends a new message to the server, and then the system closes the screen launched in the launchChat() method.

When you set backgroundDelegate:

  1. The system retains the chat session as long as MainViewController exists.
  2. To handle new message, the system makes available as an implementation measure a callback method from the PDMChatBackgroundDelegate extension.

The following SWIFT code is a of handling new messages when the chat is inactive:


import DigitalMessagingChatSDK 
class MainViewController: UIViewController { 
    func launchChat() { 
       let configuration = ... 
       let theme = ... 
       let chatController = PDMChatViewController(configuration: configuration, theme: theme) 
       chatController.backgroundDelegate = self 
       navigationController?.pushViewController(chatController, animated: true) 
    } 
} 
extension MainViewController: PDMChatBackgroundDelegate { 
    func chat(didReceive message: Message) { 
        print("Message received: \(message)") 
    } 
} 

Methods and callbacks

End session method

This feature allows the app using the Mobile Messaging SDK to call the end chat session method and close the currently open chat session on user request.

iOS Implementation

The implementation of the PDMMenuHandler class. Use this class to toggle menu, request transcript and End session functionality

 public class PDMMenuHandler { 

public init(_ viewController: PDMChatViewController?) {} 
  		 

/// Use this method to end the current session 

public func endSession() {} 
/// Use this method to download the chat transcript 

public func requestTranscript() {}  

/// Use this method to show the actions menu. 

/// If this method is called when the menu is present on the UI, menu will be 	 

/// removed 

public func showActionsMenu() {} 

} 
endSession() function is available in PDMMenuHandler 

Use this method to end the current session 
private var menuHandler: PDMMenuHandler? 

... 

let chatController = PDMChatViewController(configuration: configuration) 
menuHandler = PDMMenuHandler(chatController) 

... 
menuHandler.endSession() // this will request the transcript 

Chat Transcript Method

This feature allows the app using the Mobile Messaging SDK to initiate a chat transcript download inside the SDK on user request.

iOS Implementation

public class PDMMenuHandler { 
public init(_ viewController: PDMChatViewController?) {} 	 

/// Use this method to end the current session 
public func endSession() {} 

/// Use this method to download the chat transcript 

public func requestTranscript() {} 

/// Use this method to show the actions menu. 
/// If this method is called when the menu is present on the UI, menu will be 	 

/// removed 
public func showActionsMenu() {} 
} 
requestTranscript () function is available in PDMMenuHandler 
Use this method to request transcript from the server 
private var menuHandler: PDMMenuHandler? 
... 
let chatController = PDMChatViewController(configuration: configuration) 
menuHandler = PDMMenuHandler(chatController) 
... 
menuHandler.requestTranscript() // this will request the transcript 

Show menu

This feature allows the app using the Mobile Messaging SDK to open menu on the user request.

iOS Implementation

public class PDMMenuHandler { 
public init(_ viewController: PDMChatViewController?) {} 
/// Use this method to end the current session 
public func endSession() {} 
/// Use this method to download the chat transcript 
public func requestTranscript() {}     

/// Use this method to show the actions menu. 
/// If this method is called when the menu is present on the UI, menu will be 	 
/// removed 

public func showActionsMenu() {} 
} 
showActionsMenu () function is available in PDMMenuHandler 
Use this method to show the actions menu 
private var menuHandler: PDMMenuHandler? 
... 
let chatController = PDMChatViewController(configuration: configuration) 
menuHandler = PDMMenuHandler(chatController) 
... 
menuHandler.showActionsMenu() // this will toggle the menu 

AuthTokenProvider Callback

This callback is used to provide a signed JWT authentication Token to the SDK for validating the Customer ID and setting up a chat session.

Note: Avoid passing any reference of the Chat Fragment to authToken callback. Because the ChatConfiguration object has longer lifecycle than the Chat Fragment, once the Chat Fragment is destroyed, this might cause memory leaks.

iOS Implementation

Chat configuration expects the following parameters:

public init(apiURL: URL, apiID: String, customerToken: String, authProvider: AuthTokenProviderInterface) { 
 open class AuthTokenProviderInterface: AuthTokenProvider { 
 public init(apiId: String, endpoint: String) {} 
 open func getAuthToken(completionHandler: @escaping (String?, Error?) -> Void) {} 
}  
  1. Create a class that inherits from AuthTokenProviderInterface.
  2. Initialize the class with appId and the URL endpoint.
  3. Implement the getAuthToken function to make the request.

    Call completionHandler in a main thread once the request resolves.

Session ID Callback This callback is used to provide a signed JWT authentication Token to the SDK for validating the Customer ID and setting up a chat session.

Note: Avoid passing any reference of the Chat Fragment to authToken callback. Because the ChatConfiguration object has longer lifecycle than the Chat Fragment, once the Chat Fragment is destroyed, this might cause memory leaks.

iOS Implementation

// Implement the showActionsMenu() function in PDMPrivateDataDelegate protocol. 
let chatController = PDMChatViewController(configuration: configuration) 
chatController.privateDataDelegate = self 
extension DemoViewController: PDMPrivateDataDelegate { 
func sessionInitialized(sessionID id: String) { 
        print("Received sessionId: \(id)") 
    } 
}   

  • Previous topic Mobile Messaging SDK configuration in your Android app project
  • Next topic Private Data API for secure data transmission

Tags

Pega Customer Service 8.7 Pega Customer Service for Communications 8.7 Pega Customer Service for Financial Services 8.7 Pega Customer Service for Healthcare 8.7 Pega Customer Service for Insurance 8.7

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us