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.