fishjam-react-native-client

用途

Fishjam React Native Client 是 Fishjam 提供的 React Native / Expo SDK，用于在 iOS 与 Android 应用中实现音视频流媒体能力。它面向需要编写调用 Fishjam 的 React Native 或 Expo 应用的开发者。

它重新导出了 Web 端 @fishjam-cloud/react-client 的 Hook 接口，用移动端感知的实现覆盖了部分 Hook，并新增了仅移动端可用的 API。

主要能力

与原样重新导出的 Hook（行为与 Web SDK 一致）：useConnection、useDataChannel、useSandbox、useUpdatePeerMetadata、useVAD、Variant、InitializeDevicesSettings。

移动端覆盖实现（调用签名与 Web 相同，内部适配 React Native）：useCamera、useMicrophone、useScreenShare、useCustomSource、useInitializeDevices、useLivestreamStreamer、useLivestreamViewer、usePeers。

仅移动端提供的 Hook / API：

useCameraPermissions、useMicrophonePermissions：查询 / 申请 iOS 与 Android 设备权限。
useForegroundService：在 Android 应用进入后台时保持音视频与屏幕共享活跃。
useCallKit、useCallKitEvent、useCallKitService：iOS CallKit 集成，将 Fishjam 会话视作原生电话。
useAudioOutput 与 AudioDeviceType：切换音频路由（扬声器 / 听筒 / 蓝牙）。
RTCView、RTCPIPView：用于渲染视频轨道的原生组件，替代 <video>。
ScreenCapturePickerView 与 startPIP / stopPIP：iOS 屏幕选择器与画中画的原生组件 / 函数。

使用方式

安装：

npm install @fishjam-cloud/react-native-client @fishjam-cloud/react-native-webrtc

@fishjam-cloud/react-native-webrtc 是 peerDependency，必须显式安装。不要安装上游的 react-native-webrtc（未 fork 的包），否则会冲突。

Expo 插件注册（app.json）：

{
  "expo": {
    "plugins": [
      [
        "@fishjam-cloud/react-native-client",
        {
          "android": {
            "enableForegroundService": true,
            "enableScreensharing": true
          },
          "ios": {
            "enableScreensharing": true,
            "broadcastExtensionTargetName": "MyAppScreenSharing",
            "broadcastExtensionDisplayName": "MyApp Screen Sharing",
            "appGroupContainerId": "group.com.myapp.screensharing",
            "mainTargetName": "MyApp"
          }
        }
      ]
    ]
  }
}

随后执行 npx expo prebuild 生成原生代码。

基础用法示例：

import { FishjamProvider } from '@fishjam-cloud/react-native-client';

export default function App() {
  return (
    <FishjamProvider fishjamId={process.env.EXPO_PUBLIC_FISHJAM_ID!}>
      <Room />
    </FishjamProvider>
  );
}

FishjamProvider 在移动端与 Web 端的差异：移动端 provider 是 React 版本的轻量封装，但不支持两个 prop。persistLastDevice 在移动端不支持（无 localStorage，设备选择由操作系统管理）；fishjamClient 在移动端仅内部使用（SDK 会以 clientType: 'mobile' 自行构建）。其余 prop（fishjamId、reconnect、constraints、bandwidthLimits、videoConfig、audioConfig、debug）与 Web 一致。

关键规则

安装 @fishjam-cloud/react-native-webrtc（fork 版本），但不要安装上游 react-native-webrtc。该 fork 是 @fishjam-cloud/react-native-client 的 peerDependency，必须显式添加。安装上游未 fork 的 react-native-webrtc 会与 fork 冲突并破坏原生构建。
Expo 插件即使在 bare workflow 下也是必需的。Expo CNG（托管）模式：在 app.json / app.config.ts 中注册；bare 模式：仍需注册并执行 npx expo prebuild，或按 native-setup.md 手动完成原生步骤。
在 useInitializeDevices 之前申请权限。iOS 尤其如此，若未声明并授予 NSCameraUsageDescription / NSMicrophoneUsageDescription，设备初始化会静默失败。
Android 后台推流必须使用前台服务。用户将应用切至后台时，Android 会挂起 WebRTC 对等连接，除非有前台服务在运行，useForegroundService 用于解决此问题。
iOS 屏幕共享需要广播扩展（Broadcast Extension），即由 Expo 插件生成的独立 iOS target。需配置 broadcastExtensionTargetName 与 appGroupContainerId，插件会在 prebuild 时生成。
iOS 画中画需要插件开关：ios.supportsPictureInPicture: true，以及针对 CallKit 配对通话的 enableVoIPBackgroundMode: true。

使用提示

使用前建议先阅读 ../platform/SKILL.md 了解领域模型，并阅读 ../react-client/SKILL.md 了解共享的 Hook 目录。本技能聚焦移动端差异部分（权限、前台服务、屏幕共享广播扩展、CallKit、音频路由、Expo 插件）。与 Web SDK 行为完全相同的 Hook 不再重复说明。

适用场景

适用于编写调用 Fishjam 的 React Native 或 Expo 应用，以及配置 Fishjam 移动端 SDK、权限、后台服务、屏幕共享、CallKit、音频路由与 Expo 插件等场景。

限制

资料未提供收费、价格、性能指标或平台以外的支持信息。useSandbox 的 RoomType 在两端存在差异：Web SDK 接受 'audio_only'（下划线），React Native SDK 接受 'audio-only'（连字符），在任一平台传入错误形式都会导致 Sandbox API 拒绝请求。

参考资料

native-setup.md：安装与 Expo 插件选项（Android + iOS）、bare workflow 手动步骤、prebuild 流程。
permissions.md：useCameraPermissions、useMicrophonePermissions、先申请后初始化的模式。
rtcview.md：渲染视频，RTCView props（streamURL、trackId、mediaStream）、RTCPIPView、镜像与样式。
screen-sharing.md：Android MediaProjection 与 iOS Broadcast Extension、ScreenCapturePickerView、app-group 注意事项。
foreground-service.md：ForegroundServiceConfig、Android 权限、iOS 后台模式。
picture-in-picture.md：RTCPIPView、startPIP、stopPIP、插件开关。
callkit.md：useCallKit、useCallKitEvent、useCallKitService、CallKitConfig、CallKitAction。
audio-output.md：useAudioOutput、AudioDeviceType、切换扬声器 / 听筒 / 蓝牙。
mobile-hook-overrides.md：各 Hook 相对 Web SDK 的行为差异。
example-projects.md：fishjam-cloud/examples 仓库 mobile-react-native/ 下的可运行应用。