Insights イベント・リファレンス
Voice Insightsでは、Twilio Clientの通話のライフサイクルにおける重要なイベントについて確認できます。
多くのイベントが twilio.js ライブラリー (v1.4以上) のイベントとしても発生し、これらをネットワークの変更やデバイスの状態についてエンドユーザーにアラートする用途に使用できます。
イベント・リファレンスでは通話のライフサイクルについて把握できるようにするための各イベントについて触れています。
警告イベント
下記のイベントはVoice Insightsシステムに記録され、twilio.js ライブラリー内で warning イベントとして発生します。
ネットワークの警告
下記のイベントはtwilio.jsがネットワーク状態の悪化を検出した際に発生します。 これらのイベントは network-quality-warning-raised グループに属します。
#warning イベントをリスニングすることで、これらのイベントに対するハンドラーを実装でき、エンドユーザーが問題に気づけるように視覚的なインジケーターを表示できます。
| EventName | イベントレベル | 発生条件 | 概要 |
|---|---|---|---|
high-rtt |
Warning | 最新の5サンプル中3サンプルについて、ラウンド・トリップ・タイム（RTT = Round Trip Time）が400ミリ秒を上回った場合 | ラウンド・トリップ・タイム（RTT = Round Trip Time）はネットワーク中のレイテンシー（遅延）の目安です。 高レイテンシーは耳で聴こえるくらいの遅延となって現れます。 |
low-mos |
Warning | 最新の5サンプル中3サンプルについて、平均オピニオン評点 (MOS = Mean Opinion Score) が3.5を下回った場合 | 平均オピニオン評点 (MOS = Mean Opinion Score) は通話品質に影響する全般的なネットワーク状態の目安です。 |
high-jitter |
Warning | 最新の5サンプル中3サンプルについて、ジッターが30ミリ病を上回った場合 | ジッターはエンドポイントに到達するパケットにおける揺らぎの目安です。 高ジッターは雑音や途切れなどといった通話におけるオーディオ品質の問題となって現れます。 |
high-packet-loss |
Warning | 最新の5サンプル中3サンプルについて、1%を上回るパケットロスが発生した場合 | パケットロスは、送信されたもののエンドポイント側で受信されなかったパケットのパーセンテージとして表されます。 高パケットロスは、音声の途切れや通話の切断となって現れます。 |
twilio.jsがネットワーク状態の復旧を検出したら、これらの警告は解除されます。 warning-cleare イベントは network-quality-warning-cleared グループに属します。
| EventName | イベントレベル | 発生条件 |
|---|---|---|
high-rtt |
info | 最新の5サンプル中3サンプルについて、ラウンド・トリップ・タイム（RTT = Round Trip Time）が400ミリ秒を下回った場合 |
low-mos |
info | 最新の5サンプル中3サンプルについて、平均オピニオン評点 (MOS = Mean Opinion Score) が3.5を上回った場合 |
high-jitter |
info | 最新の5サンプル中3サンプルについて、ジッターが30ミリ病を下回った場合 |
high-packet-loss |
info | 最新の5サンプル中3サンプルについて、パケットロスが1%を下回った場合 |
音量イベント
以下のイベントは twilio.js がオーディオ入力またはオーディオ出力のレベルが予期せず長時間一定であることを検出した時に発生します。 通話が行われる際、オーディオ入力およびオーディオ出力のレベルは変化するものです。 これらのイベントは問題の示唆に使用できますが、一定のオーディオ入力／出力レベルは一方の話者がハードの消音機能を使ってマイクをミュートしている場合にも発生する可能性があります。
これらのイベントの発生がかなりの時間続いた場合、ユーザーのマイクが誤ってミュートされていないか確認を促す用途に、この機能は役に立つかもしれません。
#warning イベントをリスニングすることで、これらのイベントに対するハンドラーを実装でき、エンドユーザーが問題に気づけるように視覚的なインジケーターを表示できます。
下記の警告イベントは audio-level-warning-raised グループに属します。 これらはイベント・エミッターを通じて、SDKによってもエミットされます。
| EventName | イベントレベル | 発生条件 |
|---|---|---|
| constant-audio-input-level | Warning | オーディオ入力レベルが20秒間変化しなかった場合 |
| constant-audio-output-level | Warning | オーディオ出力レベルが20秒間変化しなかった場合 |
これらの警告レベルのイベントは音量変化によって解除されます。 これらは audio-level-warning-cleared グループに属します。
| EventName | イベントレベル | 発生条件 |
|---|---|---|
| constant-audio-input-level | info | 警告の発生後、オーディオ入力レベルが再び変化し始めた場合に発生します |
| constant-audio-output-level | info | 警告の発生後、オーディオ出力レベルが再び変化し始めた場合に発生します |
その他のイベント
以下のイベントはVoice Insightsシステムに記録されますが、twilio.jsライブラリー内の warning イベントとしては発生しません。
ICE-Connection-State イベント
下記のイベントはice-connection-state グループに属します。 これらは下記で説明されている標準の RTCPeerConnection.iceConnection 状態となります。ICEイベントについてのさらなる詳細については、こちらをご参照ください。
| EventName | イベントレベル | 概要 |
|---|---|---|
checking |
debug | ICEエージェントに1つ以上のリモート候補が与えられ、互換性の一致を見つけようとローカルおよびリモート候補の組を相互に確認していますが、まだ組が見つかっていません。 候補の収集が依然として進行中である可能性があります。 |
connected |
debug | ローカルおよびリモートの候補に使用できるペアリングが接続のすべてのコンポーネントにおいて見つかり、接続が確立されました。 収集は依然として進行中の可能性があり、またICEエージェントは依然として使用できるより良い他の接続の候補を探している可能性があります。 |
closed |
debug | このRTCPeerConnection用のICEエージェントはシャットダウンし、もうリクエストを処理することができません。 |
completed |
debug | ICEエージェントは候補の収集を終え、すべての組み合わせについてチェックを行い、すべてのコンポーネントにおいて接続が見つかりました。 |
disconnected |
debug | RTCPeerConnectionの最低1つのコンポーネントについて、まだ接続が成功していないことを示します。 これは failed よりもより緩いテストで、信頼性の低いネットワーク、あるいは一時的なネットワークの切断時のそれのように断続的にトリガーされ、また自然に復帰することがあります。 問題が解決すると、接続は connected 状態に戻ることがあります。 |
failed |
ERROR | ICE候補がすべての候補の組み合わせで確認され、接続のすべてのコンポーネントにおいて互換性のある一致の検索に失敗しました。 これはしかし、ICEエージェントがいくつかのコンポーネントについては互換性のある接続を見つけた可能性があります。 |
シグナリング状態イベント
下記のイベントは signaling-state グループに属します。 これらは、下記で述べるような標準の RTCPeerConnection.signalingState イベントです。
| EventName | イベントレベル | 概要 |
|---|---|---|
stable |
debug | 進行中のオファーの交換がなく、応答は進行中です。 RTCPeerConnectionオブジェクトが新しく、localDescriptionおよびremoteDescriptionがnullの可能性があります; これはネゴシエーションが完了し、接続が確立されたことを意味する可能性もあります。 |
closed |
debug | コネクションが閉じられました。 |
have-remote-offer |
debug | リモート・ピアがオファーを作成し、シグナリング・サーバーを使用してRTCPeerConnection.setRemoteDescription()を呼ぶことでリモート・デスクリプションとしてオファーを設定したローカル・ピアに対してそれを送り届けます。 |
have-local-offer |
debug | ローカル・ピアはRTCPeerConnection.setLocalDescription()を呼び、オファー（通常はRTCPeerConnection.createOffer()を呼ぶことで作成されます）を表すSDPを渡すと、そのオファーの適用が成功します。 |
シグナリング・イベントについての詳細は、こちらでご確認ください。
接続イベント
下記のイベントは connection グループに属します。 これらは接続状態を示すキー・イベントのログです。
| EventName | イベントレベル | 概要 |
|---|---|---|
disconnected-by-local |
info | The connection was disconnected by the local participant. |
incoming |
info | Twilioクライアントは着信接続を受信しました。 |
accepted-by-local |
info | クライアントAppによって接続が受理されました。 |
accepted-by-remote |
info | 接続が、電話の着信したリモートの参加者で受理されました。 |
disconnected-by-remote |
info | リモートの参加者が切断しました。 |
ignored-by-local |
info | 着信接続がクライアントによって無視されました。 |
unmuted |
info | 接続がミュート解除されました。 |
muted |
info | 接続がミュートされました。 |
rejected-by-local |
info | 着信接続がローカルの参加者によって拒否されました。 |
error |
ERROR | 接続エラーが発生しました。 低品質なネットワーク接続やセットアップのミスがエラーの原因となった可能性があります。 |
ユーザー・メディア・イベント
下記のイベントは get-user-media グループに属します。 これらのイベントは、twilio.jsがユーザーのオーディオ・マイクにアクセスできたかどうかを示しています。
| EventName | イベントレベル | 概要 |
|---|---|---|
succeeded |
info | Twilioクライアントはユーザーのメディア・デバイスに正常にアクセスできました。 これは、接続を確立するための特権です。 |
failed |
ERROR | Twilioクライアントはユーザーのメディア・デバイスのアクセスに失敗しました。 このイベントは、ユーザーのデバイス上のその他のエラーによってマイクがアクセスできなかった場合に記録されます。 |
denied |
ERROR | ユーザーがマイク／スピーカーへのアクセス許可を拒否し、結果接続を確立できませんでした。 |
フィードバック・イベント
Twilio.jsは postFeedback APIを通じて、ユーザーに個々の通話についての品質評価をしてもらうことができます。 フィードバックが送信されると、Voice Insightsダッシュボードから結果を視覚化、分析できるようになります。
フィードバック・イベントは 右記のグループに属します: feedback
| EventName | イベントレベル | 概要 |
|---|---|---|
| received | info | このイベントはpostFeedbackAPIを使用してTwilioにフィードバックを投稿した際に記録されます。 イベントにはユーザーによってつけられた事象名 (issue-name) および 品質スコア (quality-score) を含みます。 |
| received-none | info | このイベントはパラメーターを伴わずにpostFeedback APIを呼び出した場合に記録されます。 このイベントは、ユーザーにフィードバックを促したもののユーザーによってフィードバックの送信が辞退された場合に使用されます。 |
ヘルプが必要ですか？
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.