Asista SDK for iOS
Last updated on: March 19th, 2019
View Demo App based on Asista iOS SDK here.
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 SDK
- 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 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.
2. ‘AsistaUI’ is only available on iOS 11.0 or newer
3. Thread 1: Fatal error: ‘try!’ expression unexpectedly raised an error: AsistaCore.AsistaError.invalidAuthCredentials (“Asista Core initialization failed. Check your init variables”)
4. App crashes when the user access for photo library or camera.
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 |
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:
Asista iOS SDK UI
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:
Asista iOS SDK UI - Tickets
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
Fetch Ticket Fields
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:
Asista iOS SDK UI - Assets
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 | Type | Description |
|---|---|---|
| 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.