跳到主要内容

iOS 环境要求与 SDK 引入

SDK Version: 1.0.0
Platform: iOS

环境要求​

  • iOS 17 或更高。
  • Swift tools 5.9 或更高。
  • Xcode 15 或更高版本建议使用当前稳定版。
  • BLE 功能必须在支持蓝牙的真机验证。

获取与添加产品​

本文档包不包含 SDK 源码或二进制。请通过 xTalk 约定的客户交付渠道获取正式 Swift Package，并以交付清单中的版本和校验信息为准。

SDK 1.0.0 提供：

  • XTalkMeshSdk
  • LowLatencyPtt
  • XTalkBleSdk
  • XTalkDeviceAuthSdk
  • XTalkFileTransferSdk
  • XTalkOtaSdk

在 Xcode 中选择 File → Add Package Dependencies，按交付方式完成下列任一操作：

  • 本地交付：选择解压后的 package 根目录。
  • 客户专用 Git 地址：使用 xTalk 随交付提供的 URL 和精确版本 1.0.0。

本文档不会虚构公共 Git URL。添加完成后，在 App target 的 General → Frameworks, Libraries, and Embedded Content 或 target dependency 设置中确认产品存在。只勾选实际需要的产品。

如果客户使用自己的 Package.swift，依赖名称和位置以交付清单为准，target 产品声明如下：

.product(name: "XTalkMeshSdk", package: "XTalkMeshSdk"),
.product(name: "LowLatencyPtt", package: "LowLatencyPtt"),
.product(name: "XTalkBleSdk", package: "XTalkBleSdk"),
.product(name: "XTalkDeviceAuthSdk", package: "XTalkDeviceAuthSdk"),
.product(name: "XTalkFileTransferSdk", package: "XTalkFileTransferSdk"),
.product(name: "XTalkOtaSdk", package: "XTalkOtaSdk")

上面的 package identity 可能随客户收到的目录名或 URL 改变；product 名称固定。

权限​

在客户 App 的 Info.plist 添加面向用户的蓝牙用途说明：

<key>NSBluetoothAlwaysUsageDescription</key>
<string>Bluetooth is used to discover and communicate with xTalk devices.</string>

如果客户部署目标仍覆盖旧系统策略，可同时提供 NSBluetoothPeripheralUsageDescription。用途说明必须与客户 App 的实际业务一致。

SDK 不负责弹出客户自己的权限引导页。首次扫描前由 App 解释蓝牙用途；出现 .permissionDenied 后引导用户到系统设置，不要循环请求。

导入​

import XTalkMeshSdk
import LowLatencyPtt
import XTalkBleSdk
import XTalkDeviceAuthSdk
import XTalkFileTransferSdk
import XTalkOtaSdk

六个产品按业务选用。Mesh、Low Latency PTT、文件传输和 OTA 都通过各自文档定义的 transport 或 BLE 会话协作；只使用认证 SDK 的 UART/其他传输客户无需导入 BLE 产品。

最小编译检查​

import XTalkBleSdk
import XTalkDeviceAuthSdk

@MainActor
func makeSdkObjects(transport: any DeviceAuthTransport) {
    let ble = XTalkBleClient()
    let authenticator = XTalkDeviceAuthenticator(transport: transport)
    _ = ble.connectionState
    _ = authenticator.state
}

如果模块无法导入，先检查产品是否加入正确的 App target，而不是只加入工程。若真机扫描没有结果，再检查权限、系统蓝牙状态和设备是否广播；模拟器不能替代 BLE 真机验收。

发布构建检查清单​

  • 客户 App 的 Deployment Target 不低于 iOS 17。
  • Release target 同样链接实际使用的产品；不要只在 Debug configuration 中添加。
  • Info.plist 的用途说明存在且可被最终归档读取。
  • Swift concurrency 警告已处理：SDK 对象和 transport 在 MainActor 上使用。
  • 真机完成扫描、连接、atReady、认证、断开和重连测试。

返回接入总览