# React Native 接入

> React Native 桥模块的接口形态设计:在 RN 里复用 Embedded 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/)。

桥模块开放后,React Native 团队可以复用 Embedded 的 iOS 能力,而不必用原生写整套设备逻辑。桥模块底层仍是 [iOS SDK](/docs/embedded/ios-sdk/),通过原生模块把方法与事件暴露到 JS 层。以下是它的接口形态与接入路径,方法名与参数以正式发布为准。

## 安装(开放后)

桥模块尚未开放提供。开放后随开通邮件发放仓库地址,拷贝进你的项目 `modules/` 目录即可被自动识别。桥模块不通过公共 npm 源分发,请不要按本页出现的名称去公共源安装同名包。

  bash
    
  

  
```
# 桥模块尚未提供,地址以开通邮件为准
git clone https://<开通邮件中的仓库地址>/ikho-embedded-react-native.git

# 拷贝模块到你的 RN 工程
cp -R ikho-embedded-react-native/modules/ikho-embedded your-app/modules/ikho-embedded
```

## 原生模块链接

拿到桥模块后,在 `app.json` 声明蓝牙与麦克风权限,然后执行 prebuild 让原生模块生效。

  app.json
    
  

  
```
{
  "expo": {
    "ios": {
      "infoPlist": {
        "NSBluetoothAlwaysUsageDescription": "用于连接 iKho 录音卡并同步录音",
        "NSMicrophoneUsageDescription": "用于在应用内录制与试听音频",
        "UIBackgroundModes": ["bluetooth-central"]
      }
    }
  }
}
```

  bash
    
  

  
```
npx expo prebuild -p ios
npx expo run:ios --device   # 需真机 iPhone
```

## TS 侧 API 形态

桥模块在 JS 层的调用形态如下,以正式发布为准。

  ts
    
  

  
```
import { IKhoEmbedded } from 'ikho-embedded';

await IKhoEmbedded.configure({ userToken });

const subs = [
  IKhoEmbedded.onScanResult(({ devices }) => { /* 展示设备 */ }),
  IKhoEmbedded.onProgress(({ recordingId, progress }) => { /* 同步进度 */ }),
];

await IKhoEmbedded.scanDevices();
await IKhoEmbedded.bindDevice({ serialNumber });
const { files } = await IKhoEmbedded.syncRecordings();

subs.forEach((s) => s.remove());
```

## 与纯原生的能力差异

桥模块与原生 SDK 均尚未开放发放。按设计,桥模块覆盖最常用的设备能力;更进阶的用法(如 Wi-Fi 快传的完整控制)需扩展桥模块或直接用原生 iOS SDK。下表是开放后的能力覆盖差异。

| 能力 | 纯原生 iOS SDK | React Native 桥 |
|---|---|---|
| 扫描与绑定 | 支持 | 支持 |
| BLE 同步 | 支持 | 支持 |
| 设备状态与电量 | 支持 | 支持 |
| Wi-Fi 快传 | 支持 | 需扩展桥方法 |
| 后台续传 | 支持 | 需额外配置 |

完整方法与回调形态以 [iOS SDK](/docs/embedded/ios-sdk/) 一页为准;桥模块只是它的 JS 封装。

## Expo 适配

桥模块包含原生代码,这决定了它无法在 Expo Go 里运行:Expo Go 是一只预编译的通用客户端,只带官方内置的原生库,不会加载你项目里自带的原生模块。在 Expo Go 中调用桥模块,典型表现是模块对象为 `undefined`,或调用时抛出「找不到 native module」一类错误;这不是集成写错了,是 Expo Go 的既定限制。

两条路二选一。其一,构建开发客户端(dev client):给项目加上 `expo-dev-client`,再用 `npx expo run:ios --device` 打一个包含桥模块的自定义客户端装到真机,日常开发仍保留 Expo 的加载与调试体验。其二,执行 `npx expo prebuild -p ios`(即上文「原生模块链接」一节的做法)生成 `ios/` 原生工程,此后按带原生目录的 React Native 工程维护。无论走哪条路,设备联调都必须在真机 iPhone 上进行。