DocumentationAPI Reference

Migrating from 7.x to 8.0.0

Migrating from 7.x to 8.0.0

Set Application minimum deployment target to iOS 12.0 or higher

iOS minimum deployment target is increased from iOS 11.0 to iOS 12.0.

Migrating from 6.x to 7.0.0

Update Dependencies

In order to enable compatibility with the Zendesk SDKs, the Messaging SDK and Zendesk Core SDK have updated Objective-C headers. Because they are dependencies of the Support SDK they must be updated to Messaging SDK version 5.0.0 and Core SDK 4.0.0.

Updated Objective-C Headers

As part of enabling compatibility with the Zendesk SDKs in order to allow an easier migration between the Classic SDKs and the Zendesk SDKs, Objective-C headers on the Messaging SDK and Zendesk Core SDK have been updated.

The following is a list of the updated headers:

Messaging SDK

  • ZDKMessaging is renamed to ZDKClassicMessaging.
  • ZDKMessagingConfiguration is renamed to ZDKClassicMessagingConfiguration.
  • ZDKMessagingDelegate is renamed to ZDKClassicMessagingDelegate.
  • ZDKMessagingUIEvent is renamed to ZDKClassicMessagingUIEvent.

Zendesk Core SDK

  • ZDKZendesk is renamed to ZDKClassicZendesk.
  • ZDKPushProvider is renamed to ZDKClassicPushProvider.
  • ZDKUserProvider is renamed to ZDKClassicUserProvider.
  • ZDKCoreLogger is renamed to ZDKClassicCoreLogger.
  • ZDKLogLevel is renamed to ZDKClassicLogLevel.
  • ZDKUser is renamed to ZDKClassicUser.
  • ZDKUserField is renamed to ZDKClassicUserField.
  • ZDKUserFieldOption is renamed to ZDKClassicUserFieldOption.
  • ZDKIdentityType is renamed to ZDKClassicIdentityType.
  • ZDKHelpCenterUtil is renamed to ZDKClassicHelpCenterUtil.

Migrating from 5.x to 6.0.0

Set Application minimum deployment target to iOS 11.0 or higher

iOS minimum deployment target is increased from iOS 10.0 to iOS 11.0.

Replace .framework with .xcframework for manual integration

Version 6.0.0 doesn't support Fat Framework format modules for any integration method.

Migrating from 4.x to 5.0.0

Add new dependencies

The framework now has some additional dependencies. Integrations of the Support SDK must include the MessagingSDK, MessagingAPI, and SDKConfigurations frameworks as dependencies of your Xcode project.

Update import statements for ZendeskSDK and ZendeskProviderSDK

The ZendeskSDK has been renamed to SupportSDK. The ZendeskProviderSDK has been renamed to SupportProvidersSDK. This means that anywhere in your code you have imported the ZendeskSDK or the ZendeskProviderSDK will need to be updated.

Replace UiConfiguration with Configuration

The UiConfiguration protocol has been renamed to Configuration. This means that anywhere in your code you are using UiConfiguration will need to be updated.

Replace SupportUI with Support

The SupportUI singleton has been deprecated. Use the Support singleton instead.

Replace deflectionEnabled in ArticleUiConfiguration and HelpCenterUiConfiguration with engines or objcEngines

The deflectionEnabled property of the ArticleUiConfiguration and the HelpCenterUiConfiguration classes has been replaced with engines (for Swift) and objcEngines (for Objective-C) properties.

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 ZendeskSDKimport 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 ZendeskSDKimport 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 ZendeskProviderSDKimport 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 = 123456789123let 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 }