TestsTested | ✓ |
LangLanguage | Obj-CObjective C |
License | BSD 3.0 |
ReleasedLast Release | Aug 2016 |
Maintained by Noel Artiles, Desk.com.
The DeskKit SDK is a framework that makes it easy to incorporate your Desk site’s support portal into your iOS app. The SDK supports multiple methods for installing the framework in a project.
Starting with DeskKit SDK version 4.0
, prebuilt frameworks are attached in github releases. In order to use prebuilt frameworks:
Frameworks.zip
file from Releases
DeskKit.framework
, DeskAPIClient.framework
, DeskCommon.framework
) and select them. Check the Destination: Copy items if needed checkbox when prompted.IMPORTANT: Attached prebuilt frameworks contain binaries which have been built for a number of architectures (x86_64, i386, armv7, arm64)
. According to this radar before submission to AppStore you must strip off simulator slices (x86_64, i386)
.
Before presenting any support portal view controllers, you must start a DKSession
to authorize the Desk API:
[DKSession startWithHostname:@“yoursite.desk.com”
APIToken:@“YOUR_API_TOKEN”];
You can obtain an API token in your site’s Admin console by visiting the Settings > API page. You can set up an API Application, and then click on the link for “Your Mobile SDK Token” to obtain the token you need to enter here.
If your Support Center’s Security Mode (Admin->Channels->Advanced Settings->Security Mode) is set to ‘HTTP Only’ or ‘Mixed’ you’ll need to configure Apple’s App Transport Security to allow http content via the SDK. If your Security Mode is set to ‘HTTPS Only’ then you can skip the following.
<dict>
<key>NSExceptionDomains</key>
<dict>
<key>yourdomain.desk.com</key>
<dict>
<key>NSIncludesSubdomains</key>
<true/>
<key>NSThirdPartyExceptionAllowsInsecureHTTPLoads</key>
<true/>
</dict>
</dict>
</dict>
The DeskKitExample
app presents a support portal in a top-level UISplitViewController
. Of course, how you present your own support portal is up to you. The usual starting point, however, is the DKTopicsViewController
which is a table-based list of all the support topics in your portal. This view controller also includes a search bar that lets your users search articles.
DKSession
has a convenience method that allows you to create this controller:
[DKSession newTopicsViewController]
You’ll probably want to set yourself as the DKTopicsViewControllerDelegate
and use a DKArticleDetailViewController
to show the article. Please refer to the DeskKitExample
app for an example of how to hook up these two view controllers.
The DeskKitExample
app also demonstrates one way to present a “Contact Us” action sheet. DSSession
has a class method to create a pre-configured UIAlertController
that allows a user to choose whether to email you or call you by phone, depending on which settings you have enabled below. This controller can be instantiated like so:
[DKSession newContactUsAlertControllerWithCallHandler:^(UIAlertAction *callAction) {
[[UIApplication sharedApplication] openURL:[[DKSession sharedInstance] contactUsPhoneNumberURL]];
} emailHandler:^(UIAlertAction *emailAction) {
[self alertControllerDidTapEmailUs];
}];
When the user taps “Email Us” you can instantiate and configure an instance of DKContactUsViewController
:
- (void)alertControllerDidTapEmailUs
{
DKContactUsViewController *contactUsVC = [[DKSession sharedInstance] newContactUsViewController];
contactUsVC.delegate = self;
// Configure additional properties of DKContactUsViewController here
UINavigationController *nvc = [[UINavigationController alloc] initWithRootViewController:contactUsVC];
nvc.modalPresentationStyle = UIModalPresentationPageSheet;
[self presentViewController:nvc animated:YES completion:nil];
}
You can configure which fields to show via the DeskKitSettings.plist
(see below) or via properties on your DKContactUsViewController
instance. Properties set in code have precedence over DeskKitSettings.plist
settings.
If you already have a name and email for your user, you can pass those to the DKContactUsViewController
instance via a DKUserIdentity
object like so:
DKUserIdentity *userIdentity = [[DKUserIdentity alloc] initWithEmail:@“[email protected]”];
userIdentity.givenName = @“John”;
userIdentity.familyName = @“Doe”;
contactUsVC.userIdentity = userIdentity;
If the user’s email is not provided via the userIdentity
property, then a required “Your Email” UITextfield
will be shown in the form.
The Custom Fields you specify through the SDK must match the Custom Fields you have defined in your site’s Admin console.
When you create a DKContactUsViewController
through the DKSession
singleton, the SDK automatically sets the customFields
property using the dictionary provided via the ContactUsStaticCustomFields
key of the DeskKit Settings (see below). You can further modify the customFields
property at runtime.
// Grab initial custom fields populated from DeskKitSettings.plist
NSMutableDictionary *customFields = [contactUsVC.customFields mutableCopy];
// Add your own dynamic custom fields.
[customFields addEntriesFromDictionary:[self dynamicCustomFields]];
// Assign back to property.
contactUsVC.customFields = customFields;
The customFields
dictionary you specify will be sent along when your customer taps Send in the DKContactUsViewController
.
The following items can be customized in the support portal (all settings are optional and can be omitted if desired). To do so, copy the existing DeskKitSettings-Example.plist
file in this repository, and rename it to DeskKitSettings.plist
. The following (optional) keys can be set:
DKContactUsViewController
. You can override this string through this key. You can also specify the email subject in code through the subject
property on DKContactUsViewController
.showSubjectItem
property on `DKContactUsViewController
.userIdentity
property on DKContactUsViewController
.ContactUsShowSubjectItem
and ContactUsShowYourNameItem
to YES.userIdentity
property on DKContactUsViewController
. Change this value to YES if you want to allow the user to edit the email address set through userIdentity
.customeFields
property of DKContactUsViewController
.We have provided an example app to show how the above might work in your app. Here’s how to set it up and run it:
desk-kit
directory, cd DeskKitExample
pod install
cp DeskKitExample/DeskKitSettings-Example.plist DeskKitExample/DeskKitSettings.plist
open ./DeskKitExample.xcworkspace
AppDelegate.m
file and enter your hostname and API token in:[DKSession startWithHostname:@“yoursite.desk.com”
APIToken:@“YOUR_API_TOKEN”];
DeskKitExample/Supporting Files/DeskKitSettings.plist
to set your settings as above, if desired.