Embedded Service Chat SDK for iOS Developer Guide
jQuick Setup: Chat in the
Before running through these steps, be sure you’ve already:
- Set up Service Cloud to work with Chat. To learn more, see Org Setup for Chat in Lightning Experience with a Guided Flow.
- Installed the SDK. To learn more, see Install the Service Chat SDK for iOS.
Once you’ve reviewed these prerequisites, you’re ready to begin.
These steps describe how to set up Chat with the default UI. If you prefer to build your own user interface, see Build Your Own UI with the Chat Core API.
- Import the SDK. Wherever you intend to use the Chat SDK, be sure to import the ServiceCore framework and the ServiceChat framework.
-
Create an SCSChatConfiguration instance with information about
your LiveAgent pod, your Salesforce org ID, the deployment ID, and the button
ID.
In Swift:
1let config = SCSChatConfiguration(liveAgentPod: "TO_DO_POD_NAME", 2 // e.g. "d.gla5.gus.salesforce.com" 3 orgId: "TO_DO_ORG_ID", 4 // e.g. "00DB00000003Rxz" 5 deploymentId: "TO_DO_DEPLOYMENT_ID", 6 // e.g. "573B00000005KXz" 7 buttonId: "TO_DO_BUTTON_ID") 8 // e.g. "575C00000004h3m"In Objective-C:
1SCSChatConfiguration *config = 2 [[SCSChatConfiguration alloc] initWithLiveAgentPod:@"TO_DO_POD_NAME" 3 // e.g. "d.gla5.gus.salesforce.com" 4 orgId:@"TO_DO_ORG_ID" 5 // e.g. "00DB00000003Rxz" 6 deploymentId:@"TO_DO_DEPLOYMENT_ID" 7 // e.g. "573B00000005KXz" 8 buttonId:@"TO_DO_BUTTON_ID"]; 9 // e.g. "575C00000004h3m" -
(Optional) Configure the visitor name, queue display style, whether the user
can minimize the chat session, and various other configuration settings.
See Configure a Chat Session for more information.
-
(Optional) Customize the appearance with the configuration object.
You can configure the colors, fonts, and images to your interface with an SCAppearanceConfiguration instance. It contains the methods setColor, setFontDescriptor, and setImage. You can also configure the strings used throughout the interface. See SDK Customizations with the Service Chat SDK for iOS.
-
(Optional) Specify any pre-chat fields.
You can specify both optional and required fields shown to the user before a chat session starts. You can also directly pass data to an agent without requiring any user input. These fields can be mapped directly to fields in a record in your org.
See Show Pre-Chat Fields to User and Create or Update Salesforce Records from a Chat Session for more information.
-
To start a chat session, call the showChat(with:showPrechat:) method on SCSChatInterface.
In Swift:
1ServiceCloud.shared().chatUI.showChat(with: config!)In Objective-C:
1[[SCServiceCloud sharedInstance].chatUI showChatWithConfiguration:config];You can provide an optional completion block to execute code when the session has been fully connected to all services. During a successful session initialization, the SDK calls the completion block at the point that the session is active and the user is waiting for an agent to join. If there is a failure, the SDK calls the completion block with the associated error.
-
Listen for events and handle error conditions.
You can detect when a session ends by implementing the session(didEnd:) method on the SCSChatSessionDelegate delegate. Register this delegate using the add(delegate:) method on your SCSChat instance. In particular, we suggest that you handle the .agent reason (for when an agent ends a session) and the .noAgentsAvailable reason (for when there are no agents available). See Listen for State Changes and Events.
These steps embed the chat experience into your app.
Example
To use this example code, create a Single View Application and Install the Service Chat SDK for iOS.
Use the storyboard to add a button to the view. Add a Touch Up Inside action in your UIViewController implementation with the name startChat. In the view controller code:
- Implement the SCSChatSessionDelegate protocol so that you can be notified when there are errors or state changes.
- Specify self as a chat delegate.
- Start a chat session in the button action.
- Implement the session(didEnd:) method and show a dialog when appropriate.
In Swift:
1import UIKit
2import ServiceCore
3import ServiceChat
4
5class ViewController : UIViewController, SCSChatSessionDelegate {
6
7 override func viewDidLoad() {
8 super.viewDidLoad()
9
10 // Add our chat delegate
11 ServiceCloud.shared().chatCore.add(delegate: self)
12 }
13
14 @IBAction func startChat(_ sender: AnyObject) {
15
16 // Create config object
17 if let config = SCSChatConfiguration(liveAgentPod: "YOUR-POD-NAME",
18 orgId: "YOUR-ORG-ID",
19 deploymentId: "YOUR-DEPLOYMENT-ID",
20 buttonId: "YOUR-BUTTON-ID") {
21
22 // Start a session
23 ServiceCloud.shared().chatUI.showChat(with: config)
24 }
25 }
26
27 func session(_ session: SCSChatSession!, didEnd endEvent: SCSChatSessionEndEvent!) {
28
29 var description = ""
30
31 // Here we'll handle the situation where the agent ends the session
32 // and when there are no agents available...
33 switch endEvent.reason {
34 case .agent:
35 description = "The agent has ended the session."
36 case .noAgentsAvailable:
37 description = "It looks like there are no agents available. Try again later."
38 // TO DO: Handle other reasons
39 default:
40 description = "Session ended for an unknown reason."
41 }
42
43 let alert = UIAlertController(title: "Session Ended",
44 message: description,
45 preferredStyle: .alert)
46 let okAction = UIAlertAction(title: "OK",
47 style: .default,
48 handler: nil)
49 alert.addAction(okAction)
50 self.present(alert, animated: true, completion: nil)
51 }
52
53 func session(_ session: SCSChatSession!, didError error: Error!, fatal: Bool) {
54 // TO DO: Handle error condition
55 NSLog("Chat error: \(error.localizedDescription)")
56 }
57}In Objective-C:
1#import "ViewController.h"
2@import ServiceCore;
3@import ServiceChat;
4
5@interface ViewController : UIViewController <SCSChatSessionDelegate>
6
7@end
8
9@implementation ViewController
10
11- (void)viewDidLoad {
12 [super viewDidLoad];
13
14 // Add our chat delegate
15 [[SCServiceCloud sharedInstance].chatCore addDelegate:self];
16}
17
18- (IBAction)startChat:(id)sender {
19
20 // Create config object
21 SCSChatConfiguration *config =
22 [[SCSChatConfiguration alloc] initWithLiveAgentPod:@"YOUR-POD-NAME"
23 orgId:@"YOUR-ORG-ID"
24 deploymentId:@"YOUR-DEPLOYMENT-ID"
25 buttonId:@"YOUR-BUTTON-ID"];
26 // Start the session
27 [[SCServiceCloud sharedInstance].chatUI showChatWithConfiguration:config];
28}
29
30- (void)session:(id<SCSChatSession>)session didEnd:(SCSChatSessionEndEvent *)endEvent {
31
32 NSString *description = nil;
33
34 // Here we'll handle the situation where the agent ends the session
35 // and when there are no agents available...
36 switch (endEvent.reason){
37 case SCSChatEndReasonAgent:
38 description = @"The agent has ended the session.";
39 break;
40 case SCSChatEndReasonNoAgentsAvailable:
41 description = @"It looks like there are no agents available. Try again later.";
42 break;
43 // TO DO: Handle other reasons
44 default:
45 description = @"Session ended for an unknown reason.";
46 break;
47 }
48
49 UIAlertController *alert = [UIAlertController
50 alertControllerWithTitle:@"Session Ended"
51 message:description
52 preferredStyle:UIAlertControllerStyleAlert];
53
54 UIAlertAction* okAction = [UIAlertAction
55 actionWithTitle:@"OK"
56 style:UIAlertActionStyleDefault
57 handler:nil];
58
59 [alert addAction:okAction];
60 [self presentViewController:alert animated:YES completion:nil];
61}
62
63- (void)session:(id<SCSChatSession>)session didError:(NSError *)error fatal:(BOOL)fatal {
64 // TO DO: Handle error condition
65 NSLog(@"Chat error: \(error.localizedDescription)");
66}
67
68@end