Asista SDK for iOS

Last updated on: March 19th, 2019

View Demo App based on Asista iOS SDK here.

About Asista SDK for iOS

Asista SDK lets you quickly add the backend features to your application so that you can focus on your application code. It is designed to make interaction with Asista easy and effortless. The SDK comes with its own user interface (UI), or you can build your own. You can call only specific screens from the SDK based on the functionality you want to expose in your app.

Features of Asista

  • Register and authenticate with Asista
  • Ticket Creation
  • View Ticket details
  • Update Ticket details(ticket state, priority)
  • Add comments to ticket
  • View Knowledge Base

Getting Started

Prerequisites

  • iOS 8.0+
  • Xcode 10.0+
  • Swift 4.2+

Version Requirements

Most of the Asista UI related methods works on iOS 11.0+. To have better experience you have to make the minimum version of the app to 11.0. Even though if you are using AsistaCore dependancy only, You can make your minimum version to 8+ to access all the functions of Asista.

Integrate SDK using Cocoa pods

Step 1: Install Cocoa pods.
From a terminal window navigate into your XCode project’s application directory and run the following:

sudo gem install cocoapods
pod init
nano Podfile


Step 2: Simply add the following line to your Podfile.

To include AsistaCore:

use_frameworks!
platform :ios, '8.0'

target ‘Your App' do
pod 'AsistaCore'
  end
end

To include AsistaUI:

use_frameworks!
platform :ios, '10.0'

target 'Your App' do
pod 'AsistaUI'
  end
end


Step 3: Save and close the file.

Step 4: Run pod install and build your app.

Configure an App in Asista

To begin making calls to the Asista SDK, you need to register an application on the Asista Web portal and get credentials for your app. Someone with administrator access to Asista must do this. You will get an appKey and appSecret after the successful registration of the app.

Then, configure your Xcode with information for the Asista SDK. Locate the Info.plist file for your application. Right-click this file and select Open As > Source Code

Add the following code snippet, replacing the placeholders within the square brackets ([]) with your app’s information from the developer dashboard. (Note: Do not include the square brackets)

<key>Asista</key>

<dict>

         <key>appKey</key>

         <string>[appKey]</string>

         <key>appSecret</key>

         <string>[appSecret]</string>

         <key>tenantUrl</key>

         <string>[https://yourdomain.asista.com]</string>

</dict>

Permissions Required by Asista

Asista IOS SDK requires these minimum permissions to work flawlessly in your app. Camera and Photo library access is required to manage the attachments of the ticket.

The required permissions are listed below:

  • Privacy – Camera Usage Description
  • Privacy – Photo Library Usage Description
  • Privacy – Photo Library Additions Usage Description

Initialize the SDK in Runtime

In AppDelegate.swift for your application, just import AsistaCore framework and initialize AsistaCore.

Import the AsistaSDK framework into the AppDelegate file in your project.

The initialization code snippets look like this:

Swift 4

import AsistaCore

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

         let AsistaClient = AsistaCore.init(tenantUrl: “your tenant url”, clientSecret: “your clientSecret”, appKey: “your appKey”)
         AsistaClient.getInstance().getAuthService.{required api request}

}

Expected Errors

1. Use of unresolved identifier ‘AsistaCore’ or Use of unresolved identifier ‘AsistaUI’

This issue can be encountered when you are accessing any of the Asista methods without importing the dependency to the class.

Solution
         Import the pod to project file whenever they are needed.

2. ‘AsistaUI’ is only available on iOS 11.0 or newer

Solution
         This issue arises because the project which you are using ‘AsistaUI’ has the deployment target less than 11.0. Since Asista SDK always tries deliver the latest concept on the Cocoa platform that allow you to build applications that take advantage of new features in the latest platform SDKs, we have made our minimum deployment target to 11.0. Even though if you are using AsistaCore dependancy only, You can make your minimum version to 8+ to access all the functions of Asista.

3. Thread 1: Fatal error: ‘try!’ expression unexpectedly raised an error: AsistaCore.AsistaError.invalidAuthCredentials (“Asista Core initialization failed. Check your init variables”)

Solution
         Your initialization failed due to invalid credentials or your plist file doesn’t contain the attributes for Asista initialization.

4. App crashes when the user access for photo library or camera.

Solution
You have to check your App’s info.plist file whether any of the Asista SDK required permissions are added to the file. If it is not, Please add the resource permission to .plist file.

Asista Services

Authentication

Almost all asista functionalities can be performed only on successful authentication with asista. After successfully including the asista SDK to your project and initializing the asistaCore with the required asista properties(tenant url, appKey, appSecret), based on your requirement user ‘registration’ or ‘authentication’ can be performed.

Register User

Calls a request service to create a new user on behalf of the end user.

register(_:completionHandler:)
Performs user registration from client App

Declaration

public func register(_ user: RegisterUser, completionHandler: @escaping (ResultModel<Bool, AsistaError>) -> Void)
Parameters Type Description
user RegisterUser Object of RegisterUser model which contains the credentials for registering user
callback callback<Bool, AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then `true` will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.


Usage
After creating a RegisterUser object, you can use the object to register method to create a request.

Swift

let user = RegisterUser()
user.firstName = firstName
user.lastName = lastNameText.text!
user.email = emailText.text!
user.userId = userId
user.phone = phone

AsistaCore.getInstance().getAuthService().register(user) { (result) in
        switch result {
        case .success( _):
                   //user registration successful
        case .failed(let error):
                   //user registration failed
        }
}
User Authentication

Once user registration is successful, user authentication can be done by calling the authenticate()  method of the AuthService class in AsistaCore.

authenticate(userId:completionHandler:)
Performs user authentication by appKey, appSecret and userId

Declaration

public func authenticate(appKey: String, appSecret: String, userId: String, completionHandler: @escaping (ResultModel<Bool, AsistaError>) -> Void) 
Parameters Type Description
appKey String App unique Id
appSecret String Secret key used to connect Asista SDK with Application
userId String User Id of of the user
callback callback<Bool, AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful `then` true will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.


signOut(completionHandler:)
Sign out the user from the logged in session and invalidate token.

Declaration

public func
signOut(completionHandler: @escaping (_ status: Bool) -> Void)
Parameters Type Description
completionHandler callback<Bool> The callback invoked when the request is either successful or has failed, if sign out is successful  `true` will be returned. Otherwise false will be returned

Knowledge Base

A knowledge base lets companies answer common questions before they’re asked. Much like the Help menu in your favourite programs, a knowledge base is where you publish documentation about pricing, features, services, frequent problems, and anything else you want to share about your app or business.

Using the Asista SDK you can show a localized FAQ / Help to your customers, filter its contents to be more helpful to their specific use case, and use it as a hopping off point for creating a request.            

Asista Knowledge base comes with its own built in UI. You can use the default UI or remove it and use your own. If you use your own UI, it will takes a little more development time, but gives you more control. The UI that is provided with the Asista SDK looks like this:

Accessing through AsistaUI

You can use the api call AsistaUI.showKnowledgeBase(on: self) to show Knowledge Base in your app. Here users can browse Topics, search for articles with Asista UI.

Show Knowledge Base

You can call the method to show Knowledge Base in your app. This will bundle with all capabilities of the Asista Knowledge Base SDK with its own default UI. Users can list KB topics, search for articles and view them.

//to display Knowledge Base page   
AsistaUI.showKnowledgeBase(on: self)
Show Article List

If you need to show only the list of articles, then you can directly access the article list page.

//to display list of articles   
AsistaUI.showArticles(on: self)
Show Single Article

You can use the showSingleArticle() method to display a single KB article. Keep in mind that, you have to pass the articleId when you are invoking the method.

//to display single article  
AsistaUI.showSingleArticle(articleId: 225, on: self)
Accessing through AsistaCore
Fetch KB Topics

fetchKbTopics(completionHandler:)
Fetch the list of topics in KB.

Declaration

public func fetchKbTopics(completionHandler: @escaping (ResultModel<[KBTopic], AsistaError>) -> Void) 
Parameters Type Description
callback callback<[KBTopic], AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then Array of KB topics( I.e., [KBTopic])  will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Fetch KB Articles

fetchKbArticles(with:completionHandler:)
Fetch a list of articles under a topic id.

Declaration

public func fetchKbArticles(with topicId: Int, completionHandler: @escaping (ResultModel<KBArticle, AsistaError>) -> Void) 

Parameters Type Description
topicId Int Int value respresents the id of topic
callback callback<KBArticle, AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then list of KB Article will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Search KB Articles

searchKBArticles(query:completionHandler:)
Perform search in a list of article.

Declaration

public func searchKBArticles(query:
String, completionHandler: @escaping (ResultModel<[KBArticleSearch], AsistaError>) -> Void)
Parameters Type Description
query String String value represents the text to search in Article list
callback callback<[KBArticleSearch], AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then Array of KB Article( I.e., [KBArticleSearch])  will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.

Ticket

Using the Asista SDK, your users can create new tickets, list them and update existing ones. Users can also see their/agents comments on a ticket like a chat between agent and user.

Asista Ticketing service also comes with its own built in UI. The UI that is provided with the Asista SDK looks like this:

Accessing through AsistaUI

You can use the api call AsistaUI.showTicketCreation(on: self) to show Ticket creation page in your app. Also AsistaUI.showUserTickets(on: self) method is used to display the list of list of tickets.

Show Ticket Creation Page

You can call the method to show Ticket creation page in your app.

//to display the ticket creation page 
AsistaUI.showTicketCreation(on: self)
Show Ticket List

Use the method when you want list your user’s tickets

//to display tickets list page 
AsistaUI.showUserTickets(on: self)
Show Single Ticket

You can use the showSingleTicket() method to display a single Ticket. Keep in mind that, you have to pass the requestId when you are invoking the method.

//to display single ticket  
AsistaUI.showSingleTicket(requestId: Int, on: self)
Accessing through AsistaCore
fetchTicketFields(completionHandler:)

Returns the list of fields with their attributes to display in create ticket form

Declaration

public func fetchTicketFields(completionHandler: @escaping (ResultModel<[CreateTicketForm], AsistaError>) -> Void)
Parameters Type Description
callback callback<[CreateTicketForm], AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then Array of Ticket fields( I.e., [CreateTicketForm])  will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Fetch Category List

fetchCategoryList(completionHandler:)
Returns the list of categories for a ticket

Declaration

public func
fetchCategoryList(completionHandler: @escaping (ResultModel<[Category], AsistaError>) -> Void)
Parameters Type Description
callback callback<[Category], AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then Array of KB topics( I.e., [KBTopic])  will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Create Ticket

createTicket(with:completionHandler:)
Performs ticket creation

Declaration

public func createTicket(with
parameters: Dictionary<String, Any>, completionHandler: @escaping (ResultModel<MsgResponse, AsistaError>) -> Void)
Parameters Type Description
parameters  Dictionary<String, Any> Dictionary value contains the data of ticket
callback callback<MsgResponse, AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then response message  will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Fetch User Tickets

fetchUserTickets(from:to:completionHandler:)
Returns the list of ticket between the range

Declaration

public func
fetchUserTickets(from: Int? = 0, to: Int? = 20, completionHandler: @escaping (ResultModel<TicketList, AsistaError>) -> Void)
Parameters Type Description
from Optional Int Range starting from
to Optional Int Range ending to
callback callback<TicketList, AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then TicketList object will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Search Ticket

searchTicket(query:completionHandler:)
Search ticket on the server based on the user’s query

Declaration

public func
searchTicket(query: String, completionHandler: @escaping (ResultModel<[TicketPayload], AsistaError>) -> Void)
Parameters Type Description
query String quesry string provided by the user on ticket searching
callback callback<[TicketPayload], AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then Array of Tickets( I.e., [TicketPayload])  will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Fetch Ticket Details

fetchTicketDetails(requestId:completionHandler:)
Returns the details of the ticket based on the requestId

Declaration

public func
fetchTicketDetails(requestId: Int, completionHandler: @escaping (ResultModel<TicketDetail, AsistaError>) -> Void)
Parameters Type Description
requestId Int Represents the unique id provided to a ticket
callback callback<TicketDetail, AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then Ticket detail object( I.e., TicketDetail)  will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Add Comment

addComment(with:completionHandler:)
Add comment on the ticket

Declaration

public func addComment(with
parameters: Dictionary<String, Any>, completionHandler: @escaping (ResultModel<Bool, AsistaError>) -> Void)
Parameters Type Description
parameters Dictionary<String, Any> Dictionary value contains the data of a comment
callback callback<Bool, AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then `true` will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Fetch State List

fetchStateList(completionHandler:)
Returns the list of tickets

Declaration

public func
fetchStateList(completionHandler: @escaping (ResultModel<[State], AsistaError>) -> Void)
Parameters Type Description
completionHandler callback<[State], AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then Array of States( I.e., [States])  will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Fetch Workflow States

fetchWorkflowStates(requestId:completionHandler:)
Returns the upcoming list of states of a ticket

Declaration

public func
fetchWorkflowStates(requestId: Int, completionHandler: @escaping (ResultModel<[State], AsistaError>) -> Void)
Parameters Type Description
requestId Integer represents the unique id provided to a ticket
completionHandler callback<[State], AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then Array of Workflow States( I.e., [States])  will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Update Ticket State

updateTicketState(parameters:completionHandler:)
Perform ticket state updation on server

Declaration

public func
updateTicketState(parameters: Dictionary<String, Any>, completionHandler:
@escaping (ResultModel<MsgResponse, AsistaError>) -> Void)
Parameters Type Description
parameters Dictionary<String, Int> Dictionary value contains the data of new state
completionHandler callback<[MsgResponse], AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then Message Response object will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Fetch Priority List

fetchPriorityList(completionHandler:)
Returns list of priorities

Declaration

public func
fetchPriorityList(completionHandler: @escaping (ResultModel<[Priority], AsistaError>) -> Void)
Parameters Type Description
completionHandler callback<[Priority], AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then Message Response object will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Update Ticket Priority

updateTicketPriority(parameters:completionHandler:)
Performs ticket priority updation on server

Declaration

public func
updateTicketPriority(parameters: Dictionary<String, Int>, completionHandler:
@escaping (ResultModel<MsgResponse, AsistaError>) -> Void)
Parameters Type Description
parameters Dictionary<String, Int> Dictionary value contains the data of new priority
completionHandler callback<[MsgResponse], AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then Message Response object will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Fetch Attachment Properties

fetchAttachmentProperties(completionHandler:)
Returns the properties of attachment that uploading to the server

Declaration

public func
fetchAttachmentProperties(completionHandler: @escaping (ResultModel<AttachmentProperties, AsistaError>) -> Void)
Parameters Type Description
completionHandler callback<AttachmentProperties, AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then Attachment Properties object will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Upload Attachment

uploadAttachment(url:completionHandler:)
Performs file upload with the server.

Declaration

public func
uploadAttachment(url: URL, completionHandler: @escaping (ResultModel<UploadResponse, AsistaError>) -> Void)
Parameters Type Description
url URL Url path of the file
callback callback<UploadResponse, AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then UploadResponse object will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.

uploadAttachment(data:name:mimeType:completionHandler:)
Performs file upload with the server.

Declaration

public func
uploadAttachment(data: Data, name: String, mimeType: String, completionHandler:
@escaping (ResultModel<UploadResponse, AsistaError>) -> Void)
Parameters Type Description
Data Data File in Data format
Name String Name of the file
MimeType String Mime type of the file
callback callback<UploadResponse, AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then UploadResponse object will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Fetch Image

fetchImage(url:completionHandler:)
Returns the image in data format when calls with the url of the image

Declaration

public func fetchImage(url:
String, completionHandler: @escaping (ResultModel<Data, AsistaError>) -> Void)
Parameters Type Description
url String url path in which image is situated.
completionHandler callback<Data, AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then image will be returned in the dorm of Data object to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Download File

downloadFile(url:completionHandler:)
Download file to internal storage of the device and returns its file-path

Declaration

public func
downloadFile(url: String, completionHandler: @escaping (ResultModel<URL, AsistaError>) -> Void)
Parameters Type Description
Url String url in which file is situated.
completionHandler callback<URL, AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then file-path will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.

Asset

Assets are properties that assigned to users. Using the Asista SDK, your users can able to see their list of assets and their details.

Assets also comes with its own built in UI. The UI that is provided with the Asista SDK looks like this:

Accessing through AsistaUI

You can use the api call AsistaUI.showAssets(on: self) to show Asset in your app.

Show Asset List

Use the method when you want list your user’s assets

//to display asset list page 
AsistaUI.showAssets(on: self)
Show Single Asset

Use the showSingleAsset() method to display the details of a single asset. Keep in mind that, you have to pass the assetId when you are invoking the method.

//to display the ticket creation page 
AsistaUI.showSingleAsset(assetId: Int, on: self)
Accessing through AsistaCore
Fetch Asset Categories

fetchAssetCategories(completionHandler:)
Returns the list of asset categories

Declaration

public func
fetchAssetCategories(completionHandler: @escaping (ResultModel<[AssetCategory], AsistaError>) -> Void)
Parameters Type Description
callback callback<[AssetCategory], AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then Array of Asset category( I.e., [AssetCategory])  will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Fetch Asset Types

fetchAssetTypes(categoryId:completionHandler:)
Returns the list of asset Types

Declaration

public func fetchAssetTypes(categoryId: Int? = nil,
completionHandler: @escaping (ResultModel<[AssetType], AsistaError>) -> Void)
Parameters Type Description
categoryId Optional Int Id of the category in which asset types are listed
callback callback<[AssetType], AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then Array of Asset types( I.e., [AssetType])  will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Fetch Asset List

fetchAssetList(categoryId:modelId:from:to:completionHandler:)
Returns the list of assets

Declaration

public func
fetchAssetList(categoryId: Int? = nil, modelId: Int? = nil, from: Int? = 0, to:
Int? = 20, completionHandler: @escaping (ResultModel<AssetList, AsistaError>) -> Void)
Parameters Type Description
categoryId Optional Int Id of the category in which asset is listed
modelId Optional Int Id of the model in which asset is listed
from Optional Int Range starting from
to Optional Int Range ending to
callback callback<AssetList, AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then Asset List object will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.
Fetch Asset Details

fetchAssetDetails(assetId:completionHandler:)
Returns details of an asset from assetId

Declaration

public func fetchAssetDetails(assetId:
Int, completionHandler: @escaping (ResultModel<AssetDetail, AsistaError>) -> Void)
Parameters TypeDescription
assetId Int Unique id provided to each asset item
callback callback<AssetDetail, AsistaError> The callback invoked when the request is either successful or has failed, if the fetch is successful then Asset will be returned to the .success() of the callback, else if the fetch fails, an exception will be returned to the .failed() of the callback.



View Demo App based on Asista iOS SDK here.