Starter App 指南
起步应用的跑通路径:绑定 S1 录音卡、把录音同步到手机、发起转写并查看逐字稿。SDK 与起步应用仓库尚未开放提供。
开发者平台处于内测阶段,接口契约以联调时提供的正式文档为准。账号由对接工程师开通,详见联系我们。
起步应用是一套集成 Embedded SDK 与转写 API 的 iOS 模板工程,仓库尚未开放提供。SDK 与仓库开放后,没有自己的移动应用时可以把它当模板直接用,已有应用时把它当集成参考;走完本指南,会得到一个能在真机上绑定 S1、同步录音、展示逐字稿的可运行应用。本页先给出它的构成与跑通路径,供合作方评估集成成本。
前置条件
SDK 与仓库开放后,跑通需要以下条件。
| 项目 | 要求 |
|---|---|
| 开发机 | macOS + Xcode 15 及以上 |
| 签名 | 一个 Apple ID(真机本地测试足够;上架 TestFlight / App Store 需付费开发者账号) |
| 测试设备 | 一部真机 iPhone(iOS 15+)。SDK 计划为 arm64 真机框架,模拟器不支持设备联调 |
| 硬件 | 一张 iKho S1 录音卡 |
| 凭证 | 已开通的 Client ID、API Key 与用户令牌,以开通邮件为准 |
跑通步骤(SDK 开放后)
以下步骤在 SDK 与起步应用仓库开放后适用。
# 仓库尚未提供,地址以开通邮件为准
git clone https://<开通邮件中的仓库地址>/ikho-starter-app.git
cd ikho-starter-app/ios
open IKhoStarterApp.xcodeprojIKhoConfig.xcconfig 填入三项。本地开发建议另建 IKhoConfig.local.xcconfig(已 gitignore)覆盖占位值。
# IKhoConfig.xcconfig
USER_ACCESS_TOKEN = 你的用户令牌
IKHO_CLIENT_ID = 你的 Client ID
IKHO_API_KEY = 你的 API KeyClient Secret 仅保存在你的后端,用于签发用户令牌,切勿写入应用。
一张 S1 同一时间只能绑定一个应用。测试结束、卸载应用前请先在设置里解绑设备,否则它无法再绑定到其他应用。
自定义品牌
起步应用默认是中性外观。仓库开放后,改这四处即可换成你自己的品牌。
| 要改什么 | 文件位置 |
|---|---|
| 应用名称 | Info.plist 的 CFBundleDisplayName |
| 主题色 | Sources/Theme/IKhoTheme.swift 中的颜色常量 |
| 应用图标 | Resources/Assets.xcassets/AppIcon.appiconset/(放 1024×1024 无透明通道 PNG) |
| 欢迎页 logo 与名称 | Sources/Onboarding/WelcomeView.swift |
常见坑
集成阶段容易遇到的五个问题与处理办法,先列在这里供评估。
真机运行后不弹蓝牙授权弹窗
先确认原生工程 Info.plist 里有 NSBluetoothAlwaysUsageDescription:缺这一项时系统不会弹授权窗,扫描会静默失败。若此前弹过一次并被拒绝,系统不会再弹,需到「设置 → 隐私与安全性 → 蓝牙」里手动为应用打开,或删除应用重装后重新触发授权。
凭证填错时,报错长什么样
Client ID 或 API Key 不对,通常在 SDK 初始化或首次请求就返回鉴权失败(HTTP 401 一类);用户令牌无效或过期,则多在绑定、同步或转写请求时收到鉴权类错误。排查时先核对 IKhoConfig.xcconfig 三项是否粘贴了多余空格或换行,再确认凭证与联调环境匹配。具体错误码与错误体,内测期以联调口径为准。
模拟器上扫描不到设备
属预期行为:iOS 模拟器没有蓝牙硬件,且 SDK 是 arm64 真机框架,凡涉及扫描、绑定、同步的环节必须用真机 iPhone。界面与非设备逻辑可以留在模拟器上开发。
换了手机,原来的 S1 绑不上
一张 S1 同一时间只保留一个绑定关系,直接在新手机上发起绑定不会成功。换机前先在旧手机的设置页解绑设备;旧手机已无法操作时,请联系对接工程师按内测流程处理。
同步速度慢
先查两件事:一是手机与 S1 的距离与遮挡,BLE 带宽随距离衰减明显,建议一米内、中间无金属遮挡;二是 Wi-Fi 快传开关是否开启,大文件走 BLE 通道会明显偏慢,开启快传后走 Wi-Fi 通道传输。两项都正常仍慢时,换一个无线干扰更少的环境再试。