Getting started

Getting started

The SDK has the following requirements:

• Minimum iOS version: 11.0
• XCFrameworks are only forward compatible with equal or newer versions of the Swift Compiler. The ChatSDK will not compile with Xcode versions prior to the version it was compiled with.

Add the Chat SDK dependencies

You can add the Chat SDK to your project using CocoaPods, Carthage or manually.

Adding the SDK with Swift Package Manager

To integrate the Chat SDK using Swift Package Manager, follow the instructions inAdding the Chat SDK.

Adding the SDK with CocoaPods

To integrate the Chat SDK using CocoaPods, follow the instructions inAdding the Chat SDK.

Adding the SDK with Carthage

To integrate the Chat SDK using Carthage, follow the instructions inAdding the Chat SDK.

Adding the SDK manually

While we recommend using a third-party dependency manager like Carthage or CocoaPods, you can also manually integrate the Chat SDK by following the instructions inAdding the Chat SDK.

Initializing the SDK

To initialize the Chat SDK, you must provide your account key. If you want to implementpush notifications, you must also provide the appId. Both can can be obtained by asking the account owner.

Swift

             

              
import ChatSDKimport ChatProvidersSDKChat.initialize(accountKey: <#"Your account key"#>, appId: <#Your app identifier#>)
             

Objective-C

             

              
#import<ChatSDK/ChatSDK.h>#import<ChatProvidersSDK/ChatProvidersSDK.h>[ZDKChat initializeWithAccountKey:<#"Your account key"#>appId:<#Your app identifier#>queue:dispatch_get_main_queue()];
             

Configuring the SDK

Configuring the conversation

The Chat SDK provides theChatConfigurationclass that you can use to enable or disable certain conversational features.

Swift

             

              
let chatConfiguration = ChatConfiguration()chatConfiguration.isAgentAvailabilityEnabled = false
             

Objective-C

             

              
ZDKChatConfiguration*chatConfiguration=[[ZDKChatConfiguration alloc]init];chatConfiguration.isAgentAvailabilityEnabled=YES;
             

For the full documentation on theChatConfigurationclass, seeCustomizing the look.

Setting information for the chat session

The chat can be configured using theChatAPIConfigurationclass.

Swift

             

              
let chatAPIConfiguration = ChatAPIConfiguration()chatAPIConfiguration.departmentName = "Department name"chatAPIConfiguration.visitorInfo = VisitorInfo(name: <#"Name"#>, email: <#"Email address"#>, phoneNumber: <#"Phone number"#>)Chat.instance?.configuration = chatAPIConfiguration
             

Objective-C

             

              
ZDKChatAPIConfiguration*chatAPIConfiguration=[[ZDKChatAPIConfiguration alloc]init];chatAPIConfiguration.departmentName=<#"Department name"#>;chatAPIConfiguration.visitorInfo=[[ZDKVisitorInfo alloc]initWithName:<#"Name"#>email:<#"Email address"#>phoneNumber:<#"Phone number"#>];ZDKChat.instance.configuration=chatAPIConfiguration;
             

To update a configuration once it has been initially set, you must apply changes to aChatAPIConfigurationobject and then again set it withChat.instance?.configuration = chatAPIConfiguration, as above.

Note: You can use eitherdepartmentNameordepartmentIdto set the department.departmentwill be removed in a future version.

VisitorInfo

Important:department,visitorPathOne,visitorPathTwo, andvisitorPathTwoValuecan't be updated once a chat has started.visitorInfoandtagscan be updated throughout a session.

Important: If you're setting a department while also using a trigger to send an initial message, please seeherefor related information.

Starting a chat

Starting a chat begins with building the messaging interface, and this requires at least one product engine to be passed into the buildUI method. See theUnified SDKdocumentation for more information relating to product engines and how to use them.

Swift

             

              
import ChatSDKimport MessagingSDKfunc startChat() throws {// Name for Bot messageslet messagingConfiguration = MessagingConfiguration()messagingConfiguration.name = "Chat Bot"let chatConfiguration = ChatConfiguration()chatConfiguration.isPreChatFormEnabled = true// Build view controllerlet chatEngine = try ChatEngine.engine()let viewController = try Messaging.instance.buildUI(engines: [chatEngine], configs: [messagingConfiguration, chatConfiguration])// Present view controllerself.navigationController?.pushViewController(viewController, animated: true)}
             

Objective-C

             

              
-(void)startChat{ZDKMessagingConfiguration*messagingConfiguration=[[ZDKMessagingConfiguration alloc]init];messagingConfiguration.name=@“聊天机器人”;ZDKChatConfiguration*chatConfiguration=[[ZDKChatConfiguration alloc]init];chatConfiguration.isPreChatFormEnabled=YES;// Build view controllerNSError*error=nil;NSArray*engines=@[(id<ZDKEngine>)[ZDKChatEngine engineAndReturnError:&error]];UIViewController*viewController=[ZDKMessaging.instance buildUIWithEngines:enginesconfigs:@[messagingConfiguration,chatConfiguration]error:&error];// Present view controller[self.navigationController pushViewController:viewController animated:YES];}
             

Important: You need to add a button to dismiss the view controller if you are presenting modally. SeePresenting the screenin the Unified SDK docs.

Important:If the Chat SDK is used in conjunction with the Answer Bot SDK, the Answer Bot SDK must be added before the Chat SDK. SeeRunning the engine with other enginesin the Chat engine docs.

Push Notifications

You can use push notifications with the Chat SDK to notify your users every time the agent sends new message to the conversation. To learn how to enable the push notifications in your app, seePush Notifications.

Offline Forms

Offline forms provide a way for your visitors to contact you when all of your agents are offline. The form supports name and email input, where the email field is required to complete the form. It will create a ticket on your support dashboard once submitted. Offline forms can be enabled or disabled by setting theisOfflineFormEnabledflag in theChatConfigurationclass. TheisAgentAvailabilityEnabledflag needs to be enabled for offline forms to work. For more details, seeCustomizing the Chat experience.

Configuring the queue

The queue provides a way for users to see a rough estimate on how long they will be waiting to talk to an agent. It is based on the number of other visitors ahead of them. It is not possible to disable the queue, but it is possible to change or remove the text. Seeknown issuesfor more information.

Session termination

The chat session will terminate ifanyof the following conditions are met:

• The visitor without push has been idle* for more than 20 minutes (30 minutes total).
• The visitor with push has been inactive for more than 5 minutes.
• 客人已经断开连接的持续时间of the inactivity timeout (30 minutes or 5 minutes).
• The agent ends the chat, at which point the session will terminate after 5 minutes without visitor input, regardless off whether push notifications have been configured. Any new message will place you back in the queue.
• The visitor ends the chat, at which point the session will immediately terminate.
• On the Agent Workspace account, if either the visitor or the agent ends the chat, the session will immediately terminate.

*The visitor will become idle after no input is detected for 10 minutes.

Logging

日志可以启用后的values:

The default isinfobutverbosewill provide the most information.

Swift

             

              
Logger.isEnabled = trueLogger.defaultLevel = .verbose
             

Objective-C

             

              
ZDKChatLogger.isEnabled=YES;ZDKChatLogger.defaultLevel=ZDKChatLogLevelVerbose;
             

Integrate with SwiftUI

See the documentation hereif you are integrating the SDK in aSwiftUIview hierarchy.

Advanced Topics

See the documentation of our APIsfor descriptions of classes and models.