1. 概要とポイント
任意のWebサイト、Webページ、WebサービスなどのWebブラウザでアクセスする
Webアプリにビデオ通話・会議、音声通話・会議などを組み込む方法を概説します。
プラットフォームとしてはWebex(無償版でも動作します)を利用します。
- HTMLとJavascriptのみで実装、組み込みができる。
- ブラウザのwebrtcの機能を使うので特殊なプラグインなどは不要。
- デスクトップのブラウザはChrome, Safari, Firefox, Edgeをサポート(最新版推奨)。
- モバイルのブラウザはChrome for Android, Safari for iOSをサポート(最新版推奨)。
- ユーザ側はWebexの無償版でもよい(クレジットカード情報などの登録も不要)。
- Guest IssuerというWebexのアカウントを持っていない人にゲストアカウントを発行する機能もある。
Web系の開発者であれば、誰でも出来るものになっていると思います。
Guest IssuerはWebexのアカウントを持っていないゲスト的なユーザが、
有償版のWebexユーザとの間でビデオ会議やチャットなどを行う際に
ゲスト用のアカウントをアプリケーションが動的に発行する仕組みです。
#2. Browser SDK(ブラウザ向けのSDK)
Webブラウザで動くWebサービスに、
Webexのビデオ通話・会議などを組み込むためのSDKが提供されています。
このSDKを利用するための契約や申請などは必要ありません。
誰でも自由に利用することができます。
Browser SDKでビデオ会議を組み込んだ場合も、
利用するプラットフォームはWebexなので、
Webexのアプリや、Webexの専用端末を利用しているユーザを含めて、
ビデオ通話・会議が可能です。
基本的にはWebexのクラウドサービスそのものを利用します。
以下が公式の開発者ガイドになりますが、ポイントだけは本記事で説明します。
開発者ガイドは英語ですが、Webブラウザの翻訳機能で、ほぼ問題ない日本語で読めます。
#3. 必要な準備
開発や実験を行うためにWebexのアカウントが必要ですが、無償版でも構いません。
ビデオ通話・会議を実験するには、普通はアカウント２つ以上あった方がいいです。
１つでもいろいろ実験できますが、２つ以上使った方が最初の実験は簡単です。
最初の実験では、端末も２台あった方がいいと思います。
例えば、手元のPC・Macと、スマホなどでもよいです。
Webexのアカウントなどをお持ちでない場合は、以下からメールアドレスを入力して、
無償版のアカウントが作成できます。
クレジットカード情報の入力などが求められることはありません。
#4. まずはサンプルで実験しよう
一番単純な、Single Party Callというサンプルをまず実験するのがお勧めです。
１対１のビデオ・音声通話を行うシンプルなサンプルです。
Browser SDKとあまり関係のない部分は極力排除されたサンプルなので、
UIはまったくデザイン考慮されていません。
Browser SDKとして、１対１なのか、複数人の会議なのかの区別はほぼないので、
Single Partyと言っておきながら、このサンプルで複数人の会議に参加することもできます。
ただし、参加者全員の名前情報などを表示する機能はこのサンプルには含まれていません。
4.1. 実験ステップその1
サンプルアプリを端末２台でそれぞれ開きます。
例えば、手元のPC・Macと、スマホなどでもよいです。
4.2. 実験ステップその2
[Authentication with OAuth]内の[Login]ボタンを押して、
端末２台でそれぞれ別々のWebexアカウントでログインします。
ユーザにWebexの機能へのアクセスを許可するかの画面が表示されますが、
[許可]しないとBrowser SDKの機能は利用できません。
ログインと言っていますが、内部的には、
OAuth 2.0の認証・認可のフローを実行して、
Browser SDKで利用するためのアクセストークンを取得しています。
4.3 実験ステップその3
端末２台それぞれで、[Register]ボタンを押します。
サンプルとしては開発者向けの説明の目的もあるので、
わざわざこのプロセスを手動で行わせています。
4.4 実験ステップその4
端末２台のうち、どちらかの端末で、
[Dialer]のところに、自分の端末ではないWebexアカウントを入力します。
(２台のうちのもう１台のアカウントのものを指定)
これはビデオ通話の宛先になります。
この宛先のアドレスを、誰かのWebexアカウントにすると、その人を宛先としてビデオ通話が発信されます。
宛先を複数人が参加するビデオ会議のアドレスにすると、ビデオ会議に参加します。
[dial]を押すと通話・会議が開始されますが、
初回はブラウザのプライバシー関連の機能により、
ビデオやマイクの利用を許可するかの確認画面が表示されるはずです。
これを許可しなかった場合は、音声や映像が送られないことになります。
4.5 実験ステップその5
もう１台の端末のブラウザ上に着信した趣旨のアラートが出るはずです。
[Answer]して、ビデオやマイクの利用も許可すると、
端末２台の間でビデオ通話ができるはずです。
5. 初期段階で参考にできそうなサンプルコード
実験で利用したサンプルを理解できれば、Browser SDKの９割くらいは攻略できていると思います。
サンプルには載っていない機能もたくさんありますが、
サンプルが理解できれば、あとはSDKのリファレンスで理解できるはずです。
サンプルのコードはGitHubで公開されています。
ReactやVue.jsなどのフレームワークは利用しておらず、
シンプルなhtmlとJavascriptのみで書かれています。
サンプルを参考にReactやVue.jsのアプリに組み込むことは可能です。
5.1. ビデオ通話・会議の機能で参考になるサンプルコード抜粋
ビデオ通話・会議の機能で初期に参考になるサンプルコードは以下あたりかと思います。
各サンプルのindex.htmlとapp.jsがポイントとなりますが、
大部分のポイントはapp.jsにあります。
各サンプルは、ご自身の開発環境やローカル環境などで動かして試すことができます。
5.1.1. １対１通話を意識したサンプル
１対１のビデオ通話のサンプルです。
通話相手の名前情報など１人分しか表示されませんが、複数人の会議に参加はできます。
5.1.2. 複数人参加のビデオ会議を意識したサンプル
１対１のビデオ通話のサンプルに、
会議参加者の名前など複数人の情報を表示する機能が付いたサンプルです。
１対１のビデオ通話のサンプルとの違いは、参加者の情報を処理するかどうか程度の違いで、
その他の部分に大きな違いはありません。
会議の参加と、１対１での通話の開始方法などは処理方法に違いはありません。
5.1.3. 画面共有機能を意識したサンプル
ビデオ会議中に画面共有をする機能が付いたサンプルです。
画面共有の開始は現在、デスクトップ版のブラウザでのみサポートされます。
モバイル版でも、共有された画面の閲覧は可能です。
5.1.4. いろんな機能が付いたサンプル
他のサンプルと比べていろいろ盛り込んだサンプルです。
利用するカメラやマイクの選択機能など参考にしたい場合はこちらのサンプルを利用します。
名前に"Plugin"とついていますが、はるか昔の名残で、
現在は特殊なプラグインは必要ありません。
6. Browser SDKを使った実装時のポイント
6.1. Browser SDKのライブラリの利用
各サンプルのindex.htmlに以下のような部分があるはずです。
ここでBrowser SDKのライブラリを読み込んでいます。
<script crossorigin src="https://unpkg.com/webex@^1/umd/webex.min.js"></script>
素のhtmlを利用する場合は、
上記のような感じでCDNサービス上にあるJavascriptのライブラリを読みこめば、
Browser SDKが提供する機能にアクセスできるようになります。
ReactやVue.jsなどのフレームワークは利用時には、
node.jsのパッケージマネージャに登録されているWebex Browser SDKを
npmやyarnなどで、インストールして利用すればOKです。
npmの場合は以下のようになります。
npm install --save webex
6.2. 基本的な流れ
以下の開発ガイドの[Getting Started]に[Step]として書かれています。
下準備とか抜きにすると、主要な処理は、[Step 4]からになります(本記事の執筆時点での記述)。
本稿では抜粋して特にポイントとなる部分のみ補足的に記載します。
基本的な流れとしては、以下くらいの流れです。
- 初期化(init)
- Webexサービスへビデオ機器として登録処理(register)
- ビデオ通話・会議用のmeetingインスタンスの作成(create)
- ビデオ通話・会議への参加処理(join)
- 各種イベントの受信・処理
- Webexサービスへビデオ機器としての登録解除(unregister)
(3)のmeetingインスタンスの作成は、着信する場合は、
meetingインスタンスは(5)の各種イベントから取得することもできます。
(6)の登録解除処理も重要で、可能な限りアプリ終了時などには、
登録解除を実行するようにします。
１ユーザ当たり登録可能なビデオ機器が１００台までの制限があるため、
登録解除を明示的にしない場合は、制限超えで登録できなくなります。
なお、セッションが無効になってから１週間後に登録は自動で解除されます。
6.2.1. 初期化処理
初期化処理はシンプルに書くと以下のような感じですが、
もうちょっと細かい設定もできます(詳細は開発ガイド、APIリファレンスなど)。
const webex = window.Webex.init({
meetings: {
reconnection: {
enabled: true
}
},
credentials: {
access_token: `YOUR_ACCESS_TOKEN`
}
});
6.2.1.1. アクセストークンの一般的な取得方法
YOUR_ACCESS_TOKEN部分は、Browser SDKを使ったWebアプリを利用するユーザのアクセストークンです。
一般的には、OAuth 2.0のフローを回してアクセストークンを取得して利用します。
Browser SDKにもOAuth 2.0の支援機能が付いていますが、
ほとんどのアプリではアクセストークンやリフレッシュトークンはサーバー側で管理したいはずなので、
支援機能は利用せずに、サーバー側のアプリでOAuth 2.0関連の処理をすることになると思います。
OAuth 2.0に関して詳細説明すると、それだけで１つの記事になるので、本記事では触れませんが、
Webex API/SDKのOAuth 2.0に関しては以下を参照ください。
無償版を利用している開発者も、OAuth 2.0のためのIntegrationを作成登録できます([Create an Integration])。
なお登録する場合は、Browser SDKを利用するためにはspark:allのスコープが必要です。
管理系の機能は動きませんが、このスコープは、そのユーザのいろんな情報にアクセスできることになるので、
取り扱いには充分注意ください。
6.2.1.2. 開発初期段階での開発用の一時トークンの取得方法
開発時には一時的に利用できる開発者向けのトークンも利用できます。
以下のページの[Your Personal Access Token]から取得できます(取得から12時間のみ有効)。
このアクセストークンは運用には利用できません。
※ このアクセストークンは第三者に流出させないようにしてください。
トークン取得者のフル権限が付いたトークンなので、漏れた場合は、
取得者に成り代わって、APIでいろんなことができてしまうので慎重に取り扱う必要があります。
6.2.1.3. ゲスト用のトークンに関して
Guest Issuerという機能を使ってアプリケーションが動的にゲスト用のアクセストークンを発行できます。
JWT(Json Web Token)ベースのインタフェースを使って
ゲスト用のアクセストークンを発行できます。
利用規約上は、Guest Issuerで発行したゲストユーザのみでビデオ通話や会議を行うことはできません。
有償のWebexユーザ(*確認中)が含まれたビデオ通話や会議を行う必要があります。
有償版のWebexが必要か、無償版のWebexユーザでもよいのかは確認後に情報アップデート予定です。
昔は明確に有償版ユーザとゲスト間専用の位置付けでしたが、
開発ガイドの記載がpaid userからregular userに変わっているので確認してみます。
6.2.2. registerとunregister
開発ガイドにはregister()処理しか記載されていませんが、
Browser SDKが提供する機能の利用が終わった際などに、
サンプルには載っているunregister()はできる限り呼び出すようにします。
イメージとしてはログインとログアウトのようなイメージです。
ただし、ログインセッションの数に制限があって、ログアウトしていないと、
セッション数の上限を超えるとログインできなくなります。
セッションは１週間有効で、ユーザ当たり１００個までに制限されています。
Browser SDKを利用したアプリのみのセッション数だけではなく、
WebexアプリやWebexデバイスなどもセッション数も合算されます。
webex.meetings.unregister()
6.2.3. イベントの処理
開発ガイドやサンプルでは、以下のようにmeeting.onで通知を受けるイベントの登録や、
イベントが通知された際の処理を実装しています。
meeting.on('media:ready', (media) => {
if (!media) {
return;
}
if (media.type === 'local') {
document.getElementById('self-view').srcObject = media.stream;
}
if (media.type === 'remoteVideo') {
document.getElementById('remote-view-video').srcObject = media.stream;
}
if (media.type === 'remoteAudio') {
document.getElementById('remote-view-audio').srcObject = media.stream;
}
}
6.2.3.1 media.streamオブジェクト
media.streamオブジェクトが自分や相手の映像や音声に関するオブジェクトです。
サンプルでは、document.getElementByIdを使ってindex.html内の、
<video>、<audio>タグのsrcObjectとして設定しています。
ReactやVue.jsを利用している場合は、document.getElementByIdなどでDOMに直接アクセスはできないので、
refやrefsなどを利用してアクセスする必要があります。
(フレームワークによって呼び方や仕組みなどは異なります。)
Reactの場合は例えば以下のような感じです。
Vue.js 3.xでは方法が結構違いますが、refsなどで調べていただければと思います。
<video ref={(video) => {this.video = video}} width="640" height="360" autoPlay />
<audio ref={(audio) => {this.audio = audio}} autoPlay />
if (media.type === 'remoteVideo') {
this.video.srcObject = media.stream
}
if (media.type === 'remoteAudio') {
this.audio.srcObject = media.stream
}
6.2.4. 参加先の会議の指定
以下のコードでいうとdestination変数(文字列)で指定しています。
ここがWebexユーザのメールアドレス形式のidであれば、そのユーザとの1対１のビデオ通話になります。
会議室のSIPアドレス(会議番号@example.comのような形式)であれば、
複数人参加のビデオ会議になります。
SIPアドレス以外でもよいのですが、SIPアドレスが一番扱いやすいと思います。
webex.meetings.create(destination)
6.2.5. 会議用のSIPアドレスの取得方法
Webexで手動で予約した場合は、メールなどにSIPアドレスが書かれています。
Webex MeetingsのREST APIで会議予約したり、情報を取得したりすることもできます。
REST APIのレスポンスにSIPアドレス情報が含まれます。
グループチャットスペース(チャネル)で予約なしで、
そのスペースに含まれるメンバー同士でビデオ会議を行うこともできます。
無償版の場合は本記事投稿時点で２５名までのビデオ会議が可能なはずです。
こちらの場合もREST APIでSIPアドレス情報が取得できます。
また、スペース自体の作成やメンバーの管理などもAPI経由で可能です。
SIPアドレス情報を取得する場合は、[Get Room Meeting Details] APIを利用します。
7. まとめ
htmlとjavascriptの知識があれば、
無償版のWebexユーザ向けにも任意のWebサイトにビデオ会議の機能を組み込みこむことができます。
有償版のWebexを利用している場合は、外部のゲストユーザ向けにGuest Issuerを利用して、
Webから簡単にビデオ通話や会議に参加できる仕組みを作ることもできます。
記事ではだらだらと書きましたが、実際には、それほど難易度は高くないと思います。
Webサービスの１機能としてビデオ会議の仕組みも組み込んでみてはいかがでしょうか？