Introduction

The Zoho Desk Software Development Kit (SDK) for iOS is aimed at helping you build a custom iPhone/iPad app containing the features and functionalities of Zoho Desk. When you build an app using this SDK, you get to choose which help desk module you want to retain and which one you want to exclude. Besides, you can design the app UI according to your requirements and style guidelines, while powering the back-end of the app using the SDK.

Getting Started

There are a few requirements that must be met before you can start creating an app using the Zoho Desk SDK for iOS. These requirements are as follows.

Zoho Account

Having a Zoho account is an absolute must to be able to use the Zoho Desk SDK for iOS. If you do not have an account yet, sign up for one by visiting this link.

Client ID and Secret

Next, you require the client ID and secret for your app. To receive these credentials, you must first register your app by performing the following steps.

1. Visit Zoho's Developer Console.
2. On the API Credentials page, click the Add Client ID button.
   The Create Zoho Client ID form appears.
3. In this form, enter the following details:
   • Client Name: Name of your app
   • Client Domain: Website of your app
   • Authorized redirect URIs: Redirect URI for authentication
4. In the Client Type drop-down list, choose Mobile.
5. Click the Create button.
   The Client ID and Client Secret are displayed.

Building Your App

The first step towards building your app is installing the Zoho Desk SDK for iOS. Keep in mind that the minimum iOS version required is iOS 9.

Installing the Zoho Desk SDK for iOS

You can either automatically install the SDK using the CocoaPods dependency manager tool or manually install it in the project directory of your app.

Automatic Installation Using CocoaPods

target ‘Demo' do
      use_frameworks!
      pod ‘ZohoAuth'
      pod 'ZohoDeskSDK'
      end

To add the Zoho Desk SDK to your iOS app, just add the ZohoAuth and ZohoDeskSDK pods to the podfile.

target ‘Demo' do
      use_frameworks!
      pod "ZohoAuth"
      pod "ZohoDeskUIKit"
      pod 'ZohoDeskSDK'
      end

To include Zoho Desk UI components too in your app, add the ZohoDeskUIKit pod to the podfile.

After adding the required pods, run the pod install command in the project directory.

Note: If you have not set up CocoaPods for your app, run the pod init command from the root of your project directory. This command creates the podfile required.

Manual Installation

1. Download the framework from one of the links below:
   • Zoho Desk SDK for iOS
   • Zoho Desk SDK for iOS (with UI components)
2. Drag the .project file into the project directory of your app.
3. Add the ZohoDeskSDK framework in the Embedded Binaries and Linked Frameworks and Libraries sections of the Xcode project settings.

Note: Make sure that the Copy items if needed option is selected in the settings related to Embedded Binaries.

Initializing and Authenticating the Zoho Desk SDK for iOS

Import ZohoAuth
      Import ZohoDeskSDK

Make sure to add the ZohoAuth and ZohoDeskSDK headers to the app delegate object.

Then, add the code on the right panel in the app delegate.

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
      let configuration =  SDKConfiguration(baseURL: "https://desk.zoho.com")
      _ = ZohoDeskSDK(configuration: configuration)
      ZohoDeskSDK.delegete = self
      
      let scope = ["ZohoSupport.tickets.ALL","ZohoSupport.basic.READ","ZohoSupport.basic.CREATE","ZohoSupport.settings.ALL","ZohoSupport.basic.READ","ZohoSupport.contacts.READ","Zohosearch.securesearch.READ","aaaserver.profile.READ","zohocontacts.userphoto.READ","ZohoSupport.feeds.ALL","ZohoSupport.basic.ALL", "VirtualOffice.messages.CREATE", "profile.userphoto.UPDATE","profile.userinfo.READ","Desk.search.READ","profile.orguserphoto.READ","Desk.tasks.READ","Desk.contacts.READ"]
      
      ZohoAuth.initWithClientID(, clientSecret: , scope: scope, urlScheme: , mainWindow: (UIApplication.shared.delegate?.window)!, accountsURL: "https://accounts.zoho.com")
      ZohoAuth.getOauth2Token { (token, error) in
      if token == nil{
      ZohoAuth.presentZohoSign(in: { (token, error) in
      if token != nil{
      //Success Login
      }
      })
      }
      else{
      //Success Login
      }
      }
      //Your code
      return true
      }

Note: The Zoho Accounts URL varies according to your domain.

Add URLScheme to the Info.plist File

URLScheme refers to the redirect URI entered while generating the client ID and secret of your app. This URI must be included in the Info.plist file of your app for authentication.

Add:
      <key>CFBundleURLTypes</key>
      <array>
      <dict>
      <key>CFBundleURLName</key>
      <string><#URLScheme#></string>
      <key>CFBundleURLSchemes</key>
      <array>
      <string><#URLScheme#></string>
      </array>
      </dict>
      </array>

In the code on the right panel, replace #URLScheme with the actual redirect URI. Then, paste the code in the Info.plist file.

Add Custom Login

ZohoAuth.presentZohoSign(inHavingCustomParams: ) { (token, Error) in
      if token != nil{
      //Login Success
      }
      }

To add the Zoho Accounts login to your app and customize the login page, add the code snippet on the right panel to the login button action in the ViewController object of your app.

Add the OpenURL Method to the App Delegate Object

This method enables the ZohoAuth library to handle user login for the app.

To include this method, copy-paste the code on the right panel into the app delegate object.

Note: Code Snippet 1 is applicable only for iOS versions 10 and later. Code Snippet 2 is applicable for iOS versions older than iOS 10.

func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
      let sourceapplication = options[UIApplicationOpenURLOptionsKey.sourceApplication] as! String
      let annotation = options[UIApplicationOpenURLOptionsKey.annotation]
      ZohoAuth.handleURL(url, sourceApplication: sourceapplication, annotation: annotation)
      return true
      } 

Code Snippet 1:

func application(_ application: UIApplication, open url: URL, sourceApplication: String?, annotation: Any) -> Bool { 
      return ZohoAuth.handleURL(url, sourceApplication: sourceApplication, annotation: annotation) 
      }

Code Snippet 2:

Including Custom Params

The SDK supports inclusion of custom params on the login page. The following table lists the different custom params and their purposes.

Custom Param Name	Values Supported	Purpose
hide_signup	true or false	Show or hide Sign Up option
portal_domain	Registered domain name of the organization	Display organization logo on the login page
hide_fs	true or false	Show or hide Federated Sign In option

@"hide\_signup=false\&hide\_fs=true"

Note: You can include more than one custom param in the URL query param format. To view an example, refer to the right panel.

Handling User Logout

ZohoAuth.revokeAccessToken { (error) in
      if error != nil{
      }
      }

Add the code snippet on the right panel to the Logout/Sign Out button action in the ViewController object.

ZohoDeskUIKit.flushUserData()

Also, make sure to clear user data when a user logs out. To perform this activity, use the code snippet on the right panel.

Note: Clearing of user data is possible only in the Zoho Desk UI Kit.

Enabling Authentication for API Calls

The ZDAuthenticationDelegate method handles authentication related to API calls for the Zoho Desk SDK for iOS. This method fetches the OAuthToken that the SDK requires for making API calls.

func getToken(completion: @escaping ((String) -> ())) {
      ZohoAuth.getOauth2Token { (token, error) in
      let token = "Zoho-oauthtoken \(token ?? "")"
      completion(token)
      }
      }

Make sure to include this method in the app delegate object. Otherwise, API requests cannot be made from the SDK.

Zoho Desk APIs

Below are a few examples of the APIs provided by Zoho Desk.

Get organization

ZDOrganizationAPIHandler.getOrganization() { (organization, error, statusCode) in
      if error != nil{
      //Show UI operation
      }
      else{
      //show Error
      }
      }

This API returns details of an organization from the help desk portal.

Get ticket details

ZDTicketAPIHandler.getTicketDetails(, ticketId: ) { (ticketDetail, error, statusCode) in
      if error != nil{
      //Show UI operation
      }
      else{
      //show Error
      }
      }

This API returns the details of a ticket from the help desk portal.

Help desk modules are referred to in the ZD<Module Name>APIHandler format in API requests and ZD<Module Name> format in API responses.

To download a sample app to check how the APIs work, click here.

To view the complete list of Zoho Desk APIs, click here.

Zoho Desk UI Kit for iOS

The Zoho Desk UI Kit for iOS is a plug-and-play feature that helps build an app using standard UI elements created by Zoho. All that you need to do is add a view to the app and call an init method with the params required.

Currently, the UI kit supports the Ticket List and Ticket Detail components.

Ticket List Component

let configuration = ZDTicketListConfiguration(orgId: orgId)
      configuration.from = 0
      configuration.limit = 50
      configuration.include = "contacts,products"
      configuration.sortBy = "recentThread"
      ticketView = ZDTicketListView(frame: , configuration: )
      ticketView?.delegate = self
      view.addSubview(ticketView!)

To display the ticket list in your app, add the code snippet on the right panel to the ViewController object.

ZDTicketListConfiguration

You can customize the ticket list by altering the different attributes in the ZDTicketListConfiguration method.

let configuration = ZDTicketListConfiguration(orgId: )
      configuration.from = 0
      configuration.limit = 50
      configuration.include = "contacts,products"
      configuration.sortBy = “recentThread"

To view the complete list of attributes supported, click here.

TicketList Delegate

The TicketList delegate enables callbacks to the ViewController when certain events occur in the view. The different callbacks supported are: BeginLoading, EndLoading, DidSelectTicket, and ShouldLoadMoreData.

BeginLoading

Sends a callback to the ViewController when the ticket list is populated with content from the server.

func didBeginLoadingData(ticketList:ZDTicketListView,from:Int) -> Void{
      }

Note: You can display a loading indicator, if required. The delegate sends a callback everytime a set of tickets is loaded. You can configure the loading indicator to appear when the from index value is 0.

from refers to the index number starting from which the tickets must be listed.

EndLoading

func didEndLoadingData(ticketList:ZDTicketListView,error:Error?,statusCode:Int) -> Void{
      }

Sends a callback to the ViewController when the ticket list finishes loading. You can choose to hide the loading indicator for this callback.

DidSelectTicket

func didSelectTicket(ticketList:ZDTicketListView,orgId:String,ticketId:String,index:Int) -> Void{
      }

Sends a callback to the ViewController when the user selects a ticket in the list.

ShouldLoadMoreData

func shouldLoadMoreData(ticketList:ZDTicketListView) -> Bool{
      return true
      }

Sends a callback to the ViewController if the ticket list tries to load more content.

UpdateConfig

This method helps update configuration details, such as the orgId.

updateConfig(configuration:)

When this method is executed, all data is reset and the ticket list is refreshed with the new configuration settings.

Ticket Detail Component

let configuration = ZDTicketDetailViewConfiguration(orgId: self.orgId, ticketId: ticketId)
      let ticketdetails = ZDTicketDetailView(frame: self.view.bounds, configuration: configuration)
      view.addSubview(ticketdetails)

To display the ticket detail view in your app, add the code snippet on the right panel to the ViewController object.

ZDTicketDetailViewConfiguration

let configuration = ZDTicketDetailViewConfiguration(orgId: self.orgId, ticketId: ticketId)
      OrgID - Unique ID of the organization
      TicketId - Unique ID of the ticket

The ticket detail view displays ticket information, based on the configuration set in this method. The code for a sample configuration is displayed on the right panel.

TicketDetail Delegate

The TicketDetail delegate enables callbacks to the ViewController when certain events occur in the view. The different callbacks supported are: BeginLoading, EndLoading, and ShouldLoadMoreData.

BeginLoading

func didBeginLoadingData(ticketdetail:ZDTicketDetailView,) -> Void{
      }

Sends a callback to the ViewController when the ticket detail view receives content from the server.

Note: You can display a loading indicator, if required.

EndLoading

func didEndLoadingData(ticketdetail:ZDTicketDetailView,error:Error?,statusCode:Int) -> Void{
      }

Sends a callback to the ViewController when the ticket detail view finishes loading.

ShouldLoadMoreData

func shouldLoadMoreData(ticketList:ZDTicketListView,listingType:String) -> Bool{
      return true
      }

Sends a callback to the ViewController if the ticket detail view tries to load more conversation/thread/comment data.

UpdateConfig

This method helps update configuration details, such as the orgId.

When this method is executed, all data is reset and the ticket detail view is refreshed with the new configuration settings.