desk-kit iOS SDK

DeskKit SDK 是一个框架，它使得将您的 Desk 网站的支持门户集成到您的 iOS 应用程序变得简单。SDK 支持在项目中安装框架的多种方法。

使用预构建框架安装

从 DeskKit SDK 版本 4.0 开始，预构建框架附在 GitHub 仓库的发行中。为了使用预构建框架

1. 从 Releases 下载适当的版本 Frameworks.zip 文件
2. 解压 zip 文件
   
3. 在 Xcode 中打开您的项目，选取您的目标。在“通用”标签页下，找到“已嵌入的二进制文件”，然后点击 + 按钮。
4. 点击“添加其他...”按钮，导航到框架文件（DeskKit.framework、DeskAPIClient.framework、DeskCommon.framework）并选择它们。当提示时，请勾选“目的：如果需要则复制项”复选框。

重要提示：附带的预构建框架包含为多个架构（x86_64、i386、armv7、arm64）构建的二进制文件。根据此雷达，在提交到 AppStore 之前，您必须剥离模拟器切片（x86_64、i386）。

启动支持门户

在显示任何支持门户视图控制器之前，您必须启动一个 DKSession 来授权 Desk API

[DKSession startWithHostname:@“yoursite.desk.com”
                    APIToken:@“YOUR_API_TOKEN”];

您可以通过访问设置 > API 页面在站点的管理员控制台中获取 API 代令。您可以设置 API 应用程序，然后点击“您的移动 SDK 代令”链接以获取您需要在此处输入的代令。

配置 Apple 的 App Transport Security

如果您的支持中心的安全模式（管理员 -> 渠道 -> 高级设置 -> 安全模式）设置为“仅 HTTP”或“混合”，则需要配置 Apple 的 App Transport Security 以允许通过 SDK 通过 HTTP 内容。如果您的安全模式设置为“仅 HTTPS”，则可以跳过以下步骤。

• 打开您的 Info.plist 文件并添加以下内容

    <dict>
        <key>NSExceptionDomains</key>
        <dict>
            <key>yourdomain.desk.com</key>
            <dict>
                <key>NSIncludesSubdomains</key>
                <true/>
                <key>NSThirdPartyExceptionAllowsInsecureHTTPLoads</key>
                <true/>
            </dict>
        </dict>
    </dict>

• 这将仅适用于 Desk SDK 端点，并且不应影响在您的应用程序中加载的其他网络内容。

展示支持门户主题

DeskKitExample 应用通过顶级的 UISplitViewController 展示一个支持门户。当然，如何展示您自己的支持门户取决于您。然而，一个常见的起点是 DKTopicsViewController，这是一个基于表格的列表，列出了您门户中的所有支持主题。这个视图控制器还包含一个搜索栏，允许用户搜索文章。

DKSession 提供了一个方便的方法来创建此控制器

[DKSession newTopicsViewController]

您可能希望将自身设置为 DKTopicsViewControllerDelegate 并使用 DKArticleDetailViewController 来展示文章。请参考 DeskKitExample 应用以了解如何连接这两个视图控制器。

展示“联系我们”选项

DeskKitExample 应用亦演示了一种展示“联系我们”操作表的方式。 DSSession 有一个类方法来创建一个预配置的 UIAlertController，允许用户选择通过电子邮件联系您还是通过电话联系您，这取决于下面您启用的哪些设置。这个控制器可以如此实例化

[DKSession newContactUsAlertControllerWithCallHandler:^(UIAlertAction *callAction) {
        [[UIApplication sharedApplication] openURL:[[DKSession sharedInstance] contactUsPhoneNumberURL]];
    } emailHandler:^(UIAlertAction *emailAction) {
        [self alertControllerDidTapEmailUs];
    }];

当用户点击“电子邮件我们”时，您可以实例化和配置一个 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];
}

您可以通过 DeskKitSettings.plist（见下文）或通过您的 DKContactUsViewController 实例的属性来配置要显示的字段。代码中设置的属性优先于 DeskKitSettings.plist 设置。

如果您已经有了用户的姓名和电子邮件，您可以通过以下方式将它们传递给 DKContactUsViewController 实例

DKUserIdentity *userIdentity = [[DKUserIdentity alloc] initWithEmail:@“[email protected]”];
userIdentity.givenName = @“John”;
userIdentity.familyName = @“Doe”;
contactUsVC.userIdentity = userIdentity;

如果通过 userIdentity 属性没有提供用户的电子邮件，则表单中会显示一个必要的“您的电子邮件” UITextfield。

自定义字段

您通过 SDK 指定的自定义字段必须与您在网站管理控制台中定义的自定义字段匹配。

当您通过 DKSession 单例创建 DKContactUsViewController 时，SDK 会自动使用DeskKit设置（见下文）的 ContactUsStaticCustomFields键提供的字典设置customFields属性。您可以在运行时进一步修改customFields属性。

// 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;

您指定的customFields字典将在您的客户在DKContactUsViewController中点击“发送”时发送。

DeskKit 设置

以下内容可以在支持门户中进行自定义（所有设置都是可选的，如果需要可以省略）。要这样做，请复制此存储库中的现有 DeskKitSettings-Example.plist 文件，并将其重命名为 DeskKitSettings.plist。以下（可选）键可以设置：

• ContactUsEmailAddress - 默认情况下，SDK 将检查您在站点管理中设置的入站电子邮件地址列表，并使用它找到的第一个。如果您想使用您选择的电子邮件地址覆盖该设置，请使用此设置。
• ContactUsPhoneNumber - 如果需要，您可以提供一个电话号码，允许您的应用的用户从支持门户直接通过电话联系您。如果省略，则“通过电话联系我们”选项将不可用。如果设备无法打电话，则“通过电话联系我们”选项也将不可用。
• ContactUsSubject - 默认情况下，SDK 使用“通过iOS应用反馈”作为通过DKContactUsViewController发送电子邮件的主题。您可以通过此键覆盖此字符串。您还可以通过DKContactUsViewController上的subject属性在代码中指定电子邮件主题。
• 联系我们显示主题项 - 默认为否。在“联系我们”表单中的主题字段是可选的。如果您希望允许用户查看/编辑主题，请将此值更改为“是”。您也可以通过在 `DKContactUsViewController` 的 showSubjectItem 属性上重写此选项。
• 联系我们显示您的姓名项 - 默认为否。在“联系我们”表单中的用户全名字段是可选的。如果您希望允许用户查看/编辑通过表单发送的全名，请将此值更改为“是”。您可以通过在 `DKContactUsViewController` 上的 userIdentity 属性设置用户名的初始值。
• 联系我们显示所有可选项 - 默认为否。将此设置为“是”相当于将 ContactUsShowSubjectItem 和 ContactUsShowYourNameItem 设置为“是”。
• 联系我们显示您的电子邮件项 - 默认为否。由于用户电子邮箱地址是必需的，因此此切换只有在通过 `DKContactUsViewController` 的 userIdentity 属性设置电子邮件后才会生效。如果您希望允许用户编辑通过 userIdentity 设置的电子邮箱地址，请将此值更改为“是”。
• 联系我们静态自定义字段 - 该值是一个包含键的字典，这些键必须与您网站管理控制台中的自定义字段相匹配。此字典用于初始化 `DKContactUsViewController` 的 `customeFields 属性。
• 品牌ID - 如果您使用多个品牌，您可以在此处提供一个品牌ID，这将使门户仅限于显示该品牌中的主题和文章。如果您省略此设置，则门户将显示您支持中心中的所有主题和文章。可以通过转到您网站的“管理”部分，点击“渠道”，然后点击“品牌概览”来获取品牌ID。在右上角的下拉菜单中选择品牌后，品牌ID将显示在支持中心URL中。例如，在此支持中心URL “https://mysite.desk.com/?b_id=2” 中，品牌ID是2。

DeskKitExample应用程序

我们提供了一个示例应用程序来展示上述功能如何在您的应用程序中工作。以下是设置和运行它的方法：

1. 从 desk-kit 目录的根目录开始，执行 cd DeskKitExample
2. pod install
3. 将 DeskKitExample/DeskKitSettings-Example.plist 复制到 DeskKitExample/DeskKitSettings.plist
4. 打开 ./DeskKitExample.xcworkspace
5. 在Xcode中，打开 AppDelegate.m 文件，输入您的主机名和API令牌

[DKSession startWithHostname:@“yoursite.desk.com”
                        APIToken:@“YOUR_API_TOKEN”];

1. 在Xcode中，编辑 DeskKitExample/Supporting Files/DeskKitSettings.plist 设置您想要的设置，如果需要的话。
2. 在Xcode中，选择 Product > Run，或按 ⌘R 运行应用程序。