@hello-x/react-native

HelloX 電話機能 SDK の React Native 向け実装。Asterisk 経由の SIP 通話 (発信・着信・通話制御) を JS API として提供します。

インストール

npm install @hello-x/react-native react-native-webrtc react-native-sound @react-native-async-storage/async-storage

@react-native-async-storage/async-storage はパッケージ側で static import しているため、カスタム storage 実装 (MMKV / Keychain / SecureStore など) を渡す場合でも install は必須です。

react-native-sound は着信音の再生に使うネイティブモジュールです。SDK が起動時に import するため、ringtone: false（着信音を鳴らさない設定）でも install は必須です。install 後はアプリのネイティブ再ビルドが必要で（iOS: pod install → 再ビルド、Android: 再ビルド）、Metro のリロードだけではリンクされません。未リンクのまま起動すると SDK の読み込みに失敗します（詳細は「着信音」節）。

サポートバージョン

• React Native >= 0.84
• react-native-webrtc >= 124.0.0
• react-native-sound >= 0.11
• @react-native-async-storage/async-storage >= 2.0

着信音

着信時に着信音を鳴らします (既定で有効)。react-native-sound で同梱音源を再生します。

1. react-native-sound のネイティブリンク（必須）

react-native-sound はネイティブモジュールです。npm install 後にアプリのネイティブ再ビルドを行ってください（iOS: cd ios && bundle exec pod install → 再ビルド、Android: 再ビルド）。Metro のリロードだけではリンクされません。未リンクのまま起動すると SDK の読み込み自体が失敗します（ringtone: false でも同様。SDK が起動時に react-native-sound を import するため）。

2. 音源ファイルの配置

同梱音源 hellox_ringtone.wav は react-native-sound の仕様上ネイティブバンドルから読み込むため、アプリのネイティブプロジェクトに配置する必要があります。ファイルは node_modules/@hello-x/react-native/assets/hellox_ringtone.wav にあります。

• Android: android/app/src/main/res/raw/hellox_ringtone.wav にコピー
• iOS: Xcode でアプリターゲットに hellox_ringtone.wav を追加 (Copy Bundle Resources)

未配置の場合は SDK 初期化時に警告ログ [HelloX] [ringtone] failed to load ... が出るだけで、クラッシュはせず着信処理 (応答 / 拒否) にも影響しません（着信音が鳴らないだけ）。この警告は console.warn 経由のため、dev ビルドでは LogBox（黄色）や各種ログに出ますが、release ビルドの画面には出ません。

3. iOS のサイレントスイッチについて（制約）

iOS では、本体側面のサイレントスイッチが ON（消音）のとき着信音は鳴りません。react-native-sound の既定オーディオセッションカテゴリが AVAudioSessionCategoryAmbient で、このカテゴリはサイレントスイッチに従うためです。マナーモード中でも着信音を鳴らしたい要件がある場合は、別途 Playback 等へのオーディオセッションカテゴリ変更が必要です。Android にこの制約はありません。

4. 無効化

着信音を鳴らさない場合は ringtone: false を渡します（前述のとおり react-native-sound の install / ネイティブリンク自体は必要です）。

const sdk = new HelloX({ tokens: { accessToken: "...", refreshToken: "..." }, ringtone: false });

ドキュメント

ネイティブ設定 (iOS / Android のマイク権限、register-globals の import など)・利用方法・API リファレンス・エラーハンドリング・トラブルシューティングは ドキュメントサイト に集約しています。