Migrating ZDCChat SDK to version 1.3.1.1
This is the developer guide for Chat SDK v1. The new Chat SDK v2 for iOS is now available and is the recommended version to integrate Chat into your mobile app. It also removes the dependency on UIWebView which has been deprecated by Apple.
- If your app targets iOS 10, you need
NSPhotoLibraryUsageDescription
to be set in your applicationinfo.plist
. This key specifies the reason for your app to access the user’s photo library. Read more from NSPhotoLibraryUsageDescription section on apple docs.
Migrating ZDCChat SDK to version 1.3
In ZDCChat version 1.3, we split the ZDCChat into two SDKs:
- ZDCChatAPI includes everything needed to integrate Zendesk Chat with a custom UI
- ZDCChat contains the "out-of-the-box" UI that's built on ZDCChatAPI
Below is a list of the most important updates.
Initializing ZDCChat
The way you initialize the ZDCChat SDK has changed. Instead of using +[ZDCChat configure:]
to initialize the SDK, use +[ZDCChat initializeWithAccountKey:]
.
Prior to ZDCChat 1.3:
Objective-C
[ZDCChat configure:^(ZDCConfig *config) { config.accountKey = @"your_account_key"; }];
Swift
ZDCChat.configure {config in
config.accountKey = "your_account_key"
}
ZDCChat 1.3:
Objective-C
[ZDCChat initializeWithAccountKey:@"your_account_key"];
Swift
ZDCChat.initializeWithAccountKey("your_account_key")
The configuration that were set using +[ZDCChat configure:]
prior to 1.3 have to be set now using +[ZDCChat startChat:]
or +[ZDCChat startChatIn:withConfig:]
:
Prior to ZDCChat 1.3:
Objective-C
[ZDCChat configure:^(ZDCConfig *config) { config.accountKey = @"your_account_key"; config.department = @"Billing"; config.tags = @[@"subscription", @"mobile_app"]; config.preChatDataRequirements.email = ZDCPreChatDataRequired; }];
Swift
ZDCChat.configure {config in
config.accountKey = "your_account_key"
config.department = "Billing"
config.tags = ["subscription", "mobile_app"]
config.preChatDataRequirements.email = ZDCPreChatDataRequired
}
ZDCChat 1.3:
Objective-C
[ZDCChat startChat:^(ZDCConfig *config) {
config.department = @"Billing";
config.tags = @[@"subscription", @"mobile_app"];
config.preChatDataRequirements.email = ZDCPreChatDataRequired;
}];
Swift
ZDCChat.startChat{config in
config.department = "Billing"
config.tags = ["subscription", "mobile_app"]
config.preChatDataRequirements.email = ZDCPreChatDataRequired
}
Accessing Chat API from ZDCChat
If you want to use functionality from ZDCChatAPI while still using the UI provided in ZDCChat, use the api
property of ZDCChat
.
Prior to ZDCChat 1.3:
Objective-C
[[ZDCChat instance].session sendChatMessage:@"Hello"];
Swift
ZDCChat.instance().session.sendChatMessage("Hello")
ZDCChat 1.3:
Objective-C
[[ZDCChat instance].api sendChatMessage:@"Hello"];
Swift
ZDCChat.instance().api.sendChatMessage("Hello")
The api
property of ZDCChat
is an instance of ZDCChatAPI
which exposes all the Chat API methods.
ZDCChatSession removed in favor of ZDCChatAPI
ZDCChatSession
has been removed from ZDCChat in favor of ZDCChatAPI.
The following chat session classes have been removed:
- ZDCChatSession
- ZDCChatIO
- ZDCChatDataSource
- ZDCChatDataNode
- ZDCJSWidgetIO
- ZDCMessageMonitor
- ZDCSessionConfig
- ZDCSessionStateManager
ZDCChatAPI
provides a single entry point to all the chat API functionality. Below is a list of common API features and how to migrate to ZDCChatAPI
. In addition, we updated the Chat API document with the newly added ZDCChatAPI
. Please refer to it for further information.
Configuring and starting a chat
Prior to ZDCChat 1.3:
Objective-C
[ZDCChat configure:^(ZDCConfig *config) {
config.accountKey = @"your_account_key";
}];
[[ZDCChat instance].session connectWithConfig:configOrNil];
Swift
ZDCChat.configure { config in
config.accountKey = "your_account_key"
}
ZDCChat.instance().session.connectWithConfig(configOrNil)
ZDCChat 1.3:
Objective-C
[[ZDCChatAPI instance] startChatWithAccountKey:@"your_account_key" config:configOrNil];
Swift
ZDCChatAPI.instance().startChatWithAccountKey("your_account_key", config: configOrNil)
Listening for events
Prior to ZDCChat 1.3:
Objective-C
// Connection Events
[[ZDCChat instance].session addObserver:self forConnectionEvents:@selector(connectionStateUpdated)];
[[ZDCChat instance].session addObserver:self forTimeoutEvents:@selector(sessionTimeout)];
// Chat Events
[[ZDCChat instance].session.dataSource addObserver:self forChatLogEvents:@selector(chatEvent:)];
[[ZDCChat instance].session.dataSource addObserver:self forAgentEvents:@selector(agentEvent:)];
// and remember to remove the observer before deallocation
// Connection Events
[[ZDCChat instance].session removeObserverForConnectionEvents:self];
[[ZDCChat instance].session removeObserverForTimeoutEvents:self];
// Chat Events
[[ZDCChat instance].session.dataSource removeObserverForChatLogEvents:self];
[[ZDCChat instance].session.dataSource removeObserverForAgentEvents:self];
Swift
// Connection Events
ZDCChat.instance().session.addObserver(self, forTimeoutEvents: #selector(onSessionTimeout))
ZDCChat.instance().session.addObserver(self, forConnectionEvents: #selector(onConnectionStateUpdated))
// Chat Events
ZDCChat.instance().session.dataSource().addObserver(self, forChatLogEvents: #selector(onChatEvent))
ZDCChat.instance().session.dataSource().addObserver(self, forAgentEvents: #selector(onAgentEvent))
// and remember to remove the observer before deallocation
// Connection Events
ZDCChat.instance().session.removeObserverForConnectionEvents(self)
ZDCChat.instance().session.removeObserverForTimeoutEvents(self)
// Chat Events
ZDCChat.instance().session.dataSource().removeObserverForChatLogEvents(self)
ZDCChat.instance().session.dataSource().removeObserverForAgentEvents(self)
ZDCChat 1.3:
Objective-C
// Connection Events
[[ZDCChatAPI instance] addObserver:self forConnectionEvents:@selector(connectionStateUpdated)];
[[ZDCChatAPI instance] addObserver:self forTimeoutEvents:@selector(sessionTimeout)];
// Chat Events
[[ZDCChatAPI instance] addObserver:self forChatLogEvents:@selector(chatEvent:)];
[[ZDCChatAPI instance] addObserver:self forAgentEvents:@selector(agentEvent:)];
// and remember to remove the observer before deallocation
// Connection Events
[[ZDCChatAPI instance] removeObserverForConnectionEvents:self];
[[ZDCChatAPI instance] removeObserverForTimeoutEvents:self];
// Chat Events
[[ZDCChatAPI instance] removeObserverForChatLogEvents:self];
[[ZDCChatAPI instance] removeObserverForAgentEvents:self];
Swift
// Connection Events
ZDCChatAPI.instance().addObserver(self, forTimeoutEvents: #selector(onSessionTimeout))
ZDCChatAPI.instance().addObserver(self, forConnectionEvents: #selector(onConnectionStateUpdated))
// Chat Events
ZDCChatAPI.instance().addObserver(self, forChatLogEvents: #selector(onChatEvent))
ZDCChatAPI.instance().addObserver(self, forAgentEvents: #selector(onAgentEvent))
// and remember to remove the observer before deallocation
// Connection Events
ZDCChatAPI.instance().removeObserverForConnectionEvents(self)
ZDCChatAPI.instance().removeObserverForTimeoutEvents(self)
// Chat Events
ZDCChatAPI.instance().removeObserverForChatLogEvents(self)
ZDCChatAPI.instance().removeObserverForAgentEvents(self)
Getting the connection status
Prior to ZDCChat 1.3:
Objective-C
ZDCConnectionStatus status = [[ZDCChat instance].session connectionStatus];
Swift
let status = ZDCChat.instance().session.connectionStatus()
ZDCChat 1.3:
Objective-C
ZDCConnectionStatus status = [[ZDCChatAPI instance] connectionStatus];
Swift
let status = ZDCChatAPI.instance().connectionStatus
Getting a list of agents
Prior to ZDCChat 1.3:
Objective-C
NSDictionary *agents = [[ZDCChat instance].session.dataSource agents];
Swift
let agents = ZDCChat.instance().session.dataSource().agents()
ZDCChat 1.3:
Objective-C
NSDictionary *agents = [[ZDCChatAPI instance] agents];
Swift
let agents = ZDCChatAPI.instance().agents
Getting the chat log
Prior to ZDCChat 1.3:
Objective-C
NSArray *events = [[ZDCChat instance].session.dataSource livechatLog];
Swift
let events = ZDCChat.instance().session.dataSource().livechatLog()
ZDCChat 1.3:
Objective-C
NSArray *events = [[ZDCChatAPI instance] livechatLog];
Swift
let events = ZDCChatAPI.instance().livechatLog
Sending a message
Prior to ZDCChat 1.3:
Objective-C
[[ZDCChat instance].session sendChatMessage:@"A message"];
Swift
ZDCChat.instance().session.sendChatMessage("A message")
ZDCChat 1.3:
Objective-C
[[ZDCChatAPI instance] sendChatMessage:@"A message"];
Swift
ZDCChatAPI.instance().sendChatMessage("A message")
Ending a chat
Prior to ZDCChat 1.3:
Objective-C
[[ZDCChat instance].session endChat];
Swift
ZDCChat.instance().session.endChat()
ZDCChat 1.3:
Objective-C
[[ZDCChatAPI instance] endChat];
Swift
ZDCChatAPI.instance().endChat()
Removed some internal classes
Some of our internal classes were exposed in the framework. These classes have been removed:
- ZDCBundleUtils
- ZDCChatConstants
- ZDCDeviceInfo
- ZDCMobileProvisionAnalyzer
- ZDCReachability
- ZDUUtil