- Chat SDK v1 for iOS

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 application info.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