TRTCCalling API(Web)

最終更新日:2021-11-29 16:43:04

    TRTCCallingの概要

    TRTCCallingコンポーネントは、Tencent CloudのTencent Real-Time Communication(TRTC)とInstant Messaging(IM)サービスの組み合わせにより構成されており、1対1および複数人でのビデオ/音声通話をサポートしています。具体的な実装プロセスについては、リアルタイム音声通話(Web)をご参照ください。

    • TRTC SDK:TRTC SDKを低遅延のオーディオビデオ通話コンポーネントとして使用します。
    • IM SDK: IM SDKをシグナリング情報の送信と処理に使用します。

    TRTCCalling API

    イベントサブスクリプション/サブスクリプションのキャンセルに関するインターフェース関数

    このコンポーネントはイベントのディスパッチに基づいて管理します。アプリケーション層は、コンポーネントからディスパッチされるイベントにインタラクティブに応じて変更することができます。

    API 説明
    on(eventName, callback, context) イベントのサブスクリプション
    off(eventName, callback, context) イベントサブスクリプションの取消

    SDK 基本関数

    API 説明
    login({userID, userSig}) IMログインインターフェース。すべての機能を使用するためには、まずログインする必要があります
    logout() インターフェースからログアウトします。ログアウトした後は、ダイヤル操作ができなくなります

    通話操作に関連するインターフェース関数

    API 説明
    call({userID, type, offlinePushInfo})) シングル通話の招待
    groupCall({userIDList, type, groupID, offlinePushInfo}) グループチャット通話の招待
    accept() 通話招待に応答
    reject() 通話招待を拒否
    hangup() 現在の通話の終了

    ビデオ制御に関連するインターフェース関数

    API 説明
    startRemoteView({userID, videoViewDomID}) リモート画面レンダリングの起動
    stopRemoteView({userID}) リモート画面レンダリングの停止
    startLocalView({userID, videoViewDomID}) ローカル画面レンダリングの起動
    stopLocalView({userID}) ローカル画面レンダリングの停止
    openCamera() カメラの起動
    closeCamera() カメラの停止
    setMicMute(isMute) デバイスマイクのミュートの有無
    setVideoQuality(profile) ビデオ画質の設定
    switchToAudioCall() ビデオ通話を音声通話へ切り替え
    switchToVideoCall() 音声通話をビデオ通話へ切り替え
    getCameras() カメラデバイスリストの取得
    getMicrophones() マイクデバイスリストの取得
    switchDevice({deviceType, deviceID}) カメラまたはマイクデバイスの切り替え

    TRTCCallingの詳細

    TRTCCallingコンポーネントのインスタンスの作成

    まず、Tencent Real-Time Communicationコンソールでアプリケーションを作成し、SDKAppIDを取得する必要があります。
    その後、new TRTCCalling()メソッドを使ってTRTCCalling コンポーネントのインスタンスを取得することができます。

    let options = {
    SDKAppID: 0, // アクセスするときは、0をお客様のIMアプリケーションのSDKAppIDに置き換える必要があります
    // v0.10.2から、timパラメータを追加します
    // timパラメータはサービス内にすでに存在するTIMインスタンスに使用され、TIMインスタンスの一意性を保証します。
    tim: tim
    };
    let trtcCalling = new TRTCCalling(options);

    イベントのサブスクリプション/サブスクリプションキャンセルに関するインターフェース関数

    on(eventName, callback, context)

    コンポーネントからディスパッチされたイベントを監視するために使用します。詳細については、イベントリストをご参照ください。

    let handleInvite = function ({inviteID, sponsor, inviteData}) {
    console.log(`inviteID: ${inviteID}, sponsor: ${sponsor}, inviteData: ${JSON.stringify(inviteData)}`);
    };
    trtcCalling.on('onInvited', handleInvite, this);

    off(eventName, callback, context)

    イベント監視をキャンセルするために使用します。

    let handleInvite = function ({inviteID, sponsor, inviteData}) {
    console.log(`inviteID: ${inviteID}, sponsor: ${sponsor}, inviteData: ${JSON.stringify(inviteData)}`);
    };
    trtcCalling.off('onInvited', handleInvite, this);

    SDK基本関数

    login({userID, userSig})

    インターフェースにログインします。

    trtcCalling.login({userID, userSig})

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    userID String 現在のユーザーのID。文字列タイプ。アルファベット(a-zおよびA-Z)、数字(0-9)、ハイフン(-)、アンダーバー(_)のみ使用できます。
    userSig String Tencent Cloudによって設計されたセキュリティ保護署名。取得方法についてはUserSigの計算方法をご参照ください。

    logout()

    インターフェースからログアウトします。

    trtcCalling.logout()

    通話操作に関連するインターフェース関数

    call({userID, type, offlinePushInfo})

    1対1通話招待、そのうちtypeは通話タイプ、1は音声通話、2はビデオ通話です。

    説明:

    • v1.0.0およびそれ以降のバージョンで、timeoutパラメータを取り消しました
    • v1.0.0およびそれ以降のバージョンに、offlinePushInfoパラメータを新たに追加しました(オフラインプッシュはAndroidまたはiOS端末にのみ適用されます。WebおよびWeChat Mini Programはサポートしていません)。
    // v1.0.0より前
    trtcCalling.call({userID, type, timeout});

    // v1.0.0およびそれ以降のバージョン
    const offlinePushInfo = {
    title: '',
    description: '通話リクエストが1件あります',
    }
    trtcCalling.call({userID, type, offlinePushInfo})

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    userID String 被招待者のuserID
    type Number 1:音声通話、2:ビデオ通話
    timeout Number 0はタイムアウトしていないことを意味し、単位はs(秒)。v1.0.0より前のバージョンのみ
    offlinePushInfo Object メッセージのオフラインプッシュをカスタマイズします(オプション)。v1.0.0およびそれ以降のバージョンのみ

    offlinePushInfoパラメータ(v1.0.0およびそれ以降のバージョンのみ)

    パラメータ タイプ 意味
    title String オフラインプッシュタイトル(オプション)
    description String オフラインプッシュコンテンツ(オプション)
    androidOPPOChannelID String オフラインプッシュのためのOPPO携帯(システム8.0以上)のチャンネルIDを設定します(オプション)。

    groupCall({userIDList, type, groupID, offlinePushInfo})

    groupID パラメータは IM SDKにおけるグループ IDです。このパラメータを設定すると、通話リクエストメッセージがグループメッセージシステムを介してブロードキャストされます。このメッセージブロードキャスト方式は簡単で信頼性の高い方法です。設定しない場合は、TRTCCalling コンポーネントが単発メッセージで1人1人に通知を行います。

    説明:

    v1.0.0およびそれ以降のバージョンに、offlinePushInfoパラメータを新たに追加しました(オフラインプッシュはAndroidまたはiOS端末にのみ適用されます。WebおよびWeChat Mini Programはサポートしていません)。

    // v1.0.0より前
    trtcCalling.groupCall({userIDList, type, groupID});

    // v1.0.0およびそれ以降
    const offlinePushInfo = {
    title: '',
    description: '通話リクエストが1件あります',
    }
    trtcCalling.groupCall({userIDList, type, groupID, offlinePushInfo})

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    userIDList Array 招待リスト
    type Number 1:音声通話、2:ビデオ通話
    groupID String IMグループID(オプション)
    offlinePushInfo Object メッセージのオフラインプッシュをカスタマイズします(オプション)。v1.0.0およびそれ以降のバージョンのみ

    offlinePushInfoパラメータ(v1.0.0およびそれ以降のバージョンのみ)

    パラメータ タイプ 意味
    title String オフラインプッシュタイトル(オプション)
    description String オフラインプッシュコンテンツ(オプション)
    androidOPPOChannelID String オフラインプッシュのためのOPPO携帯(システム8.0以上)のチャンネルIDを設定します(オプション)。

    accept()

    招待を受け取った後、このインターフェースを呼び出すと、現在の招待を受け入れます。

    説明:

    • 前回のinvitationの処理が未完了の場合、コンポーネントはデフォルトでビジー状態になり、その後のすべての招待はビジーを返します。
    • v1.0.0およびそれ以降のバージョンで、paramsパラメータを取り消しました。
    import TRTCCalling from 'trtc-calling-js';
    trtcCalling.on(TRTCCalling.EVENT.INVITED, ({inviteID, sponsor, inviteData}) => {
    // ...
    // v1.0.0より前
    trtcCalling.accept({inviteID, roomID, callType})
    // v1.0.0およびそれ以降
    trtcCalling.accept();
    })

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    inviteID String 招待ID。1回の招待を表示します。v1.0.0より前のバージョンのみ
    roomID Number 通話ルームナンバーID。v1.0.0より前のバージョンのみ
    callType Number 1:音声通話、2:ビデオ通話。v1.0.0より前のバージョンのみ

    reject()

    招待を受け取った後、このインターフェースを呼び出すと、現在の招待が拒否されます。

    説明:

    v1.0.0およびそれ以降のバージョンで、paramsパラメータを取り消しました。

    import TRTCCalling from 'trtc-calling-js';
    trtcCalling.on(TRTCCalling.EVENT.INVITED, ({inviteID, sponsor, inviteData}) => {
    // ...
    // v1.0.0より前
    trtcCalling.reject({inviteID, isBusy, callType})
    // v1.0.0およびそれ以降
    trtcCalling.reject();
    })

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    inviteID String 招待ID。1回の招待を表示します。v1.0.0より前のバージョンのみ
    isBusy Boolean 回線ビジー状態の有無。v1.0.0より前のバージョンのみ
    callType Number 1:音声通話、2:ビデオ通話。v1.0.0より前のバージョンのみ

    hangup()

    1. 通話中にこの関数を呼び出せば、通話を終了することができます。
    2. ダイヤルしていない状態では、通話をキャンセルするために用いることができます。
    trtcCalling.hangup()

    ビデオ制御に関連するインターフェース関数

    startRemoteView({userID, videoViewDomID})

    リモートユーザーのカメラデータを指定されたDOM IDノードにレンダリングします。

    trtcCalling.startRemoteView({userID, videoViewDomID})

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    userID String ユーザーID
    videoViewDomID String konoユーザーデータは、このDOM IDノードにレンダリングされたvideoタグを介して再生されます

    stopRemoteView({userID})

    リモートユーザーのカメラデータによってレンダリングされたDOMノードを削除します。

    説明:

    v1.0.0およびそれ以降のバージョンで、videoViewDomIDパラメータを削除しました。

    // v1.0.0より前
    trtcCalling.stopRemoteView({userID, videoViewDomID});
    // v1.0.0およびそれ以降
    trtcCalling.stopRemoteView({userID});

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    userID String ユーザーID
    videoViewDomID String 該当するDOM IDノードのvideoタグを削除し、ビデオ再生を停止します。v1.0.0より前のバージョンのみ

    startLocalView({userID, videoViewDomID})

    ローカルユーザーのカメラデータを指定されたDOM IDノードにレンダリングします。

    trtcCalling.startLocalView({userID, videoViewDomID})

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    userID String ユーザーID
    videoViewDomID String ローカルユーザーデータは、このDOM IDノードにレンダリングされたvideoタグを介して再生されます

    stopLocalView({userID})

    ローカルユーザーのカメラデータによってレンダリングされたDOMノードを削除します。

    説明:

    v1.0.0およびそれ以降のバージョンで、videoViewDomIDパラメータを削除しました。

    // v1.0.0より前
    trtcCalling.stopLocalView({userID, videoViewDomID});
    // v1.0.0およびそれ以降
    trtcCalling.stopLocalView({userID});

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    userID String ユーザーID
    videoViewDomID String 該当するDOM IDノードのvideoタグを削除し、ビデオ再生を停止します。v1.0.0より前のバージョンのみ

    openCamera()

    ローカルカメラをオンにします。

    trtcCalling.openCamera()

    closeCamera()

    カメラをオフにします。

    trtcCalling.closeCamera()

    setMicMute(isMute)

    マイクをオン/オフします。

    trtcCalling.setMicMute(true) // マイクオフ

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    isMute Boolean
  • true: マイクのオフ
  • false: マイクのオン
  • setVideoQuality(profile)

    ビデオの画質を設定します。

    説明:

    • v0.8.0およびそれ以降のバージョンは、このメソッドが新規追加されました。
    • このメソッドは、call、groupCall、acceptの前に設定する必要があり、その後の設定は有効になりません。
    trtcCalling.setVideoQuality('720p') // ビデオの画質を720pに設定します

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    profile String
  • 480p:640 × 480
  • 720p:1280 × 720
  • 1080p:1920 × 1080
  • switchToAudioCall()

    ビデオ通話を音声通話へ切り替えます。

    説明:

    • v0.10.0およびそれ以降のバージョンは、このメソッドが新規追加されました。
    • 1v1通話中のみ使用をサポートします。
    • ERRORイベントの監視に失敗しました。code:60001。
    trtcCalling.switchToVideoCall() // ビデオ通話を音声通話へ切り替え

    switchToVideoCall()

    音声通話をビデオ通話へ切り替えます。

    説明:

    • v0.10.0およびそれ以降のバージョンは、このメソッドが新規追加されました。
    • 1v1通話中のみ使用をサポートします。
    • ERRORイベントの監視に失敗しました。code:60002。
    trtcCalling.switchToVideoCall() // 音声通話をビデオ通話へ切り替え

    getCameras()

    このインターフェースを呼び出すと、カメラデバイスリストを取得することができます。

    説明:

    v1.0.0およびそれ以降のバージョンに、このメソッドを新たに追加しました。

    trtcCalling.getCameras() // カメラリストの取得

    getMicrophones()

    このインターフェースを呼び出すと、マイクデバイスリストを取得することができます。

    説明:

    v1.0.0およびそれ以降のバージョンに、このメソッドを新たに追加しました。

    trtcCalling.getMicrophones() // マイクリストの取得

    switchDevice({deviceType,deviceID})

    このインターフェースを呼び出すと、カメラまたはマイクのデバイスを切り替えることができます。

    説明:

    v1.0.0およびそれ以降のバージョンに、このメソッドを新たに追加しました。

    trtcCalling.switchDevice(deviceType, deviceID) // デバイスの切り替え

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    deviceType String video: カメラ、 audio: マイク
    deviceID String
  • カメラデバイスIDはgetCameras()で取得します。
  • マイクデバイスIDはgetMicrophones()で取得します。
  • TRTCCallingイベントリスト

    次のコードを参照して、TRTCCalling コンポーネントイベントを監視できます。

    import TRTCCalling from 'trtc-calling-js';
    // etc
    function handleInviteeReject({userID}) {

    }
    trtcCalling.on(TRTCCalling.EVENT.REJECT, handleInviteeReject)

    招待側イベント

    CODE イベント受信側 説明
    REJECT 招待側 被招待ユーザーは通話拒否
    NO_RESP 招待側 被招待ユーザーの応答がなくタイムアウト
    LINE_BUSY 招待側 被招待ユーザーは通話中、ビジー状態
    INVITED 被招待側 招待通知を受信済み
    CALLING_CANCEL 被招待側 相手側による今回通話のキャンセル
    CALLING_TIMEOUT 被招待側 今回の通話に応答せずにタイムアウト
    USER_ENTER 招待側と被招待側 ユーザー入室
    USER_LEAVE 招待側と被招待側 通話から離脱したユーザーあり
    CALL_END 招待側と被招待側 今回の通話終了
    KICKED_OUT 招待側と被招待側 ログイン重複により、ルームから強制退出
    USER_VIDEO_AVAILABLE 招待側と被招待側 リモートユーザーによるカメラのオン/オフ
    USER_AUDIO_AVAILABLE 招待側と被招待側 リモートユーザーによるマイクのオン/オフ

    一般的なイベントコールバック

    SDK_READY

    SDKがready状態に入るとこのコールバックを受信します

    説明:

    v1.0.0およびそれ以降のバージョンに、このイベントを新たに追加しました。

    let onSDKReady = function(event) {
    console.log(event)
    };
    trtcCalling.on(TRTCCalling.EVENT.SDK_READY, onSDKReady);

    USER_ENTER

    ユーザーが入室しました。
    トリガー条件:ユーザーが通話に参加する。

    let handleUserEnter = function({userID}) {
    console.log(userID)
    };
    trtcCalling.on(TRTCCalling.EVENT.USER_ENTER, handleUserEnter);

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    userID String ユーザーID

    USER_LEAVE

    ユーザーが退室しました。
    トリガー条件:ユーザーが通話を退出する。

    let handleUserLeave = function({userID}) {
    console.log(userID)
    };
    trtcCalling.on(TRTCCalling.EVENT.USER_LEAVE, handleUserLeave);

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    userID String ユーザーID

    GROUP_CALL_INVITEE_LIST_UPDATE

    グループチャットで招待リストを更新するとこのコールバックを受信します

    説明:

    v1.0.0およびそれ以降のバージョンに、このイベントを新たに追加しました。

    let handleGroupInviteeListUpdate = function(event) {
    console.log(event)
    };
    trtcCalling.on(TRTCCalling.EVENT.GROUP_CALL_INVITEE_LIST_UPDATE, handleGroupInviteeListUpdate);

    CALL_END

    今回の通話は終了しました。
    トリガー条件:今回の通話を終了する。

    let handleCallingEnd = function(event) {
    console.log(event)
    };
    trtcCalling.on(TRTCCalling.EVENT.CALL_END, handleCallingEnd);

    KICKED_OUT

    ログインを繰り返したことにより、ルームから強制退室させられました。
    トリガー条件:他のページに重複ログインする。

    let handleKickedOut = function(event) {
    console.log(event)
    };
    trtcCalling.on(TRTCCalling.EVENT.KICKED_OUT, handleKickedOut);

    USER_VIDEO_AVAILABLE

    リモートユーザーがカメラをオン/オフにします。
    トリガー条件:リモートユーザーがカメラをオン/オフにする。

    let handleUserVideoChange = function({userID, isVideoAvailable}) {
    console.log(userID, isVideoAvailable)
    };
    trtcCalling.on(TRTCCalling.EVENT.USER_VIDEO_AVAILABLE, handleUserVideoChange);

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    userID String ユーザーID
    isVideoAvailable Boolean
  • true:リモートユーザーによるカメラオン
  • false:リモートユーザーによるカメラオフ
  • USER_AUDIO_AVAILABLE

    リモートユーザーがマイクをオン/オフにしました。
    トリガー条件:リモートユーザーがマイクをオン/オフする。

    let handleUserAudioChange = function({userID, isAudioAvailable}) {
    console.log(userID, isAudioAvailable)
    };
    trtcCalling.on(TRTCCalling.EVENT.USER_AUDIO_AVAILABLE, handleUserAudioChange);

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    userID String ユーザーID
    isAudioAvailable Boolean
  • true:リモートユーザーによるマイクオン
  • false:リモートユーザーによるマイクオフ
  • 招待側イベントコールバック

    REJECT

    ユーザーが通話を拒否しました。
    トリガー条件:被招待者が通話を拒否し、発信者がREJECTイベントコールバックを受け取る。

    let handleInviteeReject = function({userID}) {
    console.log(userID)
    };
    trtcCalling.on(TRTCCalling.EVENT.REJECT, handleInviteeReject);

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    userID String ユーザーID

    NO_RESP

    招待されたユーザーは応答しませんでした。
    トリガー条件:call/groupCallにtimeoutを設定し、被招待者がtimeout内に出なかった場合、発信者がNO_RESPイベントコールバックを受け取る。

    let handleNoResponse = function({userID, userIDList}) {
    console.log(userID, userIDList)
    };
    trtcCalling.on(TRTCCalling.EVENT.NO_RESP, handleNoResponse);

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    userID String ユーザーID
    userIDList Array タイムアウトユーザーリスト

    LINE_BUSY

    被招待側は通話中で、ビジー状態です。
    トリガー条件:被招待者が通話中である場合、発信者がLINE_BUSYイベントコールバックを受け取る。

    let handleLineBusy = function({userID}) {
    console.log(userID)
    };
    trtcCalling.on(TRTCCalling.EVENT.LINE_BUSY, handleLineBusy);

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    userID String ユーザーID

    被招待側イベントコールバック

    INVITED

    招待通知を受領しました。
    トリガー条件:招待通知があった場合、被招待者がINVITEDイベントコールバックを受け取る。

    let handleNewInvitationReceived = function({
    sponsor, userIDList, isFromGroup, inviteData, inviteID
    }
    )
    {
    console.log(sponsor, userIDList, isFromGroup, inviteData, inviteID)
    };
    trtcCalling.on(TRTCCalling.EVENT.INVITED, handleNewInvitationReceived);

    パラメータは下表に示すとおりです。

    パラメータ タイプ 意味
    sponsor String 招待者
    userIDList Array 同時に招待された人
    isFromGroup Boolean IMグループの招待の有無
    inviteData Object
  • 新しいユーザーへの招待: {version, callType, roomID}
  • 最後のユーザーとの通話終了:{version, callType, callEnd}
  • inviteID String 招待ID。1回の招待を表示

    CALLING_CANCEL

    今回の通話はキャンセルされました。
    トリガー条件:発信者がコール中に通話をキャンセルし、被招待者がCALLING_CANCELイベントコールバックを受け取る。

    let handleCallingCancel = function(event) {
    console.log(event)
    };
    trtcCalling.on(TRTCCalling.EVENT.CALLING_CANCEL, handleCallingCancel);

    CALLING_TIMEOUT

    今回の通話はタイムアウトで、応答はありませんでした。
    トリガー条件:call/groupCallにtimeoutを設定し、被招待者がtimeout内に出なかった場合、被招待者がCALLING_TIMEOUTイベントコールバックを受け取る

    let handleCallingTimeout = function(event) {
    console.log(event)
    };
    trtcCalling.on(TRTCCalling.EVENT.CALLING_TIMEOUT, handleCallingTimeout);

    TRTCCalling エラーコードリスト

    EVENTのERRORフィールドを監視することによって、コンポーネントからスローされたエラーを処理することができます。サンプルコードは次のとおりです。

    import TRTCCalling from 'trtc-calling-js';
    let onError = function(error) {
    console.log(error)
    };
    trtcCalling.on(TRTCCalling.EVENT.ERROR, onError);

    Error code

    code エラータイプ 意味
    60001 メソッドのコールに失敗しました switchToAudioCallのコールに失敗しました
    60002 メソッドのコールに失敗しました switchToAudioCallのコールに失敗しました
    60003 権限の取得に失敗しました 使用可能なマイクデバイスがありません
    60004 権限の取得に失敗しました 使用可能なカメラデバイスがありません
    60005 権限の取得に失敗しました ユーザーがデバイスの使用を禁止しています

    よくあるご質問

    通話がつながらなかったり、強制オフラインになったりするのはなぜですか?

    コンポーネントは現在、マルチインスタンスのログインやオフラインプッシュのシグナリング機能をサポートしていません。現在のログインアカウントの一意性をご確認ください。

    説明:

    • マルチインスタンス:1つのUserIDで繰り返しログインしたり、異なるターミナルからログインしたりすると、シグナリングの混乱が生じます。
    • オフラインプッシュ:インスタンスはオンラインの場合にのみメッセージを受信できます。インスタンスがオフラインのときに受信したシグナリングは、オンラインになった後は再度プッシュされません。