# Starter App 指南

> 起步应用的跑通路径:绑定 S1 录音卡、把录音同步到手机、发起转写并查看逐字稿。SDK 与起步应用仓库尚未开放提供。

本页描述的是 Embedded SDK 的接口形态设计,SDK 尚未开放发放。需要「用 iKho 硬件采集并绑定到你的 App」的合作方,请通过[联系我们](/docs/mcp-cli/contact/)登记需求,我们会在 SDK 开放时通知。
当前已可用的是服务端三组接口:[认证](/docs/api-reference/auth/overview/)、[文件上传](/docs/api-reference/file/overview/)、[转写](/docs/api-reference/transcription/overview/)。可以先用你自己的音频跑通转写链路,见[后端篇教程](/docs/embedded/tutorial-backend/)。

开发者平台处于内测阶段,接口契约以联调时提供的正式文档为准。账号由对接工程师开通,详见[联系我们](/docs/mcp-cli/contact/)。

起步应用是一套集成 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 与起步应用仓库开放后适用。

  
    1

    克隆起步应用仓库
起步应用仓库尚未提供。仓库开放后,地址随开通邮件发放,届时按以下方式克隆。

  bash
    
  

  
```
# 仓库尚未提供,地址以开通邮件为准
git clone https://<开通邮件中的仓库地址>/ikho-starter-app.git
cd ikho-starter-app/ios
open IKhoStarterApp.xcodeproj
```

  

  
    2

    填入 Client 凭证
拿到工程后,打开 `IKhoConfig.xcconfig` 填入三项。本地开发建议另建 `IKhoConfig.local.xcconfig`(已 gitignore)覆盖占位值。

  IKhoConfig.xcconfig
    
  

  
```
# IKhoConfig.xcconfig
USER_ACCESS_TOKEN = 你的用户令牌
IKHO_CLIENT_ID    = 你的 Client ID
IKHO_API_KEY      = 你的 API Key
```

Client Secret 仅保存在你的后端,用于签发用户令牌,切勿写入应用。

  

  
    3

    真机运行
用数据线连接 iPhone,在 Xcode 顶部选它为运行目标,按 ⌘R 构建。首次运行需在 Signing 面板选择你的开发者团队。模拟器不支持设备联调。

  

  
    4

    绑定 S1 录音卡
打开系统蓝牙,应用会自动扫描附近的 S1;在列表中选中你的设备,完成加密绑定。绑定成功后进入主界面,可看到设备电量与存储。

  

  
    5

    同步并转写
在录音列表里选择设备上的录音,同步到手机后发起转写,稍候即可查看带说话人与时间戳的逐字稿。

  

一张 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 通道传输。两项都正常仍慢时,换一个无线干扰更少的环境再试。

## 下一步

[Starter App 规格 起步应用规划了哪些能力与界面,目录结构如何组织。 查看规格](/docs/embedded/starter-app-specs/)

[iOS SDK 接口形态 设备能力的完整方法与回调形态,供评估集成方式。 打开 iOS SDK](/docs/embedded/ios-sdk/)