This hands-on tutorial shows you how to build a functioning iOS application in 30 minutes that lets users access your Help Center directly from the mobile app. The app also lets users submit support requests to your agents in Zendesk Support.

The tutorial uses the Support SDK for iOS, a shared code library that lets you easily incorporate different Zendesk customer support features in iOS applications.

Zendesk gives you other options for providing customer support in mobile apps:

  • You can use the Chat SDK to let users chat with support agents. To learn how, see Quick start - Chat SDK for iOS.
  • You can use the Messaging SDK to incorporate Answer Bot with Support to create a unified messaging experience. However, because Answer Bot is available only as an add-on with the Zendesk Suite Professional plan or above, the Messaging SDK is not used in this tutorial.

You need macOS and Xcode to build iOS applications. You can download Xcode from the Apple Developer website or from the Mac App Store.

You'll also need a Zendesk Support account or a trial account. You can request a sponsored test account that doesn't expire after 14 days like the trial account.

Make sure Help Center is enabled in your Zendesk Support account. See Getting started with Guide in the Zendesk Support Help Center.

Though this quick start guide provides step-by-step instructions to build a simple application, it's not an iOS app tutorial, If you're new to iOS development, I highly recommend working through the lessons in Start Developing iOS Apps (Swift) on the Apple website.

The guide walks you through the following basic steps for adding Zendesk Support features to an iOS application:

The tutorial uses version 5.0.1 of the Support SDK. It was tested in version 11.3.1 of Xcode.

Disclaimer: Zendesk provides this article for instructional purposes only. Zendesk can't provide support for third-party technologies such as Swift, iOS, and Xcode. Please post any issue in the comments section below or in the Zendesk SDKs community, or search for a solution online.

Creating a sample project

This section shows you how to create a quick sample project in Xcode. You'll use the project to try out the Support SDK.

  1. In Xcode, select File > New > Project.

    If you're at the Welcome to Xcode window, choose the second task, Create a new Xcode project.

  2. Make sure iOS is selected on the top bar, select Tabbed App, and click Next.

    This creates an app with a tab bar at the bottom of the home screen. Later you'll use the second tab to provide support to users.

  3. Set the following options for the project:

    • Product Name - Enter My Sample App or something similar
    • Organization Name - (required) Enter something like Sample
    • Organization Identifier - (required) Enter something like com.sample
    • Language - Select Swift
    • User Interface - Select Storyboard (not the default SwiftUI)
  4. Click Next, choose where you want to save the project, and click Create.

Xcode creates all the files and basic settings for your project. You can view the files in the Project navigator on the left side of the screen. If you don't see the files, click the first icon (the folder icon) on the upper side of the panel.

Adding the Support SDK with CocoaPods

CocoaPods is a dependency manager that lets you add third-party frameworks and libraries to projects.

Step 1 - Install CocoaPods

If not already done, install CocoaPods by running the following command in Terminal:

$ sudo gem install cocoapods

See Getting started on the CocoaPods site.

Step 2 - Create a Podfile

A Podfile specifies the dependencies of an Xcode project. The file is simply named Podfile with no file extension.

To create a Podfile

  1. In Terminal, navigate to the top-level folder of your project (the one with the .xcodeproj file).
  2. Create a Podfile with the following command:

    $ pod init

  3. Open the file in Xcode with the following command:

    $ open -a Xcode Podfile

    The content should look as follows:

    # Uncomment the next line to define a global platform for your project# platform :ios, '9.0'
    target 'My Sample Support App' do    # Comment the next line if you don't want to use dynamic frameworks    use_frameworks!
        # Pods for My Sample Support App
    end
  4. Add pod 'ZendeskSupportSDK' to the do block:

    target 'My Sample App' do  ...  pod 'ZendeskSupportSDK'end
  5. Save the Podfile.

Step 3 - Adding the SDK in your project

  1. If you installed the 'ZendeskSupportSDK' pod in your project directory for a previous version of the Support SDK, run the following command first:

    $ pod update ZendeskSupportSDK

    CocoaPods updates the SDK pod on your system.

    Skip this step if you never added the Support SDK in the project directory with CocoaPods before.

  2. Run the following command:

    $ pod install

    CocoaPods adds the latest version of the SDK to your project.

  3. Close your project in Xcode, then reopen it by double-clicking the .xcworkspace file located in the project's root folder.

Important: Because your project now contains a dependency managed by CocoaPods, from now on you must open the project in Xcode by double-clicking the .xcworkspace file.

Running a test build

Before going any further, make sure you successfully added the Support SDK to your project. One way is to run a test build. The application doesn't do much yet, but if you don't get any build errors you know you're on the right path.

You can use the Simulator app that’s included in Xcode to run your application. As the name implies, Simulator simulates running an iOS app on your Mac.

  1. Make sure you opened the project by double-clicking the .xcworkspace file in the project's root folder (see Adding the Support SDK with CocoaPods).
  2. In the Scheme pop-up menu on the Xcode toolbar, choose iPhone 11.

  3. Click the Run button (the play icon) on the left side of the Xcode toolbar.

    Xcode displays messages about the build process in the middle of the toolbar.

    Simulator starts automatically after the build is finished. Look for it on the Dock. Be patient. Simulator can take a while to get going the first time it starts. It's much faster with subsequent builds.

    Eventually, the application opens in Simulator:

Consider the test a success if you don't get any build errors. You might get some build warnings but you can ignore them for now. If you want, you can click the tabs to test that the basic tabbed interface works.

Initializing the Support SDK

Before a user can use any Zendesk feature on their device, the application has to initialize the Zendesk product SDKs you want to use. The initialization process involves setting initial values and performing other setup tasks.

In this section, you'll update the sample application to initialize the Support SDK dependencies and make them ready for use. The task consists of the following steps:

Getting the initialization code from your Zendesk Support account

You get the initialization code from your Zendesk Support admin interface. The code is generated when an Zendesk Support admin registers a mobile app in Zendesk Support.

You'll need to sign in as a Zendesk Support admin, or ask an admin to complete the following steps for you.

  1. In the Zendesk Support agent interface, click the Admin icon () in the sidebar, then select Channels > Mobile SDK.
  2. Click Add app.
  3. In the Setup tab, enter a name for your app.

    The name is for your reference only and is not shown to your users.

  4. Under iOS code snippet, copy and save the Swift version of the initialization code, not the Objective-C one. The Swift version is the second snippet.

    It should look as follows, but with different argument values:

    Zendesk.initialize(appId: "1e41a02a5f85d58e009ed4fa",    clientId: "mobile_sdk_client_e1c4e6262f1d02f43496",    zendeskUrl: "https://omniwear.zendesk.com")Support.initialize(withZendesk: Zendesk.instance)

    The initialization code is unique to your app and your instance of Zendesk Support. Save the snippet from your account -- not the one in the example -- in a text file for now.

  5. For Authentication method, select Anonymous.

    When the application accesses Zendesk Support, it needs to be able to authenticate as a user. You can use anonymous access or JWT authentication. For simplicity, you'll use anonymous access for the sample app.

  6. Click Save.

Adding the initialization code to the application delegate

Your application can delegate certain tasks to another object named appropriately enough the application delegate. The AppDelegate.swift file in your project defines this delegate. It contains a UIApplicationDelegate object with methods that run in response to important events in the lifetime of the application. For example, one method runs on application launch. You can add your own code to these event handlers.

  1. In Xcode, select AppDelegate.swift in the Project navigator.
  2. Add the following import statements after the import UIKit statement:

    import SupportSDKimport ZendeskCoreSDK
  3. Add the initialization code snippet you copied to the application() method that has the didFinishLaunchingWithOptions argument. Make sure to paste the snippet before the return statement.

    The method should look as follows with the initialization code:

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Zendesk.initialize(appId: "1e41a02a5f85d58e009ed4fa",        clientId: "mobile_sdk_client_e1c4e6262f1d02f43496",        zendeskUrl: "https://omniwear.zendesk.com")    Support.initialize(withZendesk: Zendesk.instance)
        return true}

    Applications are event driven, so you need to initialize the framework in an event handler like the application() method. The method runs just before the application moves to the active state.

  4. Run a build to make sure you don't get any error messages.

Adding a user identity

When the application accesses Zendesk, it needs to be able to authenticate as a user. You can use anonymous access or JWT authentication. For simplicity's sake, you selected anonymous access when you registered your app in Zendesk Support above.

  1. Add the following code (in bold) after the Zendesk.initialize() statement but before the Support.initialize(...) statement:

    ...
    
    let identity = Identity.createAnonymous()
    Zendesk.instance?.setIdentity(identity)
    
    Support.initialize(withZendesk: Zendesk.instance)

    The completed method should look as follows:

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        Zendesk.initialize(appId: "1e41a02a5f85d58e009ed4fa",        clientId: "mobile_sdk_client_e1c4e6262f1d02f43496",        zendeskUrl: "https://omniwear.zendesk.com")
        let identity = Identity.createAnonymous()    Zendesk.instance?.setIdentity(identity)
        Support.initialize(withZendesk: Zendesk.instance)
        return true}
  2. Save, then run a build to make sure you don't get any error messages.

If everything checks out, you can start adding support features to your application.

Creating a navigation controller for the SDK features

The Help Center feature is designed to work with a navigation controller. A navigation controller manages a stack of views, each with its own view controller. Among other things, the controller provides a back button that lets users go back to the previous view in the stack.

Your sample project consists of a tab bar controller with two connected view controllers:

Assume the first view controller is reserved for the main features of your fictional app. You won't worry about it here.

You'll replace the second view controller with a navigation controller to display Help Center. One approach is to embed the view controller in a navigation controller and then delete the view controller. The approach has the added benefit of preserving the tabbed interface connectors.

  1. In the Project navigator, select the Main.storyboard file to open it in Interface Builder, Xcode's visual UI editor.

    The storyboard displays the application's views and their relationships:

    To get this bird's-eye view, right-click the storyboard and choose Zoom to Fit.

  2. Zoom in on the "Second View" view and click it to give it focus.
  3. Select the round yellow icon on the view's top bar.

    The icon represents the view controller for the view.

  4. In the Xcode menu, select Editor > Embed In > Navigation Controller.

    Xcode rearranges the app for you, moving the second view as the root view in the navigation controller's stack.

    Tip: If your storyboard gets too congested, right-click and choose a zoom level.

  5. In the document outline to the left of the storyboard (not the Project navigator), select the Second View Controller and press the Delete key. You don't need it anymore.

You should be left with just the navigation controller.

Making the controller customizable

Before you can add the Zendesk Support features to the navigation controller, you need to make the controller customizable. You make controllers customizable by subclassing them, as described in this section.

  1. Select File > New > File, then choose Swift File, and click Next.
  2. Name the file SupportNavController and click Create.

    While you're at it, you can delete the SecondViewController.swift file in the Project inspector. The associated view controller doesn't exist anymore.

  3. Open the SupportNavController file in the code editor, delete everything in it, and add the following lines:

    import UIKit
    class SupportNavController: UINavigationController {}

    This creates a customizable subclass of the UINavigationController class. The subclass name should be the same as the file name.

  4. Make sure to save the file.
  5. Switch to the storyboard, select the navigation controller, then open the Identity inspector in the Utitilies panel on the upper-right side of the window.

  6. In the Custom Class section at the top, enter SupportNavController as the Class.

    This associates the navigation controller to your SupportNavController subclass.

Build and run the application to make sure everything is working. After clicking the second tab on the home screen in Simulator, you should see the following screen elements:

  • a black screen, which indicates that the navigation controller currently doesn't have a root view
  • a gray header, which is the navigation controller's Navigation view
  • a gray footer, which is the tab bar controller's Tab bar view

Adding Help Center

  1. In the SupportNavController.swift file, replace the import UIKit statement with the following import statement:

    import SupportSDK

    UIKit is a framework that defines many UI elements and other iOS-specific classes. You don't need to import it because it's imported by the ZendeskSDK framework.

  2. Add the viewDidLoad() override function to your SupportNavController subclass:

    class SupportNavController: UINavigationController {
        override func viewDidLoad() {        super.viewDidLoad()    }
    }

    Applications are event driven, so you need to start the Help Center in an event handler like viewDidLoad(). The viewDidLoad() override function always runs after the support view is loaded in memory.

  3. Add the following statements in the viewDidLoad() function to start Help Center:

    let helpCenter = HelpCenterUi.buildHelpCenterOverviewUi(withConfigs: [])pushViewController(helpCenter, animated: true)

    The first statement builds a view controller named helpCenter. The second statement pushes the helpCenter view controller on the current navigation controller.

That's it. The completed SupportNavController.swift file should look as follows:

import ZendeskSDK
class SupportNavController: UINavigationController {
    override func viewDidLoad() {        super.viewDidLoad()
        let helpCenter = HelpCenterUi.buildHelpCenterOverviewUi(withConfigs: [])        pushViewController(helpCenter, animated: true)    }
}

Build and test the application in Simulator. After tapping the second tab on the starting view, your Help Center should open in the app and let you browse and search the content.

The Help Center also lets users submit support requests (tickets) and view their open requests. Tap the note icon on the top-right to try it out.

Next steps

At this point you should have a working iOS application that lets users open your Help Center and submit support requests. Use this sample application to experiment with the rest of the framework.

For example, you can limit the number of articles displayed by specifying a list of section or category ids. You can also scope the content by supplying a list of labels. See Adding Help Center in the Support SDK documentation.

Put your project under git and create branches to try out different things. You can always reset if something goes horribly wrong.