Working with the ASAP SDK for iOS

Working with the ASAP SDK for iOS

SDK v2.0

Introduction

The ASAP SDK for iOS makes help available within quick reach for the end-users of your iOS app. Using this SDK, you can create and customize an add-on that resides within your app and provides end-users with easy access to your:
  • Customer support team (to raise tickets or chat with support agents)
  • Knowledge Base (to access help articles)
  • User community (to interact with other users of the app)
What this addition means for end-users is that they do not have to exit your app and visit your website or send an email to contact you for support. They can easily seek help right from within your app, thereby saving time and enjoying a superior customer experience.
To see the ASAP SDK in action, install this demo app on your iPhone or iPad. 
In the latest release of the SDK (v2.0), we have supported iOS 13's dark mode and made the SDK more accessible by matching the font size with that configured in the user's system. Also, in response to the overwhelming requests from the developer community, we have now separated the Chat module from the other help modules. So, you can now choose to integrate the ASAP Core SDK (consists of the Knowledge Base, Community, and Ticket modules) or the ASAP Services SDK (consists of all core modules and the Chat module).

The ASAP SDK is compatible with iOS 9 and all later versions.
If you are a current user of the ASAP SDK (versions up to 1.1.12), you need to migrate the existing code to use v2.0. For instructions on how to do this, please refer to the Migrating from v1.x to v2.0 section of this article.

Setting Up the SDK in Zoho Desk

The first step to including the ASAP add-on within your iOS app is to create and register the add-on in Zoho Desk.
To create the add-on, perform the following steps.
  1. Go to this path in Zoho Desk: Setup → Channels → ASAP.
  2. In the Setup pane on the left, under ASAP, click the + button next to Mobile. The Create Mobile Add-On page appears.

  3. Under Add-On Details , configure the following settings:
    1. Name: Name for the ASAP add-on. This name is only for reference; it does not appear anywhere on the app UI.
    2. Available for : Departments for which this ASAP add-on must be enabled
    3. Bundle ID: In the iOS field, enter the bundle ID of your iOS app. (You can retrieve the bundle ID from the General tab within the project target of your app settings.)
      Note : Bundle ID is mandatory for enabling Live Chat and sending push notifications.
    4. Live Chat: Toggle switch for enabling/disabling Live Chat.
      Note : The Live Chat module reflects the settings configured for the chat channel in your help desk portal. Therefore, any change required must be done via the Setup page in Zoho Desk.
    5. Push Notifications : Toggle switch for enabling/disabling push notifications. For more details, refer to the Enabling Notifications section in this document.
      Note : JWT-based user authentication is mandatory for enabling notifications. Push notifications related to tickets are not sent to anonymous users.
    6. Authentication Method: User authentication setting for the add-on
    7. Anonymous - In this method, end-users are considered guest users. They can only submit tickets, view posts in the user community, and chat with a customer support agent. They cannot view the tickets they submitted or actively participate in the user community.
    8. JWT - In this method, end-users are considered authenticated users. In addition to the activities that guest users can perform, authenticated users can also view and track the status of the tickets they submitted, reply/comment to a ticket, and actively participate in the user community (with rights to perform actions, such as following a topic, adding a topic, and adding a comment to existing posts).
  4. Click Save.
A new section called Code Snippet appears. This section displays the Org ID, App ID, and Deployment type details of your app. These details are vital for initializing the ASAP SDK in your app.

Integrating the SDK with Your App

The next step is to integrate the ASAP SDK with your iOS app.
You can follow either of the following two methods to perform this step.
Automated Integration Using CocoaPods
This method involves use of CocoaPods, a dependency manager that lets you add third-party frameworks and libraries to Xcode projects. For information on how to install CocoaPods, visit this link.
As the first step to integrating the SDK with your app using CocoaPods, you must create a Podfile for your project. If you have not created a Podfile already, perform the following steps:
  1. In Terminal, navigate to the top-level folder of your project (the folder with the xcodeproj file).
  2. Execute the $ pod init command.
  3. Then, open the Podfile in Xcode by executing the open -a Xcode Podfile command. The content should look as follows:
    # Uncomment this line to define a global platform for your project
    # platform :ios, '9.0'
    # Uncomment this line if you're using Swift
    # use_frameworks!
    target 'My Sample App' do
    end
  4. If you use Swift, uncomment the use_frameworks! line.
Next, you must add the Zoho Desk Portal SDK to the Podfile and install the SDK in your project. To do this, perform the following steps.
  1. First, include the SDK of your choice in the Podfile.
    • To integrate the ASAP Core SDK (Tickets, Knowledge Base, and Community), include the following code in the do block of the Podfile.
      target 'My Sample App' do
      pod 'ZohoDeskPortalCore'
      end
    • To integrate the ASAP Services SDK (Tickets, Knowledge Base, Community, and Live Chat), include the following code in the do block of the Podfile.
      target 'My Sample App' do
      pod 'ZohoDeskPortalServices'
      end
  2. Save the Podfile.
  3. Execute the $ pod install command in Terminal.
You have now successfully integrated the SDK with your app using CocoaPods. What this technically means is that your project contains a dependency managed by CocoaPods. So, going forward, you must open your project in Xcode from the file and not the .xcworkspace .xcodeproj file. For more information on how to use CocoaPods, click here
Manual Integration
If you do not want to integrate the ASAP SDK with your app using CocoaPods, you can perform a manual integration. To do this, perform the following steps.
  1. First, download the SDK of your choice.
    • For the ASAP Core SDK (Tickets, Knowledge Base, and Community), use this link.
    • For the ASAP Services SDK (Tickets, Knowledge Base, Community, and Live Chat), use this link.
  2. Decompress the zip file you downloaded. Then, drag and drop the respective framework file, which has the extension . XCFramework, to the Frameworks, Libraries and Embedded Content section of your Xcode project bundle.
Note : If you choose to integrate the ASAP Core SDK, make sure to add the NSPhotoLibraryUsageDescription, NSCameraUsageDescription and NSMicrophoneUsageDescription keys in the info.plist file of your app.
If you choose the ASAP Services SDK, you need to add these three keys and an extra key called NSBluetoothPeripheralUsageDescription. This step is important because the Chat module requires Bluetooth permissions. Missing to add these keys to the info.plist file will result in app crash at the time of launching the app or when the relevant view controller is presented and Appstore validation may fail.

Initializing the SDK in Your App

Next, you initialize the ASAP SDK in your app.
The following three keys are crucial in this step:
  • Org ID
  • App ID
  • Datacenter
The values of these keys appear under the Code Snippet section in the setup page of the ASAP add-on in Zoho Desk.
To initialize the SDK in your app, perform the following steps.
  1. Import the Zoho Desk Portal SDK framework into the AppDelegate file in your project.
    Swift
    import ZohoDeskPortalAPIKit
    Objective-C
    @import ZohoDeskPortalAPIKit;
  2. Paste the following initialization code into the application method with the didFinishLaunchingWithOptions argument.
    Swift
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        ZohoDeskPortalSDK.initialize(orgID:<#String#>, appID:<#String#>, dataCenter: <#ZDPDataCenter#>)
        return true
    }
    Objective-C
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
        [ZohoDeskPortalSDK initializeWithOrgID:<#NSString#>appID:<#NSString#>dataCenter:<#ZDPDataCenter#>];
        return YES;
    }
Note :
Datacenter values according to the deployment type are as follows:
CN - ZDPDataCenter.CN
EU - ZDPDataCenter.EU
US - ZDPDataCenter.US
IN - ZDPDataCenter.IN
AU - ZDPDataCenter.AU

Displaying Help Modules

Given below are the methods for displaying individual help modules on the ASAP add-on. These methods display the modules according to their default configuration and the settings configured in your Zoho Desk portal. The modules in the default configuration vary according to the Zoho Desk edition in use.
SDK Dashboard
The SDK dashboard is the screen through which end-users access your help center. This dashboard displays icons/buttons that provide access to your Knowledge Base, user community, customer support team (through the ticket submission form), tickets list (list of tickets submitted by users who are logged in), and live chat (to interact with a customer support agent in real time).
Note : If you chose ASAP Services and want to display the Chat module, make sure to enable it in your Zoho Desk web portal.
To display the SDK dashboard, include the following code in any method of your choice.
Swift
import ZohoDeskPortalCore
...
ZDPortalHome.show()
Objective-C
@import ZohoDeskPortalCore;
...
[ZDPortalHome showWithConfiguration:nil andTitle:nil];
Note
  • To display a particular help module in the add-on, you must first enable it in your Zoho Desk web portal.
  • You can also hide a module on the dashboard and launch it from a different location in your app.
  • You also have the option to not display the SDK dashboard on your app and still provide access to individual help modules.

The following methods help you display the individual modules with their default configuration.
SDK Dashboard with overridden configuration
The following method displays the SDK dashboard with its configuration overridden.
Swift
let config = ZDPHomeConfiguration()
config.enableHelpCenter = true // disable/enable the Help center (Knowledge Base).
config.enableCommunity = false // disable/enable the Community.
config.enableCreateTicket = true // disable/enable the CreateTicket.
config.enableMyTicket = true // disable/enable My Tickets.
ZDPortalHome.show(withConfiguration: config)
Objective-C
ZDPHomeConfiguration * config = [[ZDPHomeConfiguration alloc]init];
config.enableHelpCenter = YES; // disable/enable the Help center (Knowledge Base).
config.enableCommunity = NO; // disable/enable the Community.
config.enableCreateTicket = YES; // disable/enable the CreateTicket.
config.enableMyTicket = YES; // disable/enable My Tickets.
[ZDPortalHome showWithConfiguration:config andTitle:<#(NSString * _Nullable)#>];
In this example code snippet, the dashboard is configured such that the Community module is hidden. You also have the option to not display the SDK dashboard on your app and still provide access to individual help modules. The following methods help you display the individual modules with their default configuration.
Live Chat
Through Live Chat, end-users can interact with a customer support agent in real time.
The following methods display the Live Chat module.
Swift
import ZohoDeskPortalChat
...
ZDPortalChat.show()
Objective-C
@import ZohoDeskPortalChat;
...
[ZDPortalChat show];
Help Center (Knowledge Base)
Help center is the module through which end-users can access help articles in your Knowledge Base.
For all method calls related to the Knowledge Base, include the following import statement.
Swift
import ZohoDeskPortalKB
Objective-C
@import ZohoDeskPortalKB;
The following methods display the help center (Knowledge Base).
Swift
ZDPortakKB.show()
Objective-C
[ZDPortalKB showWithTitle:<#NSString#>];
To display a Knowledge Base category using its permalink, use the following method.
Swift
ZDPortalKB.showCategory(withPermalink: <#String#>)
Objective-C
[ZDPortalKB showCategoryWithPermalink:<#NSString#>withTitle:<#NSString#>];
Permalink refers to the URL of the Knowledge Base category.

For instance, in the URL in the image above, the portion following "/kb/" is the permalink of the category. You can pass this portion as the path of the category or sub-category.
To display an article directly using its permalink, use the following method.
Swift
ZDPortalKB.showArticle(withPermalink : <#String#>)
Objective-C
ZDPortalKB showArticleWithPermalink:<#NSString#>withTitle:<#NSString#>];
Permalink refers to the URL of the help article.

For instance, in the URL in the image above, the portion following "/articles/" is the permalink of the article.
Tickets Module
For all method calls related to the Tickets module, include the following import statement.
Swift
import ZohoDeskPortalTicket
Objective-C
@import ZohoDeskPortalTicket;
Submit Ticket
Submit Ticket is the screen through which end-users can submit their questions/requests as support tickets.
The following methods display the Submit Ticket Screen.
Swift
ZDPortalSubmitTicket.show()
Objective-C
[ZDPortalSubmitTicket showWithTitle:<#NSString#>];
If you want your app to subscribe to the submit ticket event, use the following method, which includes an event callback.
Swift
ZDPortalSubmitTicket.showAddTicketForm(completion: { (ticket) in 
  // The ticket parameter contains the details of the ticket created.
  // Your program logic goes here.
}, onError: { error in 
  // error creating Ticket
})
Objective-C
[ZDPortalSubmitTicket showAddTicketFormWithTitle:<#(NSString * _Nullable)#> navigationMode:<#(enum ZDPNavigationMode)#> completion:^(ZDPTicket * ticket) { 
  // The ticket parameter contains the details of the ticket created.
  // Your program logic goes here.
} onError:^(NSError * error) {
  // error creating Ticket
}];
The callback object sends ticket information to your app when a ticket is submitted via the Submit Ticket screen.
Note : If an authenticated user submits a ticket, all ticket details are sent. If a guest user submits a ticket, only the ticket number is sent.
My Tickets
My Tickets is the screen through which end-users can access, track, and edit the tickets they submitted.
The following methods display the My Tickets screen.
Swift
ZDPortalTicket.show()
Objective-C
[ZDPortalTicket showWithTitle:<#NSString#>];
User Community
User community is the module through which end-users can access discussion forums and interact with other users for sharing knowledge.
For all method calls related to the Community module, include the following import statement.
Swift
import ZohoDeskPortalCommunity
Objective-C
@import ZohoDeskPortalCommunity;
To display the user community,
Swift
ZDPortalCommunity.show()
Objective-C
[ZDPortalCommunity show];
To display a particular topic,
Swift
ZDPortalCommunity.showTopic(withID: <#String#>)
Objective-C
[ZDPortalCommunity showTopicWithID:<#NSString#>];

Authenticating Users in the SDK

To access the tickets they submitted, end-users of your app must have an identity so that they can authenticate themselves as a user of the Zoho Desk portal. This authentication is made possible in Zoho Desk via the JSON Web Token (JWT).
Zoho Desk supports two types of authentication: Anonymous and JWT.
  • Anonymous - In this type, end-users are considered guest users. They can only submit tickets, view posts in the user community, and chat with a customer support agent. They cannot view the tickets they submitted or actively participate in the user community.
  • JWT - In this type, end-users are considered authenticated users. In addition to the activities that guest users can perform, authenticated users can also view the tickets they submitted and actively participate in the user community (with rights to perform actions, such as following a topic, adding a topic, and adding a comment to existing posts).
For detailed information on how to configure JWT-based user authentication in the ASAP SDK, refer to this document.
The following code snippet authenticates users in the SDK. Make sure to include the following import statements to access all methods related to user authentication.
Swift
import ZohoDeskPortalAPIKit
Objective-C
@import ZohoDeskPortalAPIKit;
Swift
if !ZohoDeskPortalSDK.isUserLoggedIn{
    ZohoDeskPortalSDK.login(withUserToken: String) { (isSuccess: Bool) in
        // isSuccess shows whether the login attempt was successful
        // any errors will be logged
    }
}else{
        // user logged in already
}
Objective-C
if (!ZohoDeskPortalSDK.isUserLoggedIn){
    [ZohoDeskPortalSDK loginWithUserToken:<#(NSString * _Nonnull)#> onCompletion:^(BOOL isSuccess) {
        // isSuccess shows whether the login attempt was successful
        // any errors will be logged
    }];
}else{
    // user logged in already
}
ZohoDeskPortalSDK.isUserLoggedIn is a Boolean value that tells you whether the user is currently logged in or not.
Logging Users out from the SDK
To log a user out from the SDK, use the following method.
Swift
ZohoDeskPortalSDK.logout { (isSuccess: Bool ) in
   // isSuccess shows whether the logout attempt was successful
   // any errors will be logged 
}
Objective-C
[ZohoDeskPortalSDK logoutOnCompletion:^(BOOL isSuccess) {
   // isSuccess shows whether the logout attempt was successful
   // any errors will be logged
}];
After this method is called, the authenticated user is treated as an anonymous user.

Clearing Local Data

All the data stored locally in the device is automatically cleared when an authenticated user signs out from the ASAP add-on.
However, if local data needs to be cleared for anonymous users too, use the following method.
Swift
ZohoDeskPortalSDK.clearAllLocalData()
Objective-C
[ZohoDeskPortalSDK clearAllLocalData];

Customizing the Add-On UI

The ASAP SDK provides you with the option to customize the UI of the add-on as required.
Predefined Themes
The SDK UI comes with two predefined themes: white and black. The following methods help you apply these themes.

If you want to make any changes to the theme, first make sure to include the following import statement, which imports the Zoho Desk theme kit.
Swift
import ZDThemeKit
Objective-C
@import ZDThemeKit;
The ZDThemeKit module contains all theme-related APIs. Therefore, it must be imported before calling any method on ZDThemeManager.
Methods for Applying the White Theme (Default)
Swift
ZDThemeManager.setTheme(type: .white)
Objective-C
[ZDThemeManager setTheme:ZDThemeTypeWhite];
Methods for Applying the Black Theme
Swift
ZDThemeManager.setTheme(type: .dark)
Objective-C
[ZDThemeManager setTheme:ZDThemeTypeDark];
As you know, iOS 13 provides users with the option to set dark or light theme throughout the system. Therefore, for iOS 13 and above, you can set system theme in the ASAP add-on. In such cases, the add-on will be in the same theme as the rest of the OS.
Swift
ZDThemeManager.setTheme(type: .system)
Objective-C
[ZDThemeManager setTheme:ZDThemeTypeSystem];
Note
- ZDThemeType.system is available only for iOS 13 and above.
- By default, system theme will be applied for iOS 13 and above, and light theme will be applied for earlier versions.
Customized Themes
You can also override the default dark and light themes to make the SDK look more like your application.
To update the default light theme,
Swift
ZDThemeManager.updateTheme(theme: <#ZDThemeProtocol#>)
Objective-C
[ZDThemeManager updateThemeWithTheme:<#ZDThemeProtocol#>];
To update the default dark theme,
Swift
ZDThemeManager.updateDarkTheme(theme: <#ZDThemeProtocol#>)
Objective-C
[ZDThemeManager updateDarkThemeWithTheme:<#ZDThemeProtocol#>];
Here, ZDThemeProtocol contains the list of properties that represent the most used colors across the SDK, such as primaryTextColor and navigationBarTextColor among others. All properties in the protocol are optional. You can create any class conforming to this protocol, implement one or more properties, and pass an object of that class to the updateTheme or updateDarkTheme method. The colors you set in the class will override the default theme.
Note : Updating the SDK's theme is different from setting a theme type. At any point of time, the SDK will be in dark or light theme, based on the theme type you have set.
Using Custom Fonts
The SDK UI offers a set of default fonts, but you can use fonts of your choice if required.
To be able to display custom fonts on the SDK UI, perform these steps first:
  1. Add the font(s) to your project.
  2. Edit the info.plist file of your app to include the Fonts provided by application key.
  3. Under this key, list the file names of all the fonts you want to use in the SDK UI.
After adding the fonts to your project, you can customize the SDK UI to display text in that font.
To display the custom font on your SDK UI, include the following method in your app code
Swift
ZDPortalConfiguration.customFontName = <#String#>
Objective-C
ZDPortalConfiguration.customFontName = <#NSString#>;
Note : If you do not use a custom font, the add-on displays the system font by default. We have made the font sizes accessible from version 2.0. Accessibility for custom fonts, however, is supported only for iOS 11 and above.

Changing Language Settings

The ASAP SDK supports 47 languages. You can set any language of your choice, based on the geographical location of the end-users of your app.
Below is the code that helps you set the language for the ASAP add-on. However, to limit the size of the SDK, we have bundled only the 13 languages that were supported in v1.0 of the SDK.

Below is the list of all 47 languages supported in the ASAP SDK.

Language

Locale Code

English (UK)

en-GB

English (US)

en

German

de

Spanish

es

Catalan

ca-ES

French

fr

French (Canada)

fr-CA

Italian

it

Russian

ru

Chinese (Traditional)

zh-Hant

Chinese (Simplified)

zh-Hans

Turkish

tr

Dutch

nl

Danish

da

Portuguese (Portugal)

pt-PT

Japanese

ja

Swedish

sv

Polish

pl

Arabic

ar

Hebrew

he

Afrikaans

af

Czech

cz

Bulgarian

bg

Finnish

fi

Greek

el

Hungarian

hu

Indonesian

id

Norwegian (Bokmal)

nb

Romanian

ro

Thai

th

Ukrainian

uk

Vietnamese

vi

Urdu

ur

Hindi

hi

Telugu

te

Kannada

kn

Tamil

ta

Marathi

mr

Korean

ko

Persian

fa

Bengali

bn

Gujarati

gu

Malay

ms

Malayalam

ml

Slovak

sk

Croatian

hr

Slovenian

sl


Below is the code that helps you set the language for the ASAP add-on. Pass the language identifier to the method. For instance, pass "en" for English.

Swift
ZDPortalConfiguration.setSDKLanguage(<#String#>)
Objective-C
[ZDPortalConfiguration setSDKLanguage:<#NSString#>];
The following table lists the 13 languages that come bundled with the SDK.

Language
Locale Code
English
en
German
de
Spanish
es
French
fr
Italian
it
Russian
ru
Chinese (Traditional)   
zh-Hant
Chinese (Simplified) 
zh-Hans
Turkish
tr
Dutch
nl
Danish
da
Portuguese (Portugal)  
pt-PT
Japanese
ja

To add any of the other 34 languages to your app, perform the following steps:
  1. Download the strings bundle from here.
  2. Remove the lproj files of the languages that are not required for your app.
  3. Add the bundle to your project.


Customizing UI Strings

The ASAP SDK facilitates customization of the text that appears on the different screens of the add-on. The text includes UI labels for help modules, error messages, and general information. To change the text, perform the following steps:
  1. Create a bundle titled ASAPStrings.bundle in the Xcode project of your app. The path to access this bundle is: Application-bundle/ASAPStrings.bundle.
  2. Create a new lproj file with the language code as the filename and customize the values of the keys, as required. You can customize the prominent keys listed below or all the keys in the languages bundle.
  3. Add this new lproj file to the ASAPStrings bundle.
Each language needs a unique lproj file. To customize the strings in each language that you want to support in your add-on, repeat steps 2 and 3 as many times as required.

The following table lists some of the prominent keys in the default ASAPLocalizable.strings file.

Key
Default Text
Description
DeskPortal.Dashboard.Heading
"Welcome"
Text that appears on the help center dashboard
DeskPortal.Dashboard.helpcenter.title
"Knowledge Base"
Title of the Knowledge Base module icon on the dashboard
DeskPortal.Dashboard.helpcenter.description
"Browse our extensive repository of help articles"
Text that describes the Knowledge Base
DeskPortal.Dashboard.community.title
"Community"
Title of the user community module icon on the dashboard
DeskPortal.Dashboard.community.description
"Find and share solutions with the user community"
Text that describes the user community
DeskPortal.Dashboard.addticket.title
"Submit Ticket"
Title of the ticket submission module icon on the dashboard
DeskPortal.Dashboard.addticket.description
"Seek help from our agents"
Text that describes the ticket submission screen
DeskPortal.Dashboard.myticket.title
"My Tickets"
Title of the my tickets icon on the dashboard
DeskPortal.Dashboard.myticket.description
"View and manage tickets that you submitted"
Text that describes the my tickets screens
DeskPortal.Helpcenter.article.detail.relatedtitle
"Related Articles"
Text that appears below any help article in the Knowledge Base
DeskPortal.Helpcenter.article.detail.vote.description
"Was this article helpful?"
Text that seeks feedback from the user
DeskPortal.Helpcenter.feedback.title
"Feedback"
Title of the feedback form
DeskPortal.Helpcenter.feedback.description
"We're sorry the article wasn't helpful."
Text that appears when a user downvotes an article
DeskPortal.Myticket.option.closeticket
"Close Ticket"
Text for option that lets the user close a ticket they submitted
DeskPortal.Error.message.reload
"Retry"
Error message that appears if ticket submission fails
DeskPortal.Network.failed.error.message
"Check your internet connection"
Error message that indicates loss of connectivity
DeskPortal.Dashboard.livechat.title
"Live Chat"
Title of the live chat module on the help center dashboard
DeskPortal.Helpcenter.category.subheading
"Section"
Text that appears if only one article category exists in the Knowledge Base
DeskPortal.Helpcenter.categories.subheading
"Sections"
Text that appears if multiple article categories exist in the Knowledge Base
DeskPortal.Helpcenter.article.detail.title
"FAQs"
Title of the individual article screen
DeskPortal.Addticket.title
"Add Ticket"
Title of the ticket submission form
DeskPortal.Myticket.comment.option.title
"Comment Actions"
Title of the options menu that appears when a user adds a comment to a ticket
DeskPortal.Myticket.option.editcomment
"Edit Comment"
Text for option that lets the user edit a comment they made
DeskPortal.Helpcenter.article.subheading
"Article"
Text that appears if only one article exists under an article category
DeskPortal.Helpcenter.articles.subheading
"Articles"
Text that appears if multiple articles exist under an article category

Enabling Notifications

You can configure the ASAP add-on to send notifications to end-users when an agent responds via chat. The key component in making this possible in the SDK is an Apple Push Notification service (APNs) certificate in the .p12 format.
To generate a .p12 file of the APNs certificate, perform the following steps.
  1. Create and download an APNs certificate from Apple's developer portal.
  2. Double-click the certificate. This action automatically imports it to the Keychain Access application.
  3. Locate and expand the certificate in Keychain Access. The corresponding key for the certificate appears.
  4. Select both the certificate and the key and right-click on them. A context menu appears.
  5. Click the export option. A dialog box appears.
  6. In this dialog box, make sure that .p12 is selected in the File Format drop-down list and click Save.
  7. Enter a password to access the file and click OK. The certificate is now exported as a .p12 file.
Next, you must enable push notifications in the Zoho Desk ASAP setup page. Here's how you do this. On the setup page for the add-on in Zoho Desk, upload the .p12 file you created and the password to access the file. Next, configure the add-on to invoke the enablePushNotification: API call inside the application:didRegisterForRemoteNotificationsWithDeviceToken: method in the AppDelegate.
To perform this configuration, include the following method in the app code.
Swift
func application(_ application: UIApplication,didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
   let token = deviceToken.reduce("", {$0 + String(format: "%02X", $1)}).uppercased()
   ZohoDeskPortalSDK.enablePushNotification(deviceToken:token, mode: .production)
}
Objective-C
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken{
   NSString * token = [[[[deviceToken description]
   stringByReplacingOccurrencesOfString: @"<" withString: @""]
   stringByReplacingOccurrencesOfString: @">" withString: @""]
   stringByReplacingOccurrencesOfString: @" " withString: @""];
   [ZohoDeskPortalSDK enablePushNotificationWithDeviceToken:token isTestDevice:NO mode:APNSModeProduction];
}
Note : You can verify if notifications are sent accurately by testing the functionality in development mode. To switch to development mode, replace ".production" in the code snippet above with ".sandbox". Make sure to switch back to production mode before deploying the app for end-customer use.
Next, you must configure the SDK to automatically invoke the didReceiveRemoteNotification: method in the AppDelegate when a push notification is received. Then, for the SDK to process the notification received and perform the corresponding operation, the processRemoteNotification method in the SDK must be invoked with details of the notification, as follows.
Swift
import ZohoDeskPortalConfiguration 
...
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any]) {
   ZDPortalConfiguration.processRemoteNotification(userInfo: userInfo)
}
Objective-C
@import ZohoDeskPortalConfiguration;
...   
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler{
   [ZDPortalConfiguration processRemoteNotificationWithUserInfo:userInfo];
}

Displaying Details of Anonymous Users to Agents

When an anonymous user contacts customer support via chat, their details usually do not appear on the agent's screen. However, you can configure the ASAP add-on to display these details after receiving them from the user.
To configure this setting, use the following method.
Swift
import ZohoDeskPortalChat
...
ZDPortalChat.setGuestUser(email:<#Guest_User_Email#>, displayName:<#Guest_User_DisplayName#>", phoneNumber: <#Guest_User_PhoneNumber#>")
Objective-C
@import ZohoDeskPortalChat;
...
[ZDPortalChat setGuestUserWithEmail:<#Guest_User_Email#>displayName:<#Guest_User_DisplayName#>phoneNumber:<#Guest_User_PhoneNumber#>];
Additionally, agents can convert chat conversations into tickets, if more interactions with the user are required later. The email ID is a mandatory parameter to make this conversion possible.

Programmatically Adding Tickets

While end-users can manually submit tickets through the ASAP add-on, you can also configure your app to automatically record tickets when certain events occur in the app. For instance, if you run a clothing business and your app fails to load the For Women screen when a user tries to access it, this failure instance can be automatically recorded as a ticket in your help desk. The user would not need to visit your help center and manually submit a ticket.
To make this automatic submission of tickets possible, incorporate the following methods in your app code.
Swift
import ZohoDeskPortalAPIKit
Objective-C
@import ZohoDeskPortalAPIKit;
To fetch the IDs of the departments in your help desk portal, use the following method.
Swift
ZohoDeskPortalSDK.getDepartments(onCompletion: { (departments, error) in
   // on success, departments will return an array, error will return nil
   // on failure, error will return a value, departments will return nil
}
Objective-C
ZohoDeskPortalSDK getDepartmentsOnCompletion:^(NSArray * departments, NSError * error) {
   // on success, departments will return an array, error will return nil
   // on failure, error will return a value, departments will return nil
}];
To fetch information on the products configured in a department, use the following method.
Swift
ZohoDeskPortalSDK.getProducts(inDepartmentID: String, [String: Any]?) { (products, error) in 
   // on success, products will return an array, error will return nil
   // on failure, error will return a value, products will return nil
}
Objective-C
[ZohoDeskPortalSDK getProductsInDepartmentID:<#NSString#>params:<#NSDictionary#>onCompletion:^(NSArray * products, NSError * error) {
   // on success, products will return an array, error will return nil
   // on failure, error will return a value, products will return nil
}];
To fetch the fields configured in the ticket layout of a department, use the following method.
Swift
ZohoDeskPortalSDK.Ticket.getFields([String: Any]?) { (fields, error) in 
   // on success, fields will return an array, error will return nil
   // on failure, error will return a value, products will return nil
}
Objective-C
[ZohoDeskPortalSDKTicket getFields:<#(NSDictionary * _Nullable)#>onCompletion:^(NSArray * fields, NSError * error) {
   // on success, fields will return an array, error will return nil
   // on failure, error will return a value, fields will return nil
}];
To include a file attachment in the ticket, use the following method.
Swift
ZohoDeskPortalSDK.Ticket.addAttachment(with:<#Data#>, andName:<#String#>, using: <#ZDPUploaderDelegate?#>) { (attachment, error) in 
   // on success, attachment will return a value, error will return nil
   // on failure, error will return a value, attachment will return nil
}
Objective-C
[ZohoDeskPortalSDKTicket addAttachmentWith:<#NSData#>andName:<#NSString#>using:<#(id _Nullable)#>onCompletion:^(ZDPortalAttachment * attachment, NSError * error) {
   // on success, attachment will return a value, error will return nil
   // on failure, error will return a value, attachment will return nil
}];
To make this automatic submission of tickets possible, incorporate the following method in your app code. You have to call different methods to post tickets for authenticated and unauthenticated users.
Swift
if ZohoDeskPortalSDK.isUserLoggedIn { 
    ZohoDeskPortalSDK.Ticket.add(withFields:<#T##[String : Any]#>) { (ticket, error) in
       // on success, ticket will return an object, error will return nil
       // on failure, error will return a value, ticket will return nil
    }
} else {
    ZohoDeskPortalSDK.Ticket.addAsGuest(withFields: <#T##[String : Any]#>) { (ticketNumber, error) in
       // on success, ticketNumber will return a string value, error will return nil
       // on failure, error will return a value, ticketNumber will return nil
   }
}
Objective-C
if (ZohoDeskPortalSDK.isUserLoggedIn) {
    [ZohoDeskPortalSDKTicket addWithFields:<#(NSDictionary * _Nonnull)#>onCompletion:^(ZDPTicket * ticket, NSError * error) {
       // on success, ticket will return an object, error will return nil
       // on failure, error will return a value, ticket will return nil
    }];
}else{
    [ZohoDeskPortalSDKTicket addAsGuestWithFields:<#(NSDictionary * _Nonnull)#>onCompletion:^(NSString * ticketNumber, NSError * error) {
       // on success, ticketNumber will return a string value, error will return nil
       // on failure, error will return a value, ticketNumber will return nil
    }]
}
Note : EmailAddress, Subject, and DepartmentID are mandatory parameters in the method call

Customizing the Community module

These methods help you display your user community and all associated content on the ASAP add-on.
Custom-Configuring Community Actions
Users can perform a range of actions, including editing and deleting topics; and adding, editing, and deleting comments, in the community module.
The following method helps you define which actions must be allowed and which actions must be disallowed when users access the community through the ASAP add-on.
Swift
ZDPCommunityConfiguration.isTopicEditAllowed = <#Bool#>
ZDPCommunityConfiguration.isTopicDeleteAllowed = <#Bool#>
ZDPCommunityConfiguration.isReplyAllowed = <#Bool#>
ZDPCommunityConfiguration.iReplyEditAllowed = <#Bool#>
ZDPCommunityConfiguration.isReplyDeleteAllowed = <#Bool#>
Objective-C
ZDPCommunityConfiguration.isTopicEditAllowed = <#Bool#>;
ZDPCommunityConfiguration.isTopicDeleteAllowed = <#Bool#>;
ZDPCommunityConfiguration.isReplyAllowed = <#Bool#>; 
ZDPCommunityConfiguration.iReplyEditAllowed = <#Bool#>;
ZDPCommunityConfiguration.isReplyDeleteAllowed = <#Bool#>;
Getting the Most Popular Topics
The following API fetches the forum topics with the most number of likes.
Swift
ZohoDeskPortalSDK.Community.getMostPopularTopics(<#[String:Any]?#>) { (result: Result<[ZDPCommunity.TopicDetail], ZDPError>) in 
   // switch on result to get array of topics on success
}
Objective-C
[ZohoDeskPortalSDKCommunity getMostPopularTopics:<#(NSDictionary * _Nullable)#>onCompletion:^(NSArray * topics, NSError * error) {
   // on success, topics will return an array, error will return nil
   // on failure, error will return a value, topics will return nil
}];
Here are some of the parameter keys and the types of values expected. For more information on all keys and values, refer to the API documentation.
  1. categoryId - string - ID of the community category from which the topics must be fetched. If you want to include all categories, pass the value "-1".
  2. filterType - string - Type of forum topic. Values allowed are: QUESTION, IDEA, ANNOUNCEMENT, PROBLEM, and DISCUSSION.
  3. from - int - Index number, starting from which the topics must be fetched. Value starts from 1.
  4. limit - int - Number of topics to fetch
  5. includeCount - Boolean - Parameter that specifies whether the number of topics fetched must be displayed or not
Getting the Most Discussed Topics
The following API fetches the forum topics with the most number of comments.
Swift
ZohoDeskPortalSDK.Community.getMostDiscussedTopics(<#[String:Any]?#>) { (topics, error) in 
   // on success, topics will return an array, error will return nil
   // on failure, error will return a value, products will return nil
}
Objective-C
[ZohoDeskPortalSDKCommunity getMostDisuccedTopics:<#(NSDictionary * _Nullable)#>onCompletion:^(NSArray * topics, NSError * error) {
   // on success, topics will return an array, error will return nil
   // on failure, error will return a value, topics will return nil
}];
Here are some of the parameter keys and the types of values expected. For more information on all keys and values, refer to the API documentation.
  1. categoryId - string - ID of the community category from which the topics must be fetched. If you want to include all categories, pass the value "-1".
  2. filterType - string - Type of forum topic. Values allowed are: QUESTION, IDEA, ANNOUNCEMENT, PROBLEM, and DISCUSSION.
  3. from - int - Index number, starting from which the topics must be fetched. Value starts from 1.
  4. limit - int - Number of topics to fetch
  5. includeCount - Boolean - Parameter that specifies whether the number of topics fetched must be displayed or not

Customizing the Tickets Module

These methods help you configure the Submit Ticket form the way you want, on the ASAP add-on.
Hiding Fields in the Submit Ticket Form
The Submit Ticket form in your ASAP add-on displays the same fields configured in the ticket layout in your Zoho Desk portal. If you want to hide any of the fields in the form, you can do so using the setFieldsListTobeShown() method.
Swift
ZDPortalSubmitTicket.setFieldsListTobeShown(fields: <#[ZDVisibleTicketField]#>)
Objective-C
[ZDPortalSubmitTicket setFieldsListTobeShownWithFields:<#(NSArray * _Nonnull)#>];
Here, ZDVisibleTicketField is a class containing two properties: departmentId (an optional string), and an array of field names. You must pass the list of fields (apiNames) as strings in this method. You might also have to pass the departmentId key, depending on the department mapping of the add-on. For instance, if the add-on is configured for a specific department, you need not pass the departmentId key. If the add-on is configured for multiple departments, you must pass the departmentId key to ensure department-ticket fields mapping in the Submit Ticket form. After you include this method, the form displays only the fields you passed in the method. However, keep in mind that mandatory fields will not be hidden even if you do not pass their names in the method.
Hiding Mandatory Fields in the Submit Ticket Form
If you absolutely want to hide a mandatory field in the form, you can do so, provided the value of the field is pre-filled. To do this, you must use the preFillTicketFields() method.
The preFillTicketFields() method proves useful when you want to pre-populate fields with values, such as auto-generated IDs or OS version of devices.
To use this method, you must pass the list of PreFillTicketField objects. You should also pass the departmentId key, depending on the department mapping of the add-on.
Swift
ZDPortalSubmitTicket.preFillTicketFields(forForms: <#[ZDCustomizedTicketForm]#>)
Objective-C
[ZDPortalSubmitTicket preFillTicketFieldsForForms:<#[ZDCustomizedTicketForm]#>];
Here, ZDCustomizedTicketForm is a class containing two properties: departmentId (an optional string), and an array of customized ticket fields. Just like in the case of the setFieldsListTobeShown() method, if the add-on is configured for a specific department, you need not pass the departmentId key. If the add-on is configured for multiple departments, you must pass the departmentId key to ensure department-fields mapping.
The ZDCustomizedTicketField object contains three main properties:
  1. fieldApiName - string - apiName of the ticket field. You can retrieve the apiName of each field using the getTicketForm() method.
  2. fieldValue - object
    1. For multiselect fields, pass the values allowed, as a comma(,) separated string.
    2. For pick list fields, pass one of the values allowed, as a string.
    3. For date fields, pass the value as a string in the MM/dd/yyyy format.
    4. For dateTime fields, pass the value as a string in the MM-dd-yyyy hh:mm aa format.
    5. For Boolean fields, pass a String value("true"/"false").
    6. For all other field types, pass the values as string objects.
    7. Make sure that the values you pass here to the maxlength and decimal restrictions defined for the field.
  3. isEditable - Boolean - Key that defines if the value in the field is editable or not
Note : For more clarity check the sample here.
Custom-Configuring Ticket Actions
Users can perform a range of actions, including replying to, commenting on, and closing tickets.
The following method helps you define which actions must be allowed and which actions must be disallowed when users access the ticket submission screen on the ASAP add-on.
Swift
ZDPTicketConfiguration.isCommentAllowed = <#Bool#>
ZDPTicketConfiguration.isCommentDeleteAllowed = <#Bool#>
ZDPTicketConfiguration.isCommentEditAllowed = <#Bool#>
ZDPTicketConfiguration.isReplyAllowed = <#Bool#>
ZDPTicketConfiguration.isTicketUpdateAllowed = <#Bool#>
Objective-C
ZDPTicketConfiguration.isCommentAllowed = YES;
ZDPTicketConfiguration.isCommentDeleteAllowed = YES;
ZDPTicketConfiguration.isCommentEditAllowed = YES;
ZDPTicketConfiguration.isReplyAllowed = YES;
ZDPTicketConfiguration.isTicketUpdateAllowed = YES;

Others

These methods help you perform a variety of other actions in your ASAP add-on.
Updating User Details
The following API helps update the details of users added to your help desk portal.
Swift
import ZohoDeskPortalAPIKit
...
var body = [String : Any]()
body["displayName"] = "displayName"
body["mobile"] = "123456"

ZohoDeskPortalSDK.updateUserInformation(with: body) { (profile, error) in {
   // on success only profile will return a value, error will return nil
   // on failure only error will return a value, profile will return nil
}
Objective-C
NSMutableDictionary * body = [NSMutableDictionary new];
[body setObject:@"displayName" forKey:@"displayName"];
[body setObject:@"123456" forKey:@"mobile"];

[ZohoDeskPortalSDK updateUserInformationWith:body onCompletion:^(Profile * profile, NSError * error) {
   // on success only profile will return a value, error will return nil
   // on failure only error will return a value, profile will return nil
}];
Params
Dictionary [String : Any] data - Key and value pair. Keys included are: twitter, phone, facebook, name, displayName, mobile, countryLocale, and timeZone.

SDK Logging

The ASAP SDK also provides you with the option to fix errors that occur while using the add-on. This is made possible by SDK logging. By default, logs are enabled for the SDK. You can check the console log for errors and take necessary action. You can disable logs if you do not want them.
To disable logging for the SDK, include the following code snippet.
Swift
import ZohoDeskPortalAPIKit
...
ZohoDeskPortalSDK.disableLogs()
Objective-C
@import ZohoDeskPortalAPIKit;
...
[ZohoDeskPortalKit disableLogs]

Release Notes

v2.0.2
  1. Introduced the option to display Knowledge Base deeplinks with custom titles on the navigation bar.
  2. Updated default modal presentation style to automatic on devices running iOS 13 and above. 
  3. Fixed a critical issue identified in the Chat module. 
  4. Fixed bugs and made performance improvements.
v2.0.1
  1. Fixed a critical issue identified in the Community module.
v2.0
  • Provided support for having a multilingual Knowledge Base. 
  • Provided support for iOS 14. 
  • Included Conditional Layouts and Ticket Templates in the Add Ticket module.
  • Added an API provider as a separate lightweight framework containing all APIs available. You can build a custom UI and incorporate the APIs into it.
  • Incorporated dark mode.
  • Made the text in the SDK more accessible by configuring the SDK's font size to match that of the system.
  • Added the option to enable large titles for iOS 11 and above.
  • Embedded the Search bar within the navigation bar for iOS 11 and above.
__________________________________

SDK v1.0

Introduction

The ASAP SDK for iOS makes help available within quick reach for the end-users of your iOS app. Using this SDK, you can create and customize an add-on that resides within your app and provides end-users with easy access to your:
  • Customer support team (to raise tickets or chat with support agents)
  • Knowledge Base (to access help articles)
  • User community (to interact with other users of the app)
What this addition means for end-users is that they do not have to exit your app and visit your website or send an email to contact you for support. They can easily seek help right from within your app, thereby saving time and enjoying a superior customer experience.
The ASAP SDK supports iOS 9 and all later versions.

Setting Up the SDK in Zoho Desk

The first step to including the ASAP add-on within your iOS app is to create and register the add-on in Zoho Desk.
To create the add-on, perform the following steps.
  1. Go to this path in Zoho Desk: Setup → Channels → ASAP.
  2. In the Setup pane on the left, under ASAP, click the + button next to Mobile. The Create Mobile Add-On page appears. 

  3. Under Add-On Details, configure the following settings:
    • Name: Name for the ASAP add-on. This name is only for reference; it does not appear anywhere on the app UI.
    • Available for: Departments for which this ASAP add-on must be enabled
    • Bundle ID: In the iOS field, enter the bundle ID of your iOS app. (You can retrieve the bundle ID from the General tab within the project target of your app settings.)
      Note : Bundle ID is mandatory for enabling Live Chat and sending push notifications.
    • Live Chat: Toggle switch for enabling/disabling Live Chat.
      Note : The Live Chat component reflects the settings configured for the chat channel in your help desk portal. Therefore, any change required must be done via the Setup page in Zoho Desk.
    • Push Notifications :Toggle switch for enabling/disabling push notifications. For more details, refer to the Enabling Notifications section in this document.
      Note : JWT-based user authentication is mandatory for enabling notifications. Push notifications related to tickets are not sent to anonymous users.
    • Authentication Method: User authentication setting for the add-on
      • Anonymous - In this method, end-users are considered guest users. They can only submit tickets, view posts in the user community, and chat with a customer support agent. They cannot view the tickets they submitted or actively participate in the user community.
      • JWT - In this method, end-users are considered authenticated users. In addition to the activities that guest users can perform, authenticated users can also view and track the status of the tickets they submitted, reply/comment to a ticket, and actively participate in the user community (with rights to perform actions, such as following a topic, adding a topic, and adding a comment to existing posts).
  4. Click Save.
A new section called Code Snippet appears. This section displays the Org ID, App ID, and Deployment type details of your app. These details are vital for initializing the ASAP SDK in your app.

Integrating the SDK with Your App

The next step is to integrate the ASAP SDK with your iOS app.
You can follow either of the following two methods to perform this step.
Automated Integration Using CocoaPods
This method involves use of CocoaPods, a dependency manager that lets you add third-party frameworks and libraries to Xcode projects. For information on how to install CocoaPods, visit this link.
As the first step to integrating the SDK with your app using CocoaPods, you must create a Podfile for your project. If you have not created a Podfile already, perform the following steps:
  1. In Terminal, navigate to the top-level folder of your project (the folder with the xcodeproj file).
  2. Execute the $ pod init command.
  3. Then, open the Podfile in Xcode by executing the open -a Xcode Podfile command. The content should look as follows:
    # Uncomment this line to define a global platform for your project
    # platform :ios, '9.0'
    # Uncomment this line if you're using Swift
    # use_frameworks!
    target 'My Sample App' do
    end
  4. If you use Swift, uncomment the use_frameworks! line.
Next, you must add the Zoho Desk Portal SDK to the Podfile and install the SDK in your project. To do this, perform the following steps. 
  1. Add the following code to the do block of the Podfile.
    target 'My Sample App' do
    pod 'ZohoDeskPortalSDK', :git => 'https://github.com/zoho/ZohoDeskPortalSDK.git'
    end
  2. Save the Podfile.
  3. Execute the $ pod install command in Terminal.
You have now successfully integrated the SDK with your app using CocoaPods. What this technically means is that your project contains a dependency managed by CocoaPods. So, going forward, you must open your project in Xcode from the .xcworkspace file and not the .xcodeproj file. 
For more information on how to use CocoaPods, click here
Note 
If you use Swift for developing your app, add one of the following lines to the Podfile, based on the Xcode version used.
Manual Integration
If you do not want to integrate the ASAP SDK with your app using CocoaPods, you can perform a manual integration. To do this, perform the following steps.
  1. Download the ZohoDeskPortalSDK from this link and Mobilisten SDK from this link.
  2. Decompress both the zip files. Then, drag and drop the ZohoDeskPortalSDK.framework and Mobilisten.framework files to the Embedded Binaries section of your Xcode project bundle.
  3. Then, create a new run script phase from your app target's Build Phases tab. Paste the following code snippet in the script text field of the run script that appears. (Make sure that this script appears last in the Build Phases tab.) 
    bash "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/ZohoDeskPortalSDK.framework/strip-frameworks.sh"
    This script helps overcome a bug related to archiving universal binaries in apps submitted to the App Store. Make sure that the VALID_ARCHS build setting of your app does not contain i386 or x86_64 in the release configuration. 
Note : Make sure to add the  NSPhotoLibraryUsageDescriptionNSCameraUsageDescription, and NSBluetoothPeripheralUsageDescription keys in the info.plist file of your app. 

Initializing the SDK in Your App

Next, you initialize the ASAP SDK in your app.
The following three keys are crucial in this step:
  • Org ID
  • App ID
  • Datacenter
The values of these keys appear under the Code Snippet section in the setup page of the ASAP add-on in Zoho Desk.
To initialize the SDK in your app, perform the following steps.
  1. Import the Zoho Desk Portal SDK framework into the AppDelegate file in your project.
    Swift
    import ZohoDeskPortalSDK
    Objective-C
    @import ZohoDeskPortalSDK;
  2. Paste the following initialization code into the application method with the didFinishLaunchingWithOptions argument.
    Swift
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
       let config = ZDPortalConfiguration()
       config.enableHelpCenter = true
       config.enableCreateTicket = true
       config.enableMyTicket = true
       config.enableCommunity = false
       ZohoDeskPortalSDK.initializeSDK(<#ORGID#>, appId: <#APPID#>, dataCenter: <#dataCenterValue#>, configuration: <#config#>)
       return true
    }
    Objective-C
    - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
        ZDPortalConfiguration * config = [[ZDPortalConfiguration alloc]init];
        config.enableHelpCenter = YES;
        config.enableCommunity = YES;
        config.enableCreateTicket = YES;
        config.enableMyTicket = YES;
        [ZohoDeskPortalSDK initializeSDK:<#ORGID#> appId:<#APPID#> dataCenter:<#dataCenterValue#> configuration:<#config#>];
        return YES;
    }
Note
: Datacenter values according to the deployment type are as follows:
CN - ZDDataCenter.CN
EU - ZDDataCenter.EU
US - ZDDataCenter.US
IN - ZDDataCenter.IN

Displaying Help Components

Given below are the methods for displaying individual help components on the SDK UI. These methods display the components according to their default configuration and the settings configured in your Zoho Desk portal. The components in the default configuration vary according to the Zoho Desk edition in use.
SDK Dashboard
The SDK dashboard is the screen through which end-users access your help center. This dashboard displays icons/buttons that provide access to your Knowledge Base, user community, customer support team (through the ticket submission form), tickets list (list of tickets submitted by users who are logged in), and live chat (to interact with a customer support agent in real time).
Note : Live chat is not enabled by default in the SDK UI. You must first enable live chat in your Zoho Desk portal.
The following methods display the SDK dashboard.
Swift
ZohoDeskPortalSDK.showHomePage(controller: self)
Objective-C
[ZohoDeskPortalSDK showHomePageWithController:self];
self is the UIViewController instance that triggers the SDK dashboard.

You also have the option to not display the SDK dashboard on your app and still provide access to individual help components. The following methods help you display the individual components with their default configuration.
SDK Dashboard with overridded configuration
The following method displays the SDK dashboard with its configuration overridden.
Swift
let config = ZDPortalConfiguration()
config.enableHelpCenter = true // disable/enable the Help center (Knowledge Base).
config.enableCommunity = false // disable/enable the Community.
config.enableCreateTicket = true // disable/enable the CreateTicket.
config.enableMyTicket = true // disable/enable My Tickets.
ZohoDeskPortalSDK.showHomePage(controller: self, withConfiguration: config)
Objective-C
ZDPortalConfiguration * config = [[ZDPortalConfiguration alloc]init];
config.enableHelpCenter = YES; // disable/enable the Help center (Knowledge Base).
config.enableCommunity = NO; // disable/enable the Community.
config.enableCreateTicket = YES; // disable/enable the CreateTicket.
config.enableMyTicket = YES; // disable/enable My Tickets.
[ZohoDeskPortalSDK showHomePageWithController:self withConfiguration:config];
self is the UIViewController instance that triggers the SDK dashboard.
In this example code snippet, the dashboard is configured such that the Community component is hidden.
You also have the option to not display the SDK dashboard on your app and still provide access to individual help components. The following methods help you display the individual components with their default configuration.
Live Chat
Live chat is the component through which end-users can interact with a customer support agent in real time.
The following methods display the live chat component.
Swift
ZohoDeskPortalSDK.showLiveChat(controller: self)
Objective-C
[ZohoDeskPortalSDK showLiveChatWithController:self];
self is the UIViewController instance that triggers live chat.
Help Center (Knowledge Base)
Help center is the component through which end-users can access help articles in your Knowledge Base.
The following methods display the help center (Knowledge Base).
Swift
ZohoDeskPortalSDK.showHelpCenter(controller: self)
Objective-C
[ZohoDeskPortalSDK showHelpCenterWithController:self];
self is the UIViewController instance that triggers the Knowledge Base.
Submit Ticket
Submit Ticket is the screen through which end-users can submit their questions/requests as support tickets.
The following methods display the Submit Ticket Screen.
Swift
ZohoDeskPortalSDK.addTicket(controller: self)
Objective-C
[ZohoDeskPortalSDK addTicketWithController:self];
self is the UIViewController instance that triggers the Submit Ticket screen.
If you want your app to subscribe to the submit ticket event, use the following method, which includes an event callback.
Swift
ZohoDeskPortalSDK.addTicket(controller: self, onCompletion: { (ticketDetail) in
  // The ticketDetail parameter contains the details of the ticket created.
  // Your program logic goes here.
}) { (error) in
  // error creating Ticket
}
Objective-C
[ZohoDeskPortalSDK addTicketWithController:self onCompletion:^(TicketDetailJsonObject * ticket) {
  // The ticketDetail parameter contains the details of the ticket created.
  // Your program logic goes here.
} onError:^(NSError * error) {
    // error creating Ticket
}];
self is the UIViewController instance that triggers the Submit Ticket screen.
The callback object that sends ticket information when a ticket is submitted via the Submit Ticket screen.
Note : If an authenticated user submits a ticket, all ticket details are sent to your app. If a guest user submits a ticket, only the ticket number is sent.
My Tickets
My Tickets is the screen through which end-users can access, track, and edit the tickets they submitted.
The following methods display the My Tickets screen.
Swift
ZohoDeskPortalSDK.ticketList(controller: self)
Objective-C
[ZohoDeskPortalSDK ticketListWithController:self];
self is the UIViewController instance that triggers the My Tickets screen.
User Community
User community is the component through which end-users can access discussion forums and interact with other users for sharing knowledge.
The following methods display the user community.
Swift
ZohoDeskPortalSDK.showCommunity(controller: self)
Objective-C
[ZohoDeskPortalSDK showCommunityWithController:self];
self is the UIViewController instance that triggers the user community.

Authenticating Users in the SDK

To access the tickets they submitted, end-users of your app must have an identity so that they can authenticate themselves as a user of the Zoho Desk portal. This authentication is made possible in Zoho Desk via the JSON Web Token (JWT).
Zoho Desk supports two types of authentication: Anonymous and JWT.
  • Anonymous - In this type, end-users are considered guest users. They can only submit tickets, view posts in the user community, and chat with a customer support agent. They cannot view the tickets they submitted or actively participate in the user community.
  • JWT - In this type, end-users are considered authenticated users. In addition to the activities that guest users can perform, authenticated users can also view the tickets they submitted and actively participate in the user community (with rights to perform actions, such as following a topic, adding a topic, and adding a comment to existing posts).
For detailed information on how to configure JWT-based user authentication in the ASAP SDK, refer to this document.
The following code snippet authenticates users in the SDK.
Swift
if !ZohoDeskPortalSDK.isZDUserSignedIn{
  ZohoDeskPortalSDK.set(jwtUserIdentifier: <#Remote user Token#>, onCompletion: {
  }, onError: { (error) in
  })
}else{
  //User already signed into SDK
}
Objective-C
if (![ZohoDeskPortalSDK isZDUserSignedIn]){
  [ZohoDeskPortalSDK setWithJwtUserIdentifier:<#Remote user Token#> onComplition:^{
    
  } onError:^(NSError * error) {
  }];
}else{
    //User already signed into SDK
}
ZohoDeskPortalSDK.isZDUserSignedIn is of Boolean type, where true means the user is logged in and false means the user is an anonymous user.
Therefore, you must configure the add-on such that:
  • if the value returned is true, the user can continue performing their task as an authenticated user in the add-on
  • if the value returned is false, ZohoDeskPortalSDK.set is called to login the user
If the user is not authenticated, an error message is thrown via a call-back function.
Logging Users out from the SDK
Swift
ZohoDeskPortalSDK.logout()
Objective-C
[ZohoDeskPortalSDK logout];
After this method is called, the authenticated user is treated as an anonymous user.

Clearing Local Data

All the data stored locally in the device is automatically cleared when an authenticated user signs out from the ASAP add-on.
However, if local data needs to be cleared for anonymous users too, use the following method.
Swift
ZohoDeskPortalSDK.clearAllLocalData()
Objective-C
[ZohoDeskPortalSDK clearAllLocalData];

Hiding Help Components

By default, the ASAP SDK displays all help components available, depending on the Zoho Desk edition in use and settings configured in the Zoho Desk portal. However, you can also show or hide individual help components on your app using ZDPortalConfiguration.
The following code snippets illustrate how to disable individual help components in an add-on.
Swift
let config = ZDPortalConfiguration()
config.enableHelpCenter = false // disable the Help center (Knowledge Base).
config.enableCommunity = false // disable the Community.
config.enableCreateTicket = false // disable the CreateTicket.
config.enableMyTicket = false // disable My Tickets.
config.showLeftMenu = true // enable/disable left Menu
Objective-C
ZDPortalConfiguration * config = [[ZDPortalConfiguration alloc]init];
config.enableHelpCenter = NO; // disable the Help center (Knowledge Base).
config.enableCommunity = NO; // disable the Community.
config.enableCreateTicket = NO; // disable the CreateTicket.
config.enableMyTicket = NO; // disable My Tickets.
config.showLeftMenu = YES; // enable/disable left Menu
Note : You must send the configuration object in the ZohoDeskPortalSDK.initializeSDK function. For more details, refer to the Initializing the SDK in Your App section of this document.

Customizing the Add-On UI

The ASAP SDK provides you with the option to customize the UI of the add-on as required.
Predefined Themes
The SDK UI comes with two predefined themes: white and black. The following methods help you apply these themes.

Methods for Applying the White Theme (Default)
Swift
ZDTheme.applyTheme(theme: .white)
Objective-C
[ZDTheme applyThemeWithTheme:ZDThemeTypeWhite];
Methods for Applying the Black Theme
Swift
ZDTheme.applyTheme(theme: .dark)
Objective-C
[ZDTheme applyThemeWithTheme:ZDThemeTypeDark];
Customized Themes
You can also customize the theme of each individual screen--article page, ticket submission page, ticket listing page, and so on--of the add-on UI, using our APIs.
Below is an example of a method that helps you customize the theme of the article page in the Knowledge Base.
Swift
let articleTheme =  ZDThemeArticle.init()
articleTheme.tintColor = UIColor.white
articleTheme.primaryTextColor = UIColor.white
articleTheme.secondryTextColor = UIColor(red:0.12, green:0.13, blue:0.15, alpha:1.00)
articleTheme.primaryBackgroundColor = UIColor(red:0.12, green:0.13, blue:0.15, alpha:1.00)
articleTheme.secondryBackgroundColor = UIColor(red:0.12, green:0.13, blue:0.15, alpha:1.00)
articleTheme.cellSeporatorColor = UIColor(red:0.12, green:0.13, blue:0.15, alpha:1.00)
articleTheme.headerColor = UIColor(red:0.13, green:0.18, blue:0.15, alpha:1.00)
Objective-C
ZDThemeArticle * articleTheme = [ZDThemeArticle init];
articleTheme.tintColor = [UIColor whiteColor];
articleTheme.primaryTextColor = [UIColor whiteColor];
articleTheme.secondryTextColor = [UIColor colorWithRed:0.12 green:0.13 blue:0.15 alpha:1.00];
articleTheme.primaryBackgroundColor = [UIColor colorWithRed:0.12 green:0.13 blue:0.15 alpha:1.00];
articleTheme.secondryBackgroundColor = [UIColor colorWithRed:0.12 green:0.13 blue:0.15 alpha:1.00];
articleTheme.cellSeporatorColor = [UIColor colorWithRed:0.12 green:0.13 blue:0.15 alpha:1.00];
articleTheme.headerColor = [UIColor colorWithRed:0.12 green:0.13 blue:0.15 alpha:1.00];
Note : You can similarly customize the articles listing page and ticket submission page. However, keep in mind that such customization will override the SDK theme.
Customizing the Navigation Bar and Status Bar
To customize the theme of the navigation bar and status bar of the ASAP add-on, use the following code:
Swift
ZDNavigationTheme.navigationBarColor = UIColor.blue
ZDNavigationTheme.titleColor = UIColor.white
ZDNavigationTheme.barButtonTextColor = UIColor.white
ZDNavigationTheme.translucent = false
ZDNavigationTheme.statusBarApperance = .lightContent
ZDNavigationTheme.backButtonStyle = ZDNavigationBackButtonStyle.icon
Objective-C
[ZDNavigationTheme setNavigationBarColor:[UIColor blueColor]];
[ZDNavigationTheme setTitleColor:[UIColor blueColor]];
[ZDNavigationTheme setBarButtonTextColor:[UIColor blueColor]];
[ZDNavigationTheme setTranslucent:NO];
[ZDNavigationTheme setStatusBarApperance:UIStatusBarStyleLightContent];
[ZDNavigationTheme setBackButtonStyle:ZDNavigationBackButtonStyleIcon];
Using Custom Fonts
The SDK UI offers a set of default fonts, but you can use fonts of your choice if required.
To be able to display custom fonts on the SDK UI, perform these steps first:
  1. Add the font(s) to your project.
  2. Edit the info.plist file of your app to include the Fonts provided by application key.
  3. Under this key, list the file names of all the fonts you want to use in the SDK UI.
After adding the fonts to your project, you can customize the SDK UI to display text in that font.
To display the custom font on your SDK UI, include the following method in your app code
Swift
let font = ZDCustomFont()
font.fontFamilyName = "ProximaNova"
font.regularFontName = "ProximaNova-reg"
font.lightFontName = "ProximaNova-light"
font.boldFontName = "ProximaNova-Bold"
font.mediumFontName = "ProximaNova-Bold"
Objective-C
ZDCustomFont * font = [ZDCustomFont init];
font.fontFamilyName = @"ProximaNova";
font.regularFontName = @"ProximaNova-reg";
font.lightFontName = @"ProximaNova-light";
font.boldFontName = @"ProximaNova-Bold";
font.mediumFontName = @"ProximaNova-Bold";
Note : If you do not use a custom font, the add-on displays the system font by default.

Changing Language Settings

The ASAP SDK supports 12 languages. You can set any language of your choice, based on the geographical location of the end-users of your app.
Below is the code that helps you set the language for the ASAP add-on.
Swift
ZDPortalConfiguration.setSDKLanguage = "en"
Objective-C
ZDPortalConfiguration.setSDKLanguage = @"en";
The table below lists all languages supported.
Language
Locale Code
English
en
German
de
Spanish
es
French
fr
Italian
it
Russian
ru
Chinese
zh
Turkish
tr
Dutch
nl
Danish
da
Portuguese
pt
Japanese
ja

Customizing UI Strings

The ASAP SDK facilitates customization of the text that appears on the different screens of the add-on. The text includes UI labels for help components, error messages, and general information. To change the text, perform the following steps:
  1. Create a bundle titled ASAPStrings.bundle in the Xcode project of your app. The path to access this bundle is: Application-bundle/ASAPStrings.bundle.
  2. From this link, download the lproj file containing the default strings that appear in the SDK UI.
  3. Add the lproj file you downloaded in the previous step to the ASAPStrings bundle.
  4. Open the ASAPLocalizable.strings file within the lproj file and customize the text as required.
Note : Each language has a unique lproj file. To customize the strings in each language that you want to support in the SDK, choose the relevant lproj file while performing step 2 and repeat steps 3 and 4
The table below lists the different keys in the default ASAPLocalizable.strings file.
Key
Default Text
Description
DeskPortal.Dashboard.Heading
"Welcome"
Text that appears on the help center dashboard
DeskPortal.Dashboard.helpcenter.title
"Knowledge Base"
Title of the Knowledge Base module icon on the dashboard
DeskPortal.Dashboard.helpcenter.description
"Browse our extensive repository of help articles"
Text that describes the Knowledge Base
DeskPortal.Dashboard.community.title
"Community"
Title of the user community module icon on the dashboard
DeskPortal.Dashboard.community.description
"Find and share solutions with the user community"
Text that describes the user community
DeskPortal.Dashboard.addticket.title
"Submit Ticket"
Title of the ticket submission module icon on the dashboard
DeskPortal.Dashboard.addticket.description
"Seek help from our agents"
Text that describes the ticket submission screen
DeskPortal.Dashboard.myticket.title
"My Tickets"
Title of the my tickets icon on the dashboard
DeskPortal.Dashboard.myticket.description
"View and manage tickets that you submitted"
Text that describes the my tickets screens
DeskPortal.Helpcenter.article.detail.relatedtitle
"Related Articles"
Text that appears below any help article in the Knowledge Base
DeskPortal.Helpcenter.article.detail.vote.description
"Was this article helpful?"
Text that seeks feedback from the user
DeskPortal.Helpcenter.feedback.title
"Feedback"
Title of the feedback form
DeskPortal.Helpcenter.feedback.description
"We're sorry the article wasn't helpful."
Text that appears when a user downvotes an article
DeskPortal.Myticket.option.closeticket
"Close Ticket"
Text for option that lets the user close a ticket they submitted
DeskPortal.Error.message.reload
"Retry"
Error message that appears if ticket submission fails
DeskPortal.Network.failed.error.message
"Check your internet connection"
Error message that indicates loss of connectivity
DeskPortal.Dashboard.livechat.title
"Live Chat"
Title of the live chat module on the help center dashboard
DeskPortal.Helpcenter.category.subheading
"Section"
Text that appears if only one article category exists in the Knowledge Base
DeskPortal.Helpcenter.categories.subheading
"Sections"
Text that appears if multiple article categories exist in the Knowledge Base
DeskPortal.Helpcenter.article.detail.title
"FAQs"
Title of the individual article screen
DeskPortal.Addticket.title
"Add Ticket"
Title of the ticket submission form
DeskPortal.Myticket.comment.option.title
"Comment Actions"
Title of the options menu that appears when a user adds a comment to a ticket
DeskPortal.Myticket.option.editcomment
"Edit Comment"
Text for option that lets the user edit a comment they made
DeskPortal.Helpcenter.article.subheading
"Article"
Text that appears if only one article exists under an article category
DeskPortal.Helpcenter.articles.subheading
"Articles"
Text that appears if multiple articles exist under an article category

Enabling Notifications

You can configure the ASAP add-on to send notifications to end-users when an agent responds via chat. The key component in making this possible in the SDK is an Apple Push Notification service (APNs) certificate in the .p12 format.
To generate a .p12 file of the APNs certificate, perform the following steps.
  1. Create and download an APNs certificate from Apple's developer portal.
  2. Double-click the certificate. This action automatically imports it to the Keychain Access application.
  3. Locate and expand the certificate in Keychain Access. The corresponding key for the certificate appears.
  4. Select both the certificate and the key and right-click on them. A context menu appears.
  5. Click the export option. A dialog box appears.
  6. In this dialog box, make sure that .p12 is selected in the File Format drop-down list and click Save
  7. Enter a password to access the file and click OK. The certificate is now exported as a .p12 file. 
Next, you must enable push notifications in the Zoho Desk ASAP setup page.
Here's how you do this.
On the setup page for the add-on in Zoho Desk, upload the .p12 file you created and the password to access the file.
Next, configure the add-on to invoke the enablePushNotification: API call inside the application:didRegisterForRemoteNotificationsWithDeviceToken: method in the AppDelegate. 
To perform this configuration, include the following method in the app code.
Swift
func application(_ application: UIApplication,didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
  let token = deviceToken.reduce("", {$0 + String(format: "%02X", $1)}).uppercased()
  ZohoDeskPortalSDK.enablePushNotification(deviceToken:token, mode: .production)
}
Objective-C
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken{
    NSString * token = [[[[deviceToken description]
                                      stringByReplacingOccurrencesOfString: @"<" withString: @""]
                                     stringByReplacingOccurrencesOfString: @">" withString: @""]
                                    stringByReplacingOccurrencesOfString: @" " withString: @""];
    [ZohoDeskPortalSDK enablePushNotificationWithDeviceToken:token isTestDevice:NO mode:APNSModeProduction];
}
Note
  • You can verify if notifications are sent accurately by testing the functionality in development mode. To switch to development mode, replace ".production" in the code snippet above with ".sandbox".
  • Make sure to switch back to production mode before deploying the app for end-customer use.
Next, you must configure the SDK to automatically invoke the didReceiveRemoteNotification: method in the AppDelegate when a push notification is received. 
Then, for the SDK to process the notification received and perform the corresponding operation, the processRemoteNotification method in the SDK must be invoked with details of the notification, as follows.
Swift
func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any]) {
  ZohoDeskPortalSDK.processRemoteNotification(userInfo: userInfo)
 }
Objective-C
- (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler{
    [ZohoDeskPortalSDK processRemoteNotificationWithUserInfo:userInfo];
}

Displaying Details of Anonymous Users to Agents

When an anonymous user contacts customer support via chat, their details usually do not appear on the agent's screen. However, you can configure the ASAP add-on to display these details after receiving them from the user.
To configure this setting, use the following method.
Swift
ZDPortalConfiguration.setGuestUser(email: <#Guest_User_Email#>, displayName: <#Guest_User_DisplayName#>", phoneNumber: <#Guest_User_PhoneNumber#>")
Objective-C
[ZDPortalConfiguration setGuestUserWithEmail:<#Guest_User_Email#> displayName:<#Guest_User_DisplayName#> phoneNumber:<#Guest_User_PhoneNumber#>];
Additionally, agents can convert chat conversations into tickets, if more interactions with the user are required later. The email ID is a mandatory parameter to make this conversion possible.

Programmatically Adding Tickets

While end-users can manually submit tickets through the ASAP add-on, you can also configure your app to automatically record tickets when certain events occur in the app.
For instance, if you run a clothing business and your app fails to load the For Women screen when a user tries to access it, this failure instance can be automatically recorded as a ticket in your help desk. The user would not need to visit your help center and manually submit a ticket.
To make this automatic submission of tickets possible, incorporate the following method in your app code.
Swift
ZDProvoider.sharedInstance.getDepartments(onCompletion: { (departments) in
// get departments list in departments variable
}) { (error) in
    // error in departments fetch
}
Objective-C
[[ZDProvoider sharedInstance] getDepartmentsOnCompletion:^(NSArray<DepartmentJsonObject *> * departments) {
    // get departments list in departments variable
} onError:^(NSError * error) {
    // error in departments fetch
}];
EmailAddressSubject, and DepartmentID are mandatory parameters in the method call. 
To fetch the IDs of the departments in your help desk portal, use the following method.
Swift
ZDProvoider().getProductsFor(<#Department ID#>, from: <#T##Int#>, limit: <#T##Int#>, onCompletion: { (products) in
    // get products list in products variable
}) { (error) in
    // error in products fetch
}
Objective-C
[ZDProvoider sharedInstance] getProductsFor:@"Department ID" from:<#(NSInteger)#> limit:<#(NSInteger)#> onCompletion:^(NSArray  products) {
    // get products list in products variable
} onError:^(NSError * error) {
    // error in products fetch
}
To fetch information on the products configured in a department, use the following method.
Swift
ZDProvoider.sharedInstance.getTicketForm(<#Department ID#>, onCompletion: { (ticketFilelds) in
    // get Ticket Form in ticketFilelds variable
}) { (error) in
    // error in TicketForm fetch
}
Objective-C
[[ZDProvoider sharedInstance] getTicketForm:<#Department ID#> onCompletion:^(NSArray<TicketFieldsJsonObject *> * ticketFilelds) {
    // get Ticket Form in ticketFilelds variable
} onError:^(NSError * error) {
    // error in TicketForm fetch
}];
To fetch the fields configured in the ticket layout of a department, use the following method.
Swift
ZDProvoider.sharedInstance.uploadTicketAttachment(<#Your File path#>, onCompletion: { (attachement) in
    // get uploaded attachement object in attachement variable
}) { (error) in
    // error in Attachement upload
}
Objective-C
[[ZDProvoider sharedInstance] uploadTicketAttachment:<#Your File path#> onCompletion:^(AttachmentJsonObject * attachement) {
    // get Ticket Form in ticketFilelds variable
} onError:^(NSError * error) {
    // error in Attachement upload
}];
To include a file attachment in the ticket, use the following method.
Swift
let ticketForm = ZDTicketForm()
ticketForm.emailID = <#User email ID#>
ticketForm.contactName = <#Contact Name#>
ticketForm.subject = <#Ticket Subject#>
ticketForm.departmentID = <#Ticket Department ID#>
ticketForm.descriptionText = <#Ticket Description Text#>

ZDProvoider.sharedInstance.createTicket(form: ticketForm, onCompletion: { (ticket) in
    // get created ticket object in ticketDetail variable
}) { (error) in
    // error in ticket submission
}
Objective-C
ZDTicketForm * ticketForm = [ZDTicketForm init];
[ticketForm setEmailID:<#User email ID#>];
[ticketForm setContactName:<#Contact Name#>];
[ticketForm setSubject:<#Ticket Subject#>];
[ticketForm setDepartmentID:<#Ticket Department ID#>];
[ticketForm setDescriptionText:<#Ticket Description Text#>];

[[ZDProvoider sharedInstance] createTicketWithForm:ticketForm onCompletion:^(TicketDetailJsonObject * ticket) {
    // get created ticket object in ticketDetail variable
} onError:^(NSError * error) {
    // error in ticket submission
}]

Knowledge Base

These methods help you display your Knowledge Base and all associated content on the ASAP add-on.
Category deeplinking
The following method displays the list of categories/sub-categories in your Knowledge Base and the help articles under each category.
Swift
ZohoDeskPortalSDK.showCatgoryByPermalink(forPermaLink:"permalink", controller: self)
Objective-C
[ZohoDeskPortalSDK showCatgoryByPermalinkForPermaLink:@"permalink" controller:self];
  1. Self is the instance of the UIViewController.
  2. Permalink is the URL of the Knowledge Base category.

For instance, in the URL in the image above, the portion following "/kb/" is the permalink of the category. You can pass this portion as the path of the category or sub-category.
Article deeplinking
The following method displays the content of a help article right within your ASAP add-on.
Swift
ZohoDeskPortalSDK.showHelpPage(forPermaLink: "permalink", controller: self)
Objective-C
[ZohoDeskPortalSDK showHelpPageForPermaLink:@"permalink" controller:self];
  1. Self is the instance of the UIViewController.
  2. Permalink is the URL of the help article.

For instance, in the URL in the image above, the portion following "/articles/" is the permalink of the article.

Community

These methods help you display your user community and all associated content on the ASAP add-on.
Custom-Configuring Community Actions
Users can perform a range of actions, including editing and deleting topics; and adding, editing, and deleting comments, in the community module.
The following method helps you define which actions must be allowed and which actions must be disallowed when users access the community through the ASAP add-on.
Swift
ZDCommunityConfiguration.configure.isTopicDeleteAllowed = true
ZDCommunityConfiguration.configure.isTopicEditAllowed = true
ZDCommunityConfiguration.configure.isReplyDeleteAllowed = true
ZDCommunityConfiguration.configure.isReplyEditAllowed = true
ZDCommunityConfiguration.configure.isReplyAllowed = true
Objective-C
[ZDCommunityConfiguration configure].isTopicDeleteAllowed = YES;
[ZDCommunityConfiguration configure].isTopicEditAllowed = YES;
[ZDCommunityConfiguration configure].isReplyDeleteAllowed = YES;
[ZDCommunityConfiguration configure].isReplyEditAllowed = YES;
[ZDCommunityConfiguration configure].isReplyAllowed = YES;
Getting the Most Popular Topics
The following API fetches the forum topics with the most number of likes.
Swift
ZDProvoider.sharedInstance.getZDMostPopularCommunityTopics(forCategory: "Your Category ID", filterType: "ALL", from: 1, limit: 10, includeCount: false, { (communityTopics) in
    // get most popular topic list in communityTopics callback
}) { (error) in
    // error
}
Objective-C
[[ZDProvoider sharedInstance] getZDMostPopularCommunityTopicsForCategory:@"Your Catehory ID" filterType:@"ALL" from:1 limit:10 includeCount:NO :^(NSArray communityTopics) {
    // get most popular topic list in communityTopics callback
} onError:^(NSError * error) {
    // error
}];
Params
  1. categoryId - string - ID of the community category from which the topics must befetched. If you want to include all categories, pass the value "-1".
  2. filterType - string - Type of forum topic. Values allowed are: QUESTIONIDEAANNOUNCEMENTPROBLEM, and DISCUSSION.
  3. from - int - Index number, starting from which the topics must be fetched. Value starts from 1.
  4. limit - int - Number of topics to fetch
  5. includeCount - Boolean - Parameter that specifies whether the number of topics fetched must be displayed or not
Getting the Most Discussed Topics
The following API fetches the forum topics with the most number of comments.
Swift
ZDProvoider.sharedInstance.getZDMostDiscussedCommunityTopics(forCategory: "Your Category ID", filterType: "ALL", from: 1, limit: 10, includeCount: false, { (communityTopics) in
    // get most discussed topic list in communityTopics callback
}) { (error) in
    // error
}
Objective-C
[[ZDProvoider sharedInstance] getZDMostDiscussedCommunityTopicsForCategory:@"Your Catehory ID" filterType:@"ALL" from:1 limit:10 includeCount:NO :^(NSArray communityTopics) {
    // get most discussed topic list in communityTopics callback
} onError:^(NSError * error) {
   // error
}];
Params
  1. categoryId - string - ID of the community category from which the topics must befetched. If you want to include all categories, pass the value "-1".
  2. filterType - string - Type of forum topic. Values allowed are: QUESTIONIDEAANNOUNCEMENTPROBLEM, and DISCUSSION.
  3. from - int - Index number, starting from which the topics must be fetched. Value starts from 1.
  4. limit - int - Number of topics to fetch
  5. includeCount - Boolean - Parameter that specifies whether the number of topics fetched must be displayed or not

Tickets

These methods help you configure the submit ticket form the way you want, on the ASAP add-on.
Hiding Fields in the Submit Ticket Form
The Submit Ticket form in your ASAP add-on displays the same fields configured in the ticket layout in your Zoho Desk portal. If you want to hide any of the fields in the form, you can do so using the setFieldsListTobeShown() method. 
You must pass the list of fields (apiNames) as strings in this method. You might also have to pass the departmentId key, depending on the department mapping of the add-on. For instance, if the add-on is configured for a specific department, you need not pass the departmentId key. If the add-on is configured for multiple departments, you must pass the departmentId key to ensure department-ticket fields mapping in the Submit Ticket form. 
After you include this method, the form displays only the fields you passed in the method. However, keep in mind that mandatory fields will not be hidden even if you do not pass their names in the method.
Hiding Mandatory Fields in the Submit Ticket Form
If you absolutely want to hide a mandatory field in the form, you can do so, provided the value of the field is pre-filled. To do this, you must use the preFillTicketFields() method.
The preFillTicketFields() method proves useful when you want to pre-populate fields with values, such as auto-generated IDs or OS version of devices.
To use this method, you must pass the list of PreFillTicketField objects. You should also pass the departmentId key, depending on the department mapping of the add-on.
Just like in the case of the setFieldsListTobeShown() method, if the add-on is configured for a specific department, you need not pass the departmentId key. If the add-on is configured for multiple departments, you must pass the departmentId key to ensure department-fields mapping. 
The PreFillTicketField object contains three main properties:
  1. fieldApiName - string - apiName of the ticket field. You can retrieve the apiName of each field using the getTicketForm() method.
  2. fieldValue - object
    • For multiselect fields, pass the values allowed, as a comma(,) separated string.
    • For pick list fields, pass one of the values allowed, as a string.
    • For date fields, pass the value as a string in the MM/dd/yyyy format.
    • For dateTime fields, pass the value as a string in the MM-dd-yyyy hh:mm aa format.
    • For Boolean fields, pass a String value("true"/"false").
    • For all other field types, pass the values as string objects.
    • Make sure that the values you pass here to the maxlength and decimal restrictions defined for the field.
  3. isEditable - Boolean - Key that defines if the value in the field is editable or not
Note : For more clarity check the sample here.
Custom-Configuring Ticket Actions
Users can perform a range of actions, including replying to, commenting on, and closing tickets.
The following method helps you define which actions must be allowed and which actions must be disallowed when users access the ticket submission screen on the ASAP add-on.
Swift
ZDTicketConfiguration.configure.isCommentAllowed = true
ZDTicketConfiguration.configure.isCommentDeleteAllowed = true
ZDTicketConfiguration.configure.isCommentEditAllowed = true
ZDTicketConfiguration.configure.isReplyAllowed = true
ZDTicketConfiguration.configure.isTicketUpdateAllowed = true
Objective-C
ZDTicketConfiguration.configure.isCommentAllowed = YES;
ZDTicketConfiguration.configure.isCommentDeleteAllowed = YES;
ZDTicketConfiguration.configure.isCommentEditAllowed = YES;
ZDTicketConfiguration.configure.isReplyAllowed = YES;
ZDTicketConfiguration.configure.isTicketUpdateAllowed = YES;

Others

These methods help you perform a variety of other actions in your ASAP add-on.
Updating User Details
The following API helps update the details of users added to your help desk portal.
Swift
var body = [String : Any]()
body["displayName"] = "displayName"
body["mobile"] = "123456"

ZDProvoider.sharedInstance.UpdateUserInformation(userInfo: body, { (userInfo) in
    // get updated user information in userInfo variable
}) { (error) in
    // error
}
Objective-C
NSMutableDictionary * body = [NSMutableDictionary new];
[body setObject:@"displayName" forKey:@"displayName"];
[body setObject:@"123456" forKey:@"mobile"];

[[ZDProvoider sharedInstance] UpdateUserInformationWithUserInfo:body :^(NSDictionary * userInfo) {
    // get updated user information in userInfo variable
} onError:^(NSError * error) {
    // error
}];
Params
Dictionary [String : Any] data - Key and value pair. Keys included are: twitter, phonefacebooknamedisplayNamemobilecountryLocale, and timeZone

SDK Logging

The ASAP SDK also provides you with the option to fix errors that occur while using the add-on. This is made possible by SDK logging.
To enable logging for the SDK, include the following code snippet.
Swift
ZDPortalConfiguration.enableLogMessages = true
Objective-C
ZDPortalConfiguration.enableLogMessages = YES;
After enabling SDK logging, you can check the console log for the errors and take necessary action.

Release Notes

v1.1.5
  • Introduced an event callback that helps detect the dismissal of the Chat module.
  • Fixed an issue that caused a delay in loading the Chat screen for the first time.
  • Added a provision that lets users display custom UI text/labels.
  • Added the provision to enable/disable user actions in the ticket submission screen. For more details, click here.
  • Improved the capabilities related to attaching files.
v1.1.4
  • Introduced an API that helps update user details. For more details, click here.
v1.1.3
  • Fixed a critical issue that sometimes caused the app to crash when users tried to login to the add-on.
v1.1.2
  • Introduced an event callback that helps detect the dismissal of the ZohoDeskPortalSDK view controller.
    Swift
    ZohoDeskPortalSDK.dismissController {(controller) in
        // You can find dismissed from ZohoDeskPortalSDK using ZDViewController object
        switch controller{
        case .DashBoard:
            print("DashBoard")
        default:
            break
        }
    }
    Objective-C
    [ZohoDeskPortalSDK dismissControllerOnCompletion:^(enum ZDViewController controller) {
        switch (controller) {
            case ZDViewControllerDashBoard:
                NSLog(@"DashBoard");
            default:
                break;
        }
    }];
v1.1.1
  • Added an event callback to the Logout method.
    Swift
    ZohoDeskPortalSDK.logout(onComplition: {
        print("User sucessfully logged out")
    }) { (error) in
        print(error)
    }
    Objective-C
    [ZohoDeskPortalSDK logoutOnComplition:^{
        //
    } onError:^(NSError * error) {
        //
    }];
v1.1
  • Included the All option in the sub-forum filter in the Community module.
  • Enabled deep-linking for Knowledge Base categories.
  • Added the provision to enable/disable user actions in the Community module.For more details, check here.
v1.0.1
  • Introduced methods that help custom-configure the fields in the Submit Ticketscreen. For more details, check here.
  • Tweaked the Submit Ticket form such that the Department field is not displayed if the help desk portal has only one department.
v1.0
  • Introduced rich text formatting for ticket comments.
  • Implemented threaded comments for forum topics in the user community.
  • Implemented comment actions for comments on forum topics.
  • Implemented search feature within the user community.
  • Added APIs related to community categories, most popular topics, and most discussed topics.
  • Added a method that launches the topic detail screen when a topic ID is passed.
  • Added the Discussion topic type to the Community module.
  • Introduced event callbacks. For details, refer to the following sample code.
    Swift
    ZohoDeskPortalSDK.ZDAnalyticsTracker { (analyticsObject) in
        if analyticsObject?.getEventAction() == .KBArticleClicked{
            print("An Article is clicked.")
            //An Article is clicked. You can Log or Push this to any of the Analytics tools.
        }else if analyticsObject?.getEventAction() == .CommunityTopicClicked{
            print("A Topic is clicked.")
            //A topic is clicked. You can Log or Push this to any of the Analytics tools.
        }
    }
    Objective-C
    [ZohoDeskPortalSDK ZDAnalyticsTrackerOnCompletion:^(ZDAnalytics * analyticsObject) {
        if ([analyticsObject getEventAction] == ZDPortalUIActionKBArticleClicked) {
            NSLog(@"An Article is clicked.");
            //An Article is clicked. You can Log or Push this to any of the Analytics tools.
        }else if ([analyticsObject getEventAction] == ZDPortalUIActionCommunityTopicClicked) {
            NSLog(@"A Topic is clicked.");
            //A topic is clicked. You can Log or Push this to any of the Analytics tools.
        }
    }];
  • Fixed an issue related to the search functionality in the Community module. (If you are a new user starting out with this version of the SDK, you do not have to make any changes to overcome this issue. But if you are upgrading from the previous version of the SDK and have enabled JWT-based authentication in your Zoho Desk portal, make sure to regenerate the user token after upgrading. No functionality or features will be impacted for end-users.) For details, refer to the following sample code.
    Swift
    if !ZohoDeskPortalSDK.isZDUserSignedIn || !ZohoDeskPortalSDK.isZDSDKMigratedTo1_0{
        ZohoDeskPortalSDK.set(jwtUserIdentifier: <#Remote user Token#>, onComplition: {
        }, onError: { (error) in
        })
    }else{
        //User already signed into SDK
    }
    Objective-C
    if (![ZohoDeskPortalSDK isZDUserSignedIn] || ![ZohoDeskPortalSDK isZDSDKMigratedTo1_0]){
        [ZohoDeskPortalSDK setWithJwtUserIdentifier:<#Remote user Token#> onComplition:^{
        } onError:^(NSError * error) {
        }];
    }else{
        //User already signed into SDK
    }
v0.2.7
  • Added the Follow option for Categories in the Community module.
  • Enabled custom-configuration of the back button on the navigation bar.
    Swift
    ZDNavigationTheme.backButtonStyle = ZDNavigationBackButtonStyle.icon
    Objective-C
    [ZDNavigationTheme setBackButtonStyle:ZDNavigationBackButtonStyleIcon];
v0.2.6
  • Enabled support for the Indian data center. To host your ASAP add-on on this datacenter, pass the value of the data center key as ZDDataCenter.IN while initializing the SDK.
  • Included a new method that launches the add-on dashboard with its configuration overridden. For more details, check here
v0.2.5
  • Added the from and limit parameters to Product provider APIs. The from parameter denotes the index number of the resource and the limit parameter denotes the number of resources to return. If these two parameters are not passed in the API request, the first 10 products are returned, by default.
  • In the Create Ticket provider API, we fixed a critical bug that caused failure of ticket submission when a file was attached to the ticket.
v0.2.4
  • Enabled push notifications for the following ticket actions:
    • Agent creates a ticket on behalf of the user.
    • Agent sends a new ticket response.
    • Priority of the ticket is changed.
    • Status of the ticket is changed.
    • A new comment is added to a ticket.
    • A ticket comment is edited.
  • Introduced a callback method for the Submit Ticket screen. Through this method, the ASAP add-on can be configured such that ticket details are sent to the app immediately after a ticket is submitted.
v0.2.3
  • Fixed an issue that in some cases caused an app crash when the ASAP framework tried to access Core Data.

Migrating from v1.x to v2.0

Integrating the SDK with Your iOS App

In late 2018, Zoho Desk introduced a capability called ASAP, which takes help to users proactively, eliminating the hassle of navigating to a different tab and finding help resources. Using the ASAP SDK, you can embed a widget into your iOS app, so that your customers can reach you quickly for support.

Over these two years, we have refined the ASAP SDK and made it more accessible and easier to use. The culmination of these refinements is here for you. Presenting to you the ASAP SDK for iOS - v2.0.

If you have already been using the ASAP SDK with your iOS app, there is a bit of migration that you would need to do to make your app compatible with v2.0.

The following tables list the changes you need to make to ensure a smooth migration.
v1.0 Series
v2.0
pod 'ZohoDeskPortalSDK', :git => 'https://github.com/zoho/ZohoDeskPortalSDK.git'end
pod 'ZohoDeskPortalServices',
In App Delegate.swift,

import ZohoDeskPortalSDK
...
config.enableHelpCenter = true
config.enableCreateTicket = true
config.enableMyTicket = true
config.enableCommunity = false
ZohoDeskPortalSDK.initializeSDK(<#ORGID#>, appId: <#APPID#>, dataCenter: <#dataCenterValue#>, configuration: <#config#>)
import ZohoDeskPortalAPIKit
...
ZohoDeskPortalSDK.initialize(orgID:<#String#>, appID:<#String#>, dataCenter: <#ZDPDataCenter#>)

you can set configuration when showing dashboard.
Method for displaying the home page
v1.0 Series
v2.0
import ZohoDeskPortalSDK
....
ZohoDeskPortalSDK.showHomePage()
import ZohoDeskPortalCore
...
ZDPortalHome.show() // By default, all modules are enabled. To hide any module, pass the configuration object as shown here
Method for displaying the help center (Knowledge Base)
v1.0 Series
v2.0
import ZohoDeskPortalSDK
....
ZohoDeskPortalSDK.showHelpCenter(_:)
import ZohoDeskPortalKB
...
ZDPortalKB.show()
Method for displaying the Submit Ticket screen
v1.0 Series
v2.0
import ZohoDeskPortalSDK
....
ZohoDeskPortalSDK.addTicket(_:)
import ZohoDeskPortalTicket
...
ZDPortalSubmitTicket.show()
Method for displaying the My Tickets list
v1.0 Series
v2.0
import ZohoDeskPortalSDK
....
ZohoDeskPortalSDK.ticketList(_:)
import ZohoDeskPortalTicket
...
ZDPortalTicket.show()
Method for displaying the Community module
v1.0 Series
v2.0
import ZohoDeskPortalSDK
....
ZohoDeskPortalSDK.showCommunity(_:)
import ZohoDeskPortalCommunity
...
ZDPortalCommunity.show()
Method for authenticating users in the SDK
v1.0 Series
v2.0
ZohoDeskPortalSDK.set(jwtUserIdentifier: _, onCompletion: _ -> (), onError: _ -> () )
ZohoDeskPortalSDK.loginUser(withJWTidentifier: <#String#>, onCompletion: (Bool) -> Void)
Method for checking if a user is currently authenticated
v1.0 Series
v2.0
ZohoDeskPortalSDK.isZDUserSignedIn
ZohoDeskPortalSDK.isUserLoggedIn
To log out an user from the SDK

ZohoDeskPortalSDK.logout()
ZohoDeskPortalSDK.logout(onCompletion: (Bool) -> Void)
//skipping customization for now

Method for enabling sending of push notifications to users
v1.0 Series
v2.0
ZohoDeskPortalSDK.enablePushNotifications(deviceToken: _, mode: )
ZohoDeskPortalSDK.enablePushNotification(deviceToken:token, mode: .production)
To let the SDK know about the notifications, in AppDelegate.swift,

import ZohoDeskPortalSDK
...
ZohoDeskPortalSDK.processRemoteNotification(userInfo: userInfo)
import ZohoDeskPortalConfiguration
...
ZDPortalConfiguration.processRemoteNotification(userInfo: userInfo)
// set guest config in chat

If you were programmatically adding tickets as mentioned here, kindly follow the new approach as explained here.
Method for deep-linking a Knowledge Base category
v1.0 Series
v2.0
import ZohoDeskPortalSDK
...
ZohoDeskPortalSDK.showCatgoryByPermalink(forPermaLink:"permalink", controller: self)
import ZohoDeskPortalKB
...
ZDPortalKB.showCategory(withPermalink : <#String#>)
Method for deep-linking a Knowledge Base article
v1.0 Series
v2.0
import ZohoDeskPortalSDK
...
ZohoDeskPortalSDK.showHelpPage(forPermaLink: "permalink", controller: self)
import ZohoDeskPortalKB
...
ZDPortalKB.showArticle(withPermalink : <#String#>)
Method for customizing the community module
v1.0 Series
v2.0
ZDCommunityConfiguration.configure.isTopicDeleteAllowed = true
ZDCommunityConfiguration.configure.isTopicEditAllowed = true
ZDCommunityConfiguration.configure.isReplyDeleteAllowed = true
ZDCommunityConfiguration.configure.isReplyEditAllowed = true
ZDCommunityConfiguration.configure.isReplyAllowed = true
ZDPCommunityConfiguration.isTopicEditAllowed = <#Bool#>
ZDPCommunityConfiguration.isTopicDeleteAllowed = <#Bool#>
ZDPCommunityConfiguration.isReplyAllowed = <#Bool#>
ZDPCommunityConfiguration.iReplyEditAllowed = <#Bool#>
ZDPCommunityConfiguration.isReplyDeleteAllowed = <#Bool#>
Method for fetching the list of most popular topics
v1.0 Series
v2.0
ZDProvoider.sharedInstance.getZDMostPopularCommunityTopics( with all parameters)
ZohoDeskPortalSDK.Community.getMostPopularTopics(<#[String: Any]?#>, onCompletion: <#Result<[ZDPCommuity.TopicDetail], ZDPError> -> Void#>
for the list of parameters which can be passed in, refer here
Method for fetching the list of most discussed topics
v1.0 Series
v2.0
ZDProvoider.sharedInstance.getZDMostDiscussedCommunityTopics( with all parameters)
ZohoDeskPortalSDK.Community.getMostDiscussedTopics(<#[String: Any]?#>, onCompletion: <#Result<[ZDPCommuity.TopicDetail], ZDPError> -> Void#>
for the list of parameters which can be passed in, refer here
ticket configuration - same as community configuration - static changes pending

Method for updating user information
v1.0 Series
v2.0
ZDProvoider.sharedInstance.UpdateUserInformation(userInfo: <#data#>, onCompletion: _ -> (), onError: _ -> ())
ZohoDeskPortalSDK.updateUserInformation(with: [String: String], onCompletion: (Result<ZDPortal.Profile, ZDPError>) -> Void)
Method for enabling logs in the SDK
v1.0 Series
v2.0
ZDPortalConfiguration.enableLogMessages = true
ZohoDeskPortalSDK.enableLogs()
Method for disabling logs in the SDK
v1.0 Series
v2.0
ZDPortalConfiguration.enableLogMessages = false
ZohoDeskPortalSDK.disableLogs()
Note 
From v2.0:
  • The View Controller is not required in any show method.
  • All show methods have title and style parameters with default values. You can override the parameters, if required.


    Zoho DataPrep Personalized Demo

    If you'd like a personalized walk-through of our data preparation tool, please request a demo and we'll be happy to show you how to get the best out of Zoho DataPrep.

    Zoho CRM Training

      Create, share, and deliver

      beautiful slides from anywhere.

      Get Started Now





              Zoho CRM Training Programs

              Learn how to use the best tools for sales force automation and better customer engagement from Zoho's implementation specialists.

              Zoho CRM Training

                Zoho SalesIQ Resources



                    Zoho TeamInbox Resources




                              Zoho DataPrep Resources

                                Zoho DataPrep Demo

                                Get a personalized demo or POC

                                REGISTER NOW


                                  Design. Discuss. Deliver.

                                  Create visually engaging stories with Zoho Show.

                                  Get Started Now











                                                        • Related Articles

                                                        • Working with the ASAP SDK for React Native

                                                          The ASAP SDK for React Native makes help available within quick reach for the end-users of your mobile app. Using this SDK, you can add and customize an add-on that resides within your iOS/Android app and provides end-users with easy access to your: ...
                                                        • Working with the ASAP Add-On for the Web

                                                          Introduction The ASAP add-on for websites makes your help center available within quick reach for your end-customers. By integrating this add-on with your website, you can provide your customers with easy access to your:  Customer support team (to ...
                                                        • Working with the ASAP Add-Ons for Mobile Platforms

                                                          The ASAP SDKs for mobile platforms--iOS and Android--make help available within quick reach for the end-users of your mobile apps. Using these SDKs, you can create and customize add-ons that reside within your app and provide end-users with easy ...
                                                        • Working with the ASAP SDK for Android

                                                          SDK v2.0 Introduction The ASAP SDK for Android makes help available within quick reach for the end-users of your Android app. Using this SDK, you can create and customize an add-on that resides within your app and provides end-users with easy access ...
                                                        • Managing Help Center Users

                                                          Help Center users are users who prefer to find solutions by reading through your knowledge base articles or community posts. When they are unable to find answers they can get it resolved from your agents by submitting a ticket. Users can also ...

                                                        Resources

                                                        Videos

                                                        Watch comprehensive videos on features and other important topics that will help you master Zoho CRM.



                                                        eBooks

                                                        Download free eBooks and access a range of topics to get deeper insight on successfully using Zoho CRM.



                                                        Webinars

                                                        Sign up for our webinars and learn the Zoho CRM basics, from customization to sales force automation and more.



                                                        CRM Tips

                                                        Make the most of Zoho CRM with these useful tips.



                                                          Zoho Show Resources