Write custom code using API providers

This is the developer guide for the Support SDK v1 for iOS. For Support SDK v2, see Support SDK v2 iOS.

API providers allow you to use all the features of the Support SDK without the UI. They let you interact with Zendesk Support on behalf of an end-user.

Before you start

Before you start, the following information is useful to know:

  • All API providers assume that you have correctly initialized ZDKConfig, including a valid identity.
  • You can use the following API providers:
    • ZDKRequestProvider
      • Used to fetch a list of requests and to create new requests
      • Used to fetch a list of comments for a given request and to add additional comments
    • ZDKHelpCenterProvider
      • Used to fetch categories, sections, and articles
      • Used to search for articles
      • Used to vote on articles
    • ZDKUploadProvider
      • Used to upload attachments
      • Used to delete attachments
    • ZDKUserProvider
      • Used to add or remove end-user tags
      • Used to set user-fields to an end-user
    • ZDKPushRegistrationProvider
      • Used to register and unregister clients for push notifications
      • Supports webhook and Urban Airship
  • API providers return a result asynchronously through a callback provided in a request.
  • Each callback block contains an NSError parameter that is nil for successful API requests.

A note on initialization

Your code might load your ApplicationDelegate (initialization code) and your ViewController (provider logic) at the same time. In this case the SDK might not have a chance to initialize correctly. If you encounter this issue, then you can rectify it by declaring property-level provider instances as lazy.

lazy var provider = ZDKHelpCenterProvider()

View API provider documentation in Xcode

You can view all API provider documentation in Xcode by using the open quickly command (shift+command+O) and typing the name of the API provider that you are interested in:

  • ZDKRequestProvider.h
  • ZDKHelpCenterProvider.h
  • ZDKUploadProvider.h
  • ZDKAvatarProvider.h
  • ZDKPushRegistrationProvider.h
  • ZDKUserProvider.h

ZDKRequestProvider

Create a ZDKRequestProvider as follows:

Swift 3

let provider = ZDKRequestProvider()

Objective-C

ZDKRequestProvider *provider = [ZDKRequestProvider new];
Create a support request

After creating a ZDKRequestProvider provider, you can use the provider's createRequest method to create a request.

Swift 3

var request = ZDKCreateRequest()
request.subject = "My printer is on fire!"
request.requestDescription = "The smoke is very colorful."
request.tags = ["printer", "fire"]

provider.createRequest(request) { result, error in
}

Objective-C

ZDKCreateRequest *request = [ZDKCreateRequest new];

request.subject = @"My printer is on fire!";
request.requestDescription = @"The smoke is very colorful.";
request.tags = @[@"printer", @"fire"];

[provider createRequest:request withCallback:^(id result, NSError *error) {

    if (error) {
        // Handle the error

        // Log the error
        [ZDKLogger e:@"Something went wrong"];

    } else {
        // Handle the success
    }
}];
Create a request with an attachment

You can use the provider's createRequest method to create a request with an attachment.

In the following example, replace UploadResponse with a ZDKUploadResponse retrieved with the uploadAttachment method of the ZDKUploadProvider.

Swift 3

var request = ZDKCreateRequest()
request.attachments = UploadResponse
request.subject = "My printer is on fire!"
request.requestDescription = "The smoke is very colorful."

provider.createRequest(request) { result, error in
}

Objective-C

ZDKCreateRequest *request = [ZDKCreateRequest new];

request.attachments = @[UploadResponse];

request.subject = @"Ticket subject";
request.requestDescription = @"Ticket description";

[provider createRequest:request withCallback:^(id result, NSError *error) {

    if (error) {
        // Handle the error

        // Log the error
        [ZDKLogger e:@"Something went wrong"];

    } else {
        // Handle the success
    }
}];
Sending additional data in a request

You can send additional data in a request using custom fields.

Using custom fields and custom forms

The ZDKConfig class has a customTicketFields array property that you can use to set the values of custom fields in requests. The actual custom fields are created in the Zendesk Support admin interface. Each custom field has an ID that's displayed when an admin views the field in the Zendesk Support admin interface. You'll need this ID to use it in the Support SDK. Custom fields must be visible and editable for end-users to work with the Support SDK.

Here's an example of setting a custom field:

Swift 3

let customeFieldOne = ZDKCustomField(fieldId: 1234567, andValue: "3")
let customeFieldTwo = ZDKCustomField(fieldId: 2345678, andValue: "Some text")

ZDKConfig.instance().customTicketFields = [customeFieldOne, customeFieldTwo]

Objective-C

ZDKCustomField *customeFieldOne = [[ZDKCustomField alloc] initWithFieldId:@(1234567) andValue:@"3"];
ZDKCustomField *customeFieldTwo = [[ZDKCustomField alloc] initWithFieldId:@(2345678) andValue:@"Some text"];

[ZDKConfig instance].customTicketFields = @[customeFieldOne, customeFieldTwo];

If your Zendesk Support instance supports custom forms, you can specify the form that will be shown with the ticketFormId property in the ZDKConfig class. Here's an example:

Swift 3

ZDKConfig.instance().ticketFormId = 1333

Objective-C

[ZDKConfig instance].ticketFormId = @(1333);

ZDKHelpCenterProvider

Using the ZDKHelpCenterProvider is very similar to using the ZDKRequestProvider. You can call the following methods from the list at ZDKHelpCenterProvider.

ZDKUploadProvider

Using the ZDKUploadProvider is very similar to using the ZDKRequestProvider. You can call the following methods from the list at ZDKUploadProvider.

ZDKUserProvider

Using the ZDKUserProvider is very similar to using the ZDKRequestProvider. You can call the following methods from the list at ZDKUserProvider.

ZDKPushRegistrationProvider

Using the ZDKPushRegistrationProvider is very similar to using the ZDKRequestProvider. You can call the following methods from the list at ZDKPushRegistrationProvider.