Signaling 2.x 移行に関する補足資料
はじめに
本文書は、Agora 社が提供する公式の「Signaling 2.x への移行ガイド」 (英題: Signaling Migration guide ) を補完するテクニカルリファレンスです。
Signaling 1.x は 2026 年 7 月 15 日にサポート終了 (Sunset) が予定されています。後継バージョンである 2.x への対応化を進めていく中で、表面化しそうな技術課題を紹介・整理し、円滑な移行作業とトラブルシューティングの迅速化を支援することを目的としています。
2.x メッセージングの基盤：Pub/Sub モデルの採用
Signaling 2.x では、メッセージ送受信の仕組みとして「Pub/Sub」モデルを意識して設計されています。
これまでの 1.x では、送受信が密結合した設計でした。ユーザーがメッセージを送るにはチャンネルへの接続が必須ですが、その間は他のユーザーからのメッセージを受信し続けることになります。
2.x の Pub/Sub モデルでは、送信と受信の操作が完全に独立 ( decoupled ) しています。
例えば、メッセージ配信だけの機能が実装できる一方、メッセージの受信のみに特化した機能を実装することができるようになります。
1.x と 2.x での機能相互性・共存について
Signaling 2.x の基盤は 1.x と大きく異なり、一部の機能については相互互換性が保証されています。
既存の 1.x システムを維持しながら段階的に 2.x へ移行する場合や、新旧バージョンが混在する環境での互換性を確認したい際にご参考ください。
| 機能・概念 | 制限事項など |
| チャンネル名、uid の命名規則 |
2.x では「 _ 」で始まる名称や「 . 」を含む名称が禁止されています。 2.x における命名規則について、詳細は以下のドキュメントを参照ください。 |
| 各ユーザーオンライン状態の取得 |
Signaling SDK v1.x の利用ユーザーを、 2.x の Presence 機能 ( 例: getOnlineUsers API など ) で検知する必要がある場合、バックエンド側の追加設定が必要になる場合があります。 詳しくはサポートまでお問い合わせください。 |
| メッセージング |
1.x の Channel Messaging、Peer-to-Peer Message はそれぞれ 2.x の Message Channel、User Channel に対応しており、相互にメッセージ通信 (1 メッセージあたり、最大 32 KB)が可能です。 もし相互通信に失敗する場合、チャンネル名、uid の命名規則 (上項) に違反していないか、2.x 側の実装が正しくされているか、下各項のドキュメントを参考にご確認ください。 |
| Call Invitation | 1.x の Call Invitation 機能と、2.x CallAPI の相互運用はサポートされません。 |
| API Call Limit |
1.x と2.x それぞれで API Call LImit が設定されています。 Limit を超えた分の API コールに対しては、処理されない場合があります。 一部の API コールに対して、申請ベースでの上限緩和が可能です。 詳細は以下ドキュメントからご確認ください。 |
| Token |
2.x でサポートされる Token の種類は AccessToken2 のみとなります。 1.x (v1.5.0以降) は、従来の AccessToken と AccessToken2 の両形式に対応しているため、あらかじめ Token サーバーを更新しておくことで、既存クライアントの動作を維持したまま、2.xの導入・共存が容易になります。 |
| Offline Message | 1.x の Offline Message 機能は v1.5 で廃止となりました。 2.x では本機能を直接代替する機能はございません。 |
| メッセージ履歴 (Historical Message) |
1.x のメッセージ履歴機能は v1.5 で廃止となりました。 2.x ではベータ版として提供されていますが、1.x との相互互換性はございません。 |
| 画像・ファイル送信 |
当機能は v1.5 以降、画像・ファイルを直接送受信する機能は廃止となりました。 テキスト以外のメッセージ送受信が引き続き必要な場合におきましては、実データをクラウドストレージで管理し、そのメタ情報やリンクをメッセージとして送信する、等のロジック開発をご検討ください。 テキスト型、リンク型、など複数のメッセージ型を扱う場合、これらデータ構造の設計を予めご検討いただくことを推奨します。 詳細は以下ドキュメントからご確認ください |
実装に関する Q＆A
Q: 2.x への移行後、NOT_ENABLE_RTM エラーが発生して接続できません。
A: Agora Console 上で Signaling 2.x の機能が有効化されているかをご確認ください。 2.x を利用するには、プロジェクトの設定画面で明示的に有効化 (Enable ) する操作が必要です。
2.x では Agora Console の「Project Management」から対象プロジェクトの編集 (Configure) 画面に入り、「All features」 > 「Signaling」 > 「Basic information」にて データセンター (Data Center) から、ご利用の地域に近いエリアを選択して有効化する必要があります。
データセンター設定では、チャンネルメタデータ、ユーザーメタデータを保存するストレージのリージョンを設定します。
一度選択し確定すると、後から変更することはできませんのでご注意ください。
Q: アプリのタスクキルやブラウザのタブを閉じた際、視聴者数の減算 (退出検知) が 1.x の時より遅れるのはなぜですか？
A: 2.x では presenceTimeout の設定値に基づいてオフライン判定が行われるためです。1.x では退出判定に至るタイムアウトは 30 秒の固定時間でしたが、2.x では 300 秒 (5 分) がデフォルトとして設定されています。
即時性を求める場合は、プロジェクトの要件に合わせてこの値を短く設定することをお勧めします。ただし、短すぎるとネットワークの瞬断で意図せずオフライン判定されるリスクがあるため、バランスの検討が必要です。
Q:Video SDK と Signaling SDK を併用すると、ビルドエラーが発生します。
A: 両 SDK に含まれる aosl ライブラリが競合することが主な原因です。 以下のドキュメントを参考に対応をいただくことで問題を回避いただけます。
Q: 1.x から 2.x へメッセージを送っても失敗してしまう。
A: 「1.x と 2.x での機能相互性・共存について > メッセージング」をご確認ください。
Q: 1.x で使用していたユーザー ID やチャネル名をそのまま 2.x でも使えますか？
A: 注意が必要です。2.x では命名規則が厳格化されており、「 _ 」 (アンダースコア ) で始まる名前や「 . 」 (ドット ) を含む名前は使用できません。1.x でこれらの文字を使用していた場合、2.x への移行タイミングで ID 体系の見直しが必要になるケースがあります。
2.x での命名規則の詳細は以下のドキュメントを参照ください。
・Channel basics > Channel Naming
Signaling 1.x → 2.x 機能マッピング表
1.x からの移行に伴う、それぞれに対応する 2.x の機能について、一部を掲載します。
※ iOS 版の API 名を引用しています。開発プラットフォームに対応する正確な API 名はリファレンスからご確認ください。
1. SDK のセットアップ
| 1.x の機能・概念 | 1.x API | 2.x API | 概要・補足 |
| SDKの初期化 | initWithAppId | initWithConfig |
Initialize an RTM Client instance を参照 ※2.x では初期化時に userId が必須となり、後から変更できません。切り替え時は再生成が必要です。 |
| ログイン | loginByToken | loginByToken | Log in to Signaling を参照 |
| イベント一覧 | 各種 API ドキュメント参照 | Event Listeners を参照 |
1.x のリスナー群が再編成されています。 詳細は Event notifications を参照 |
| アクセスエリア制限 | 初期化前 (initWithAppId) 、setRtmServiceContext で設定 | 初期化時 (initWithConfig) に指定 ※ Config 引数の areaCode として指定 |
Restrict access area を参照 |
2. メッセージング
| 1.x の機能・概念 | 2.x での扱い | 概要・補足 |
| Channel Message | Message Channel | Message channels を参照 |
| Peer-to-Peer Message | User Channel | User channels を参照 |
| 画像・ファイル送信 | n/a |
当機能は v1.5 以降、画像・ファイルを直接送受信する機能は廃止となりました。 テキスト以外のメッセージ送受信が引き続き必要な場合、「1.x と 2.x での機能相互性・共存について > 画像・ファイル送信」をご参考ください。 尚、Agora 社では、リッチテキストやバイナリファイルの送受信機能を備えた Agora ChatSDK を開発・用意しております。 |
3. ユーザーのオンライン状態、属性情報管理
| 1.x の機能・概念 | 2.x での扱い | 概要・補足 |
| オンライン状態取得 | Presence | User presence and custom status を参照 |
| User Attributes | User Metadata |
2.x では: ・ユーザー単位だけでなく、チャンネルにも Metadata の付与・管理が可能です。 ・バージョニングやロックの概念が導入されています。 詳しくは User metadata and channel metadata を参照 |
4. その他機能の互換性について
| 1.x の機能・概念 | 2.x での扱い | 概要・補足 |
| コール招待 (Call Invitation) | n/a | 同様の機能は CallAPI モジュールで補完できますが、1.x との相互互換性はございません。 |