Migration Guide
Migration Guide
If you're migrating from an older version of the Chat SDK (prior to v2), this guide will help to highlight some of the key differences.
Initializing the Chat SDK
The Chat SDK initialization should take place in your AppDelegate.swift. The initialization method takes the following parameters:
- accountKey - This can be found on the Chat dashboard. Ask a Chat admin for the key if you don't have access to the dashboard.
- apiConfig - Provides a way to configure the chat.
- thread - The thread to dispatch operations on. Default is the main thread.
Before
ZDCChat.initialize(withAccountKey: accountKey)
After
Chat.initialize(accountKey: accountKey, queue: .main)
Starting the chat
Before
ZDCChat.start(in: self.navigationController, withConfig: config)
After
do {
let chatEngine = try ChatEngine.engine()
let viewController = try Messaging.instance.buildUI(engines: [chatEngine], configs: [])
navigationController?.pushViewController(viewController, animated: true)
} catch {
// handle error
}
Adding visitor information
Before
ZDCChat.updateVisitor { user in
user?.name = "Name"
user?.email = "Email address"
user?.phone = "Phone number"
}
After
let chatAPIConfiguration = ChatAPIConfiguration()
chatAPIConfiguration.visitorInfo = VisitorInfo(name: "Name", email: "Email address", phoneNumber: "Phone number")
Chat.instance?.configuration = chatAPIConfiguration
Setting the department
Before
ZDCChat.start(in: self.navigationController, withConfig: { config in
config?.department = "Department name"
})
After
let chatAPIConfiguration = ChatAPIConfiguration()
chatAPIConfiguration.department = "Department name"
Chat.instance?.configuration = chatAPIConfiguration
// OR
let chatProvider = Chat.chatProvider
chatProvider.setDepartment("Department Name")
Sending events
Chat SDK v1 allowed you to send events through the ZDCChatAPI
instance. With Chat SDK v2, these events are grouped together with similar APIs under the providers.
Provider | Description |
---|---|
ChatProvider | For APIs related to the chat session. |
ProfileProvider | For APIs related to the visitor. |
PushNotificationsProvider | For APIs related to Push. |
ConnectionProvider | For APIs related to the connection. |
SettingsProvider | For APIs related to the Chat dashboard settings. |
Every event that can be sent can take an optional completion closure.
The closure provides a Result<Success, Error>
return to handle the result of the request.
Before
ZDCChatAPI.instance().sendChatMessage(message)
ZDCChatAPI.instance().uploadFile(with: data, name: fileName)
ZDCChatAPI.instance().endChat()
ZDCChatAPI.instance().setNote(note)
ZDCChatAPI.instance().setPushToken(data)
After
let chatProvider = Chat.chatProvider
// Optional completion handler
chatProvider?.sendMessage(message)
chatProvider?.sendFile(url: fileURL,
onProgress: { (progress) in },
completion: { (result) in } )
chatProvider?.endChat { (result) in
switch result {
case .success:
break // Chat ended
case .failure(let error):
break // Handle error
}
}
Chat.profileProvider?.setNote(note) { _ in }
Chat.pushNotificationsProvider?.registerPushToken(data)
Observing events
Chat v1 leveraged NSNotificationCenter to emit events and handle the subscription of events. Chat v2 implements event observers through the observable pattern.
Subscribing to events
Before
ZDCChatAPI.instance().addObserver(self, forConnectionEvents: #selector(onConnectionStateUpdated))
ZDCChatAPI.instance().addObserver(self, forChatLogEvents: #selector(chatLogEvents))
ZDCChatAPI.instance().addObserver(self, forAgentEvents: #selector(onAgentEvent))
ZDCChatAPI.instance().addObserver(self, forUploadEvents: #selector(chatUploadEvent))
ZDCChatAPI.instance().addObserver(self, forAccountEvents: #selector(chatAccountEvent))
After
let stateToken = Chat.chatProvider?.observeChatState { (state) in
// Handle logs, agent events, queue position changes and other events
}
let connectionToken = Chat.connectionProvider?.observeConnectionState { (connection) in
// Handle connection status changes
}
let accountToken = Chat.chatProvider?.observeAccount { account in
// Handle department and account status changes
}
let settingsToken = Chat.settingsProvider?.observeChatSettings { settings in
// Handle changes to Chat settings
}
var tokens: [ObservationToken?] = [stateToken, connectionToken, accountToken, settingsToken]
Unsubscribing from events
Before
ZDCChatAPI.instance().removeObserver(forConnectionEvents: self)
ZDCChatAPI.instance().removeObserver(forAgentEvents: self)
ZDCChatAPI.instance().removeObserver(forChatLogEvents: self)
ZDCChatAPI.instance().removeObserver(forUploadEvents: self)
ZDCChatAPI.instance().removeObserver(forAccountEvents: self)
After
tokens.forEach { $0.cancel() }
Conflicting Names CommonUISDK.Framework
If you are using CocoaPods you may get a "conflicting names commonuisdk.framework" error if you are also using the Support SDK. You can fix this by updating the Support SDK. Follow the Support SDK migration guide, and ensure that you are using the ZendeskSupportSDK
pod, and not the deprecated ZendeskSDK
pod.
Bot-centered conversational experience
The Chat SDK leverages the Unified SDK to present chat features to the user in a conversational flow. Pre-chat forms, offline forms, and customer satisfaction requests are all sent to the user through a chat bot. Though the bot resembles Answer Bot, it's not. See Configuring the chat bot.