Quick start - Chat SDK for iOS

This hands-on tutorial shows you how to build a functioning iOS application in 30 minutes that lets users chat with a support agent. It uses the Zendesk Chat SDK for iOS, a shared code library that lets you easily incorporate Zendesk Chat in iOS applications.

You need Mac OSX 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 Chat account. A free trial account is available. See the Zendesk Chat website.

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 chat functionality to an iOS application:

1. Downloading the Chat SDK
2. Creating a sample project
3. Adding the Chat SDK to the project
4. Embedding a view in a navigation controller
5. Adding a button to start a chat
6. Connecting the button
7. Initializing the Chat SDK
8. Pushing the chat view atop the current view
9. Start a chat
10. Next steps

The tutorial uses version 1.3 of the Chat SDK.

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

Downloading the Chat SDK

1. Download the Chat SDK from Github.

   Tip: Click Download ZIP on the right side of the repo toolbar to get all the files.

2. Unzip and move the folder to a sensible place on your hard drive.

   The folder that contains your iOS projects -- or where you plan on creating your projects -- is an excellent choice.

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 Chat SDK.

1. In Xcode, select File > New > Project. Make sure iOS is selected on the top bar.

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

2. Select Tabbed Application 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
   • Company Identifier - (required) Enter something like com.sample
   • Language - Select Swift
   • Devices - Select iPhone
   • Leave the last two checkboxes unchecked

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 Chat SDK to the project

1. Select your project by clicking the project name with the blue page icon at the top of the Project navigator.

   

2. Choose File > Add Files to “My Sample App” from the Xcode menu.

3. Navigate to the unzipped SDK folder you downloaded from Github and multi-select the following items:

   • ZDCChat.bundle
   • ZDCChat.framework
   • ZDChatAPI.framework
   • ZDCChatStrings.bundle

4. Before clicking Add, click the Options button below the files and make sure the rest of the settings are set as follows:

   • Destination - select Copy items if needed
   • Added folders - select Create groups
   • Add to targets - make sure your application is selected

   

5. Click Add.

Note: If you see question marks beside the framework items in the Project navigator, it means that the option to place the project under git was selected when you created it. It's selected by default. The question marks indicate that the framework files are untracked. You can ignore this for now.

Running a test build

Before going any further, make sure you successfully added the Chat 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. In the Scheme pop-up menu on the Xcode toolbar, choose iPhone 6s.

   

2. 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. Be patient. It can take a while to get going the first time it starts. It's much faster with subsequent builds.

   Eventually your application opens in Simulator:

   

Consider the test a success if you don't get any build errors. If you want, you can click the tabs on the lower side to test that the basic tabbed interface works.

If you get a build error, a framework may be missing. See Adding the MobileCoreServices framework below

Tip: If the app is too big for the Simulator window, select Window > Scale on the Simulator menu.

Embedding a view in a navigation controller

The Chat SDK displays the chat view on iPhones by pushing it as the topmost view in a navigation controller. A navigation controller manages a stack of views, each with its own view controller. The navigation controller provides a back button that lets users go back to the previous view in the stack.

Your sample project so far consists of a tab bar controller with two connected views, each managed by its own view controller. Because neither view controller is stacked in a navigation controller, you can't push the chat view atop anything yet.

To view the structure of your application, select the Main.storyboard file in the Project navigator to open it in Interface Builder:

Tip: To get this bird's-eye view, double-click an empty part of the canvas to zoom out, or right-click and choose a zoom level.

In this section, you'll embed the second view controller in a navigation controller so you can push the chat view atop the second view. The second view will show a button that customers can tap to chat with a support agent.

(The first view is reserved for the main features of your fictional app. We won't worry about it here.)

To embed the second view in a navigation controller

1. On the storyboard, zoom in on the "Second View" view and click it to give it focus.

2. Select the round yellow icon on the view's top bar.

   

   The icon represents the view controller for the view.

3. 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.

   

Adding a button to start a chat

In this section, you'll add a button to the second view that users can tap to start a chat with a support agent. This isn't a UI design tutorial so the changes are limited to adding a very basic button.

1. Select the Main.storyboard file to open it in Interface Builder.

2. Make sure the object library is visible in the panel on the right side of the screen by selecting the third tab in the toolbar on the bottom half of the panel.

   

   The object library lists objects you can add to the storyboard to build your user interface.

3. Scroll down the list until you find the Button object, then drag an instance to the second view. Use the vertical guideline to position the button in the horizontal center of the view.

   

4. Double-click the button, change the text to Chat, and press Enter.

5. With the button still selected, click the Align button on the lower right side of the storyboard:

   

6. In the Add New Alignment Constraints dialog box, select the Horizontally in Container option, then click Add 1 Constraint.

7. With the button still selected, click the Pin button on the lower right side of the storyboard:

   

8. Make the following changes in the Add New Constraints dialog box:

   1. Click the T bar connecting the top-most neighbor so it turns solid red.

      

   2. Click Add 1 Constraint.

9. Save, then run a build to make sure you don't get any error messages.

If you see a triangular warning icon in the build status bar at the top, select the view controller icon () on the view's top bar, click the Resolve Auto Layout Issues icon () on the lower right side of the storyboard, then select Update Frames.

Connecting the button

In this section, you connect your Chat button to a method in the second view controller. The connection triggers the method, or action in iOS, when the user taps the Chat button. You'll later add code to the method that pushes the chat view on top of the second view.

Create an action

1. In the Project navigator, select SecondViewController.swift.

2. Delete everything in the SecondViewController subclass until it looks as follows:

   class SecondViewController: UIViewController {
   
   }
   

3. Add the following action to the subclass:

   @IBAction func pushChat(sender: AnyObject) {
   
   }
   

   Your code should look as follows:

   class SecondViewController: UIViewController {
   
       @IBAction func pushChat(sender: AnyObject) {
   
       }
   
   }
   

   The expression @IBAction identifies the function as an Interface Builder (IB) action. You can call the function anything you want. I went with pushChat.

4. Save the file.

Connect the button to the action

1. Click the Main.storyboard file to switch to the storyboard.

2. Select the Chat button in your second view by clicking it.

3. While holding down the Control key or the right mouse button, drag from the button to the view controller icon () on the view's top bar, then release the key or mouse button to reveal a menu.

   

4. Select your newly created action under Sent Events (pushChatWithSender here).

5. Save the file, then run a build to make sure you don't get any error messages.

If everything checks out, you can initialize the Chat SDK and push the chat view atop the second view.

Initializing the Chat SDK

Before a user can use chat on their device, the application has to create and prepare an instance of the Chat SDK. The initialization process involves setting initial values and performing other setup tasks.

In this section, you'll update the sample application to initialize the Chat SDK. The task consists of the following steps:

1. Getting the Zendesk Chat account key
2. Adding the initialization code to the application

Getting the Zendesk Chat account key

You'll need access to the Zendesk Chat dashboard to get the Chat account key. If you don't have access, ask somebody who does to perform the following steps.

1. In the Chat dashboard, click the vertical triple-dot icon below your profile icon in the upper right, then select Check Connection.

   

2. Copy and save the account key. It should be the second item in the list.

Adding the initialization code to the application

You add 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 the AppDelegate.swift file in the Project navigator.

2. Replace the import UIKit statement with the following import statement:

   import ZDCChat
   

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

3. Add the the following initialization code to the didFinishLaunchingWithOptions application method:

   ZDCChat.initialize(withAccountKey: "your_account_key")
   

   Replace the your_account_key placeholder value with the account key you retrieved earlier from the Chat dashboard.

   The delegate method should look as follows:

   func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
   
       ZDCChat.initialize(withAccountKey: "3NPBQia9qItVDD98qmCYEfVesWLR4IFC")
   
       return true
   }
   

   The delegate method runs just before the application moves to the active state.

4. Save, then run a build to make sure you don't get any error messages.

If everything checks out, you can push the chat view atop the second view when the user taps the Chat button.

Pushing the chat view atop the current view

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

   import ZDCChat
   

2. Add the following statement to the pushChat() method you added earlier:

   ZDCChat.start(in: self.navigationController, withConfig: nil)
   

That's it. When the function runs in response to the user tapping your custom button, it calls the start() method. The method in turn pushes the chat view atop the current view controller.

The completed SecondViewController.swift file should look as follows:

import ZDCChat

class SecondViewController: UIViewController {

    @IBAction func pushChat(sender: AnyObject) {
        ZDCChat.start(in: self.navigationController, withConfig: nil)
    }

}

Start a chat

You can start a test chat if one or more chat agents are online. If nobody is online and you're a Zendesk Chat agent or administator, you can chat with yourself by setting your status to Online in the Chat dashboard:

Build and run the application in Simulator. After tapping the second tab and then your custom Chat button, the chat interface should appear. Enter a message and tap Send to initiate a chat.

Next steps

At this point you should have a working iOS application that lets users chat with support agents. Use the sample application to experiment with the rest of the SDK. Here are some resources:

• Chat iOS SDK documentation
• Using the Chat SDK APIs to show the number of unread messages (iOS)

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