iOS 配置

[English Version]

在 iOS 系统中创建 RainMaker 项目

所有与配置相关的字段都保存在属性列表文件 Configuration.plist 中，您可以在 RainMaker 项目的根目录下找到这一文件，用 Xcode 打开并添加以下属性值。

AWS 配置

RainMaker 使用 Amazon Cognito 来提供移动应用中的认证、授权和用户管理服务，同时借助 AWS 服务提供 RESTful API 用于设备通信。您需要在应用中对其进行配置，这些设置将位于 Configuration.plist 文件中的 AWS Configuration 键中。

Key类型描述
App Client ID字符串（必需）用于识别用户池中的应用。获取该值：
- 用超级管理员账号登录 RainMaker 管理面板；
- 打开 Deployment Settings，从左侧导航窗格选择 Deployment details；
- 在 Cognito details 部分找到应用客户端 ID。
Authentication URL字符串（必需）第三方认证登录的 OAuth URL，请参考 如何获取认证 URL。
Base URL字符串（必需）与每个 API 终端节点相对应。获取该值：
- 用超级管理员账号登录 RainMaker 管理面板；
- 打开 Deployment Settings，从左侧导航窗格选择 Deployment Details；
- 找到 base url，这一 url 在 Deployment details 被识别为 API PATH URI。
Redirect URL字符串在此处添加以下值：
<Bundle ID>://success。
创建重定向 URL 的具体步骤请参阅 添加 URL 方案
Claim URL字符串（可选）Assisted Claiming 的 API 终端节点。不适用于客户部署，可删除或保持空白。

[注意：如何获取 RainMaker 管理面板的 URL？
- RainMaker 管理面板位于 Cloudformation 堆栈中。
- 超级管理员用户在部署 RainMaker 后会收到邮件。
- 此邮件中会提供 RainMaker 管理面板的 URL。]

应用配置

Key类型描述
Enable Schedule布尔在应用中启用 (Yes) 或禁用 (No) 调度功能。
Enable Scene布尔在应用中启用 (Yes) 或禁用 (No) 场景功能。
Enable Local Control布尔在应用中启用 (Yes) 或禁用 (No) 本地控制功能。
Enable Grouping布尔在应用中启用 (Yes) 或禁用 (No) 分组功能。
Enable Sharing布尔在应用中启用 (Yes) 或禁用 (No) 分享功能。

外部链接

以下链接用于在应用浏览器中打开与项目相关的文件。请在 Plist 文件中为每个文件类型提供有效链接。

  1. 使用条款
  2. 隐私政策
  3. 文档

配网设置

为应用进行配网设置。

Key类型描述
BLE Device Prefix字符串应用程序将搜索名称中带有此前缀的 Bluetooth LE 设备。
ESP Allow Prefix Search布尔只有在该值被设置为 "true" 时，应用程序允许通过前缀进行搜索。
ESP Security Mode字符串可能值
secure：用于设备和应用之间的安全通信或加密通信。
unsecure：用于设备和应用之间的非安全通信或未加密通信。
ESP Transport字符串可能值
BLE：只支持 Bluetooth LE 设备配置。
SoftAP：只支持 SoftAP 设备配置。
Both：同时支持 Bluetooth LE 和 SoftAP 设备配置。
ESP Scan Enabled布尔在应用中启用或禁用扫描功能。

App Group

App Group 功能支持由一个团队开发的多个应用程序共同维护共享容器（存储空间）。在这种情况下，该容器由应用程序和扩展通知服务共享。共享容器用于存储节点的详细信息，这些信息用于通知服务中的自定义通知功能。更多信息请参阅 此处。

配置 App Group

  1. 进入苹果开发者控制台，打开标识符：https://developer.apple.com/account/resources/identifiers/list。
  2. 点击 + 图标，添加新的标识符。
  3. 从列表中选择 App Groups 并点击 Continue。

ios_config_app_group

  1. 为您的 App Group 添加 Description 和 Identifier 字段，点击 Continue。

ios_config_register_app_group

  1. 检查改动并点击 Register 保存更改。

ios_config_register_app_group-1

在 Xcode 中配置 App Group

  1. 打开 Xcode 项目，在您的主应用目标中，打开 Signing & Capabilities。
  2. 在 App Groups 性能下勾选您之前配置的 App Group。

ios_config_xcode_app_group

  1. 针对应用中的 PushNotificationExtension 目标，重复步骤 1 和 2。
  2. 打开项目中的 Configuration.plist 文件。
  3. 将 App Group 的键值设置为您的 App Group ID。

ios_config_xcode_app_group-1

推送通知设置

通知设置 (Push Notifications) 服务在项目中默认为启用状态。如果您想在开发时测试该服务，请参照下图，但您需要将端点从 APNS 改为 APNS_SANDBOX。

ios_config_endpoint_setting

注意：发布应用或将应用上传至 App Store 时，请将端点重新设置为 APNS。

添加 URL 方案

App Bundle ID 应被包含在 RainMaker 项目中的 Info.plist 文件。 ESPRainMaker > Info，向下滚动至 URL Types 并点击展开。请按照下图重新设置您的重定向 URL。

url_scheme

创建重定向 URL

ESP RainMaker 应用的重定向 URL 将为：

com.espressif.rainmaker.softap://success

将 com.espressif.rainmaker.softap 替换为您应用的 Bundle ID，此时应用的重定向 URL 将变为：

com.your_application_id.app://success

其他设置

您也可以通过设置 Configuration.plist 中的 App Theme Color 键值，为您的应用选择主题颜色，例如将颜色设置为十六进制值 #FFFFFF。

Alexa 账户关联

Alexa 账户关联 (Account Linking) 功能允许用户从自有应用程序中的服务关联 Alexa 账号。下文介绍了如何在自有应用端进行配置以使用该功能。

注意：更多关于 Alexa 账户关联和云端配置的信息，请参考 Alexa 账户关联。

创建 iOS 通用链接

若您的应用支持通用链接，iOS 用户在打开您的网站链接后能够直接重定向至您的应用，而无需借助 Safari 浏览器。若您的应用不支持通用链接，用户点击网站链接后将前往 Safari 浏览器。

请参考 iOS 文档中的 通用链接。

为你的应用程序创建通用链接，请参考以下步骤：

  1. 在您应用的 Xcode 项目中，通过导航选择 .xcodeproj 文件。在 Signing and Capabilites 部分，选择 Associated Domains。在 Domain 下，点击 + 图标，并添加如下信息：
applinks:domain name of the associated website

  1. 创建新文件并将其命名为 "apple-app-site-association"，该文件即为 json 文件，包含以下信息：
{
 "applinks": {
   "apps": [],
   "details": [
     {
       "appID": "ABCD1234.com.apple.wwdc",
       "paths": ["*"]
     }
   ]
 }
}
注意：请不要将 .json 添加至 apple-app-site-association 文件中。

  1. 上述文件中的 appID 格式如下：<TEAMID.您的应用的 Bundle ID>。 更多关于团队 ID 的信息，请参阅 此处；更多关于应用 Bundle ID 的信息，请参阅 此处。

  2. paths 数组中包含了应用支持使用通用链接的所有网站路径。路径值若为 * 则表示应用支持网站的所有可能路径。

  3. apple-app-site-association 文件必须放在服务器的根目录下或根目录下的 .well-known 文件夹中。

  4. 文件需要通过 HTTPS 访问，无需任何重定向，网址为 https://<domain>/apple-app-site-association 或 https://<domain>/.well-known/apple-app-site-association。

配置账户关联

打开 Configuration.plist 文件，在 AWS Configuration 部分为添加以下属性值：

Key类型描述
Authentication URL字符串第三方认证登录的 OAuth URL，请参考 如何获取认证 URL。

打开 Configuration.plist 文件，在 ESP Alexa Configuration部分为添加以下属性值：

Key类型描述
Alexa Client Id字符串Alexa client ID。您可按照以下步骤获取该值：
- 前往 Alexa 开发者控制台
- 打开 Skill
- 打开 Build 标签页
- 打开 Permissions
- 找到 Alexa Client Id
Alexa Client Secret字符串Alexa client secret。您可按照以下步骤获取该值：
- 前往 Alexa 开发者控制台
- 打开 Skill
- 打开 Build 标签页
- 打开 Permissions
- 找到 Alexa Client Id
Alexa RM Client Id字符串请参考 获取 Alexa 和 GVA 客户端 ID 的步骤 并复制 esp-rainmaker-alexa-skill 的客户端 ID
Skill Id字符串用于链接 Skill 的 Skill ID。您可按照以下步骤获取该值：
- 前往 Alexa 开发者控制台
- 打开 Skill
- 打开 Smart Home
- 找到 Skill Id
Skill Stage字符串可能值：
live：用于活跃 Skill。
development：用于开发中的 Skill。
Redirect URL字符串调用 Alexa 认证码和 RainMaker 认证码（或自定义用户认证服务）时可获取重定向 URL。该值也被用作 iOS 应用的应用链接。请参考 为移动应用创建重定向 URL 了解如何配置应用链接。
Alexa Access Token URL字符串用于从 Alexa 认证码中获取 Alexa 访问令牌的 API 端点。
请参考 获取 Alexa 访问令牌 URL 中的步骤。

苹果开发者设置

在苹果开发者控制台创建应用 ID

  1. 打开 苹果开发者网站。

  2. 点击左侧菜单中的 Identifiers，点击 + 图标，添加新的标识符。

    Apple Identifiers

  3. 从列表中选择 App IDs，然后点击 Continue。

    Apple Sign In

  4. 从类型中选择 App。

    App type

  5. 为您的应用添加 Bundle ID 和 Description 字段，请保证 Bundle ID 与您在 RainMaker iOS 应用中所使用的 ID 保持一致。

    Register AppId

  6. 向下滚动页面，选择 Push Notifications 和 Sign In with Apple 功能，并点击 Continue。

    Register AppId

  7. 检查更改并确认配置。

  8. 请记录下您的 Team ID App ID Prefix 值和 Bundle ID 值，然后点击 Register 保存更改。

    Register AppId

← 安卓配置通知 Payload →