Migrating from 3.x to 4.0

Update the way you create custom fields

A CustomField class written in Swift replaces ZDKCustomField class written in Objective-C.

The initializer has changed. The new initialization snippet is as follows:

Swift

let customFieldOne = CustomField(fieldId: 2345678, value: "some_text")

Objective-C

ZDKCustomField *customFieldOne = [[ZDKCustomField alloc] initWithFieldId:@(2345678) value:@"some_text"];

You can also initialize custom fields using a dictionary:

Swift

let customFieldOne = CustomField(dictionary: ["id": 2345678, "value": "some_text"])

Objective-C

ZDKCustomField *customFieldOne = [[ZDKCustomField alloc] initWithDictionary:@{@"id": @(2345678), @"value" : @"some_text"}];

For more information, see Working with API providers

Update the way you set and get custom fields

  • the customTicketFields property in ZDKCreateRequest class has been renamed to customFields
  • the fields property in RequestUiConfiguration has been renamed to customFields
  • Custom fields are now available as the customFields property of the ZDKRequest class.

Migrating from 2.x to 3.0

Updating your application dependencies

Version 3.0.0 of the Support SDK has a new dependency called CommonUISDK. The ZendeskSDK module directly depends on it so you will need to have it in the "Embedded Binaries" Build Phase of your application target.

Update your initialization call

If using the Support SDK UI in your app, you need to use the new UI singleton to initialize. This will replace the old initialization snippet for integrations that use the Support UI. If you are using the Support SDK API providers rather than the UI, then your initialization snippet remains unchanged.

The new initialization snippet is:

Swift

import ZendeskSDK
import ZendeskCoreSDK

Zendesk.initialize(appId: "appId", clientId: "clientId", zendeskUrl: "url")
SupportUI.initialize(withZendesk: Zendesk.instance)

Objective-C

#import <ZendeskSDK/ZendeskSDK.h>;
#import <ZendeskCoreSDK/ZendeskCoreSDK.h>;
#import <ZendeskSDK/ZendeskSDK-Swift.h>;
#import <ZendeskCoreSDK/ZendeskCoreSDK-Swift.h>;

[ZDKZendesk initializeWithAppId:@"appId" clientId:@"clientId" zendeskUrl:@"url"];
[ZDKSupportUI initializeWithZendesk:[ZDKZendesk instance]];

Import CommonUISDK when using UiConfiguration

Now when using the UiConfiguration class, the CommonUISDK will need to be imported for it to be available.

Update your theming code

There is a new method of theming in Support SDK. It works the same way as the old API where you supply one primary color which we use to theme the UI. The new API looks like:

Swift

import CommonUISDK

CommonTheme.currentTheme.primaryColor = .red

Objective-C

#import <CommonUISDK/CommonUISDK-Swift.h>;

[ZDKCommonTheme currentTheme].primaryColor = [UIColor redColor];

Migrating from 1.x to 2.0

This page covers the key changes you'll need to make to your app to upgrade from a 1.x version of the Support SDK to 2.0.

Update the framework

SDK 2.0 is a mixed framework written in Objective-C and Swift 4. As such the integration instructions differ from SDK 1.0, which was fully written in Objective-C. We have also split the SDK into three separate frameworks: ZendeskSDK contains the UI, ZendeskProviderSDK contains the REST API wrappers, and ZendeskCoreSDK contains the user management and networking.

Please follow Adding the Support SDK to add the SDK to your project. There are separate instructions for integrating into a pure Objective-C project and a project containing Swift.

You may have to remove ZendeskSDK.bundle from Copy Bundle Resources in your projects Build Phases.

Update the initialization call

Previously, you initialized the SDK using the ZDKConfig singleton. In 2.0, we have split out the responsibilities of the SDK into two separate enum singletons that must both be initialized separately. Initialize the Zendesk enum singleton with your account details first, and then initialize the Support enum singleton as follows:

Swift

import ZendeskSDK
import ZendeskCoreSDK

Zendesk.initialize(appId: "appId", clientId: "clientId", zendeskUrl: "url")
Support.initialize(withZendesk: Zendesk.instance)

Objective-C

#import <ZendeskSDK/ZendeskSDK-Swift.h>;
#import <ZendeskCoreSDK/ZendeskCoreSDK-Swift.h>;

[ZDKZendesk initializeWithAppId:@"appId" clientId:@"clientId" zendeskUrl:@"url"];
[ZDKSupport initializeWithZendesk:[ZDKZendesk instance]];

For more information, see Initializing the Support SDK. Please note the order of the arguments has changed from 1.x.

Update the identity

The mechanism for setting an identity is unchanged in 2.0, but the identity classes have moved, and the setIdentity method is on Zendesk rather than the old ZDKConfig.

Setting an anonymous identity:

Swift

let identity = Identity.createAnonymous()
Zendesk.instance?.setIdentity(identity)

Objective-C

id<ZDKObjCIdentity> userIdentity = [[ZDKObjCAnonymous alloc] initWithName:nil email:nil];
[[ZDKZendesk instance] setIdentity:userIdentity];

Setting a JWT identity:

Swift

let identity = Identity.createJwt(token: "unique_id")
Zendesk.instance?.setIdentity(identity)

Objective-C

id<ZDKObjCIdentity> userIdentity = [[ZDKObjCJwt alloc] initWithToken:"unique_id"];
[[ZDKZendesk instance] setIdentity:userIdentity];

For more information, see Setting an identity.

Update the way you start SDK View Controllers

We have changed how the SDK is presented in 2.0. Now a UIViewController is returned for you to present as you see fit. All previous methods for starting our controllers should be replaced, as detailed in Configuring the SDK activities.

Note The Rate My App feature that was in SDK v2 has been deprecated and removed. To continue using the feature, consider using our open source replacement.

Add iCloud permissions

If you wish for your users to attach files to support requests, you must enable iCloud Documents in your app's Capabilities. Users can still upload photos from their photo library or camera as long as the usage descriptions in the info.plist are updated.

Update the provider references

All our provider classes have changed. They no longer take any arguments.

import ZendeskProviderSDK
import ZendeskCoreSDK

let requestProvider = ZDKRequestProvider()

let helpCenterProvider = ZDKHelpCenterProvider()
@ import ZendeskSDK;
@ import ZendeskCoreSDK;

[[ZDKRequestProvider alloc] init];

[[ZDKHelpCenterProvider alloc] init];
Note on 2.0.0 to 2.0.2

In 2.0.0 ZDKHelpCenterProvider required a Zendesk instance to be passed on init. This is no longer the case.

Update push notification handling and deep-linking

If you previously used the ZDKPushUtil methods to handle in coming push notifications, it has been replaced. The new method is a more "hands off" approach to handling incoming pushes. You should now call the following method when a push notification is received and pass it the request ID from the push payload.

Support.instance?.refreshRequest(requestId:"request_id")
[[ZDKSupport instance] refreshRequestWithRequestId:@"request_id"];

This method will not handled any deeplinking to the ticket screen. It will just reload the relevant screens (RequestListViewController and RequestViewController) if an end-user is on them. DeepLinking to the RequestViewController with a request ID should be handled by you.

This can be done like so:

let requestVC = ZDKRequestUi.buildRequestUiWithRequestId:@"request_id"];
UIViewController *requestVC = [ZDKRequestUi buildRequestUiWithRequestId:@"request_id"];

Where to next?

Now that you've completed these steps, your app should be building and running with version 2.0 of the Support SDK. To take advantage of the latest features, try out our new configuration options.

Migrating for 2.0.0 to 2.0.2

2.0.0 shipped with a number of Int types in the public APIs. This was a mistake as they can overflow on 32-bit devices. In order to fix this we have had to break several APIs. If your integration uses only the SDK UI the impact should be minimal. If you make use of the providers you will need to update your project.

Zendesk IDs, like ticket, category, section, and article IDs are 64-bit. On 32-bit devices you need to wrap literal integers into an NSNumber like this:

let doubleValue: Double = 123456789123
let doubleValueNumber: NSNumber = NSNumber(value: doubleValue)

Presenting the Help Center UI

We have removed all Int types from our APIs. This impacts the HelpCenterUiConfiguration.groupdIds property and ZDKHelpCenterUi.buildHelpCenterArticle(withArticleId: ) function.

HelpCenterUiConfiguration.groupdIds has been changed to an NSNumber.

ZDKHelpCenterUi.buildHelpCenterArticle(withArticleId: ) has been changed to take a String.

Using the Help Center Providers

All NSInteger types have been changed to NSString types. This reverts them back to they way they worked in SDK 1.X. As a type change only emits a warning in Objective-C we have had to change the signatures in order to force an error and ensure correct behaviour.

Initializing ZDKHelpCenterProvider:
let helpCenterProvider = ZDKHelpCenterProvider(locale: "en")!

Becomes:

let helpCenterProvider = ZDKHelpCenterProvider()
getSectionsForCategoryId:
helpCenterProvider.getSectionsForCategoryId(200183938) { (result, _) in }

Becomes:

helpCenterProvider.getSectionsWithCategoryId("200183938", withCallback: { (result, _) in })
getArticlesForSectionId:
helpCenterProvider.getArticlesForSectionId(200549778, withCallback: { (result, _) in })

Becomes:

helpCenterProvider.getArticlesWithSectionId("200549778", withCallback: { (result, _) in })
getArticlesWithLabels:
helpCenterProvider.getArticlesForSectionId(200549778, labels: ["ios"]) { (result, _) in }

Becomes:

helpCenterProvider.getArticlesWithSectionId("200549778", labels: ["ios"]) { (result, _) in }
getAttachmentForArticleId:
helpCenterProvider.getAttachmentForArticleId(203296726) { (result, _) in }

Becomes:

helpCenterProvider.getAttachmentWithArticleId("203296726", withCallback: { (result, _) in })}
getArticleById:
helpCenterProvider.getArticleById(203296726) { (result, _) in }

Becomes:

helpCenterProvider.getArticleWithId("203296726") { (result, _) in }
getSectionById:
helpCenterProvider.getSectionById(200549778) { (result, _) in }

Becomes:

helpCenterProvider.getSectionWithId("200549778") { (result, _) in }
getCategoryById:
helpCenterProvider.getCategoryById(200183938) { (result, _) in }

Becomes:

helpCenterProvider.getCategoryWithId("200183938") { (result, _) in }
upvoteArticle:
helpCenterProvider.upvoteArticle(withId: 203296726) { (result, _) in }

Becomes:

helpCenterProvider.upVoteArticle(withId: "203196726") { (result, _) in }
downvoteArticle:
helpCenterProvider.downvoteArticle(withId: 203296726) { (result, _) in }

Becomes:

helpCenterProvider.downVoteArticle(withId: "203296726") { (result, _) in }
deleteVote:
helpCenterProvider.deleteVote(withId: 203296726) { (result, _) in }

Becomes:

helpCenterProvider.removeVote(withId: "203196726") { (result, _) in }