OpenTok.js ライブラリのバージョン 1.0 からの移行

について 最新バージョン OpenTok.js ライブラリでは、 ウェブRTC オーディオ・ビデオ通信において、Adobe Flashの代わりに。このガイドでは、ウェブサイトをバージョン1.0からOpenTok.jsライブラリの最新バージョンへ移行する方法について解説します。

最新の OpenTok.js ライブラリは、以下の OpenTok ライブラリを使用してアプリと連携します：

• OpenTok Android 2.3 以降用 SDK
• OpenTok iOS 2.3 以降用 SDK

バージョン 2.0 からコードを移行する場合は、以下を参照してください。 このページ.

• 最新の OpenTok.js ライブラリを読み込み中
• セッション作成のメディアモード
• 最新の OpenTok.js ライブラリへの移行
• 新機能

最新の OpenTok.js ライブラリを読み込み中

を設定する。 src 属性の script OpenTok.js ライブラリの最新バージョンを読み込むには、以下の URL にタグを追加してください：

<script src="https://static.opentok.com/v2/js/opentok.min.js"></script>

セッションの作成とメディアモード

新しい OpenTok.js ライブラリで使用するには、新しいセッションを作成する必要があります。OpenTok 1.0 で以前使用されていたセッションは、OpenTok の最新バージョンでは使用できません。

バージョン1.0では、ストリームはクライアント間で直接（ピアツーピア）送信されるか、OpenTok Media Routerを介して送信されていました。バージョン1.0のセッションを、OpenTokサーバー用SDKのいずれかを使用して作成する際には、 p2p.preference パラメータを "enabled" または "disabled". OpenTokの最新バージョンでは、これが変更されています。

セッションを作成する際、そのセッション内のクライアントがオーディオ・ビデオストリームをどのように送信するかを指定します。これは、 メディアモード. 選択肢は2つあります：

• 中継 — リレーセッションでは、クライアント同士が直接（ピアツーピア）で音声・動画ストリームの送受信を試みます。ただし、ファイアウォールの制限によりクライアント同士が接続できない場合、セッションではOpenTok TURNサーバーを介して音声・動画ストリームを中継します。 （バージョン 2.2 以前、OpenTok サーバー SDK では、これらのセッションをピアツーピア セッションと呼んでいました。ただし、それらの SDK を使用している場合でも、ファイアウォールの制限によりピアツーピア ストリーミングがブロックされる場合は、セッションでは OpenTok TURN サーバーを使用してストリームを中継します。）

• ルーティング — このセッションでは、OpenTok Media Router を使用して、クライアント間で音声・動画ストリームをルーティングします。この OpenTok メディアルーター には次のようなメリットがある：

  • OpenTok Media Router を使用すると、多者間セッションにおける帯域幅の使用量を削減できます。（media mode プロパティが relayed に設定されている場合、各クライアントは、そのストリームを購読している各クライアントに対して、個別の音声・動画ストリームを送信する必要があります。）
  • OpenTok Media Router は、以下の機能を通じてユーザー体験の質を向上させることができます。 オーディオのフォールバックとビデオのリカバリー. この機能により、クライアントの接続状態が、購読しているストリームの動画を再生できないほど悪化した場合、そのクライアントでは動画の配信が停止され（他のクライアントには影響しません）、クライアントには音声のみが配信されます。クライアントの接続状態が改善すると、動画の配信が再開されます。
  • OpenTok Media Router は、以下の機能をサポートしています。 OpenTok 2.0 のアーカイブ機能、これにより、OpenTokのセッションを録画、保存、および再生することができます。

注： OpenTokサーバーSDKの新バージョンでは、デフォルトのメディアモードは「relayed」となっています。（以前のバージョンでは、デフォルトでOpenTok Media Routerが使用されていました。）

<script src="https://static.opentok.com/v2/js/opentok.min.js"></script>

OpenTok.js ライブラリの最新バージョンへの移行

重要だ： 最新の OpenTok.js ライブラリには、OpenTok.js 1.0 と互換性のない変更が含まれています。このセクションでは、既存のコードを最新の OpenTok.js ライブラリで動作するように修正する方法について説明します。

廃止されたAPI

バージョン 1.0 に含まれていた以下のクラス、プロパティ、メソッド、およびイベントは、OpenTok.js の最新バージョンには含まれていません。

非推奨

OTオブジェクト

TB オブジェクトの名前が OT（OpenTok の略）に変更されました。また、OpenTok.js ライブラリの URL が、opentok.min.js ファイルを指すようになった点にもご注意ください：

<script src="https://static.opentok.com/v2/js/opentok.min.js"></script>

ただし、下位互換性を確保するため、JavaScriptのTBオブジェクトは引き続き動作し、TB.min.jsのURLも引き続き利用可能です。

セッションへの接続

OpenTok.js ライブラリの最新バージョンでは、API キーを OT.initSession() メソッド（最初のパラメータとして）：

var session = OT.initSession(apiKey, sessionId);
session.connect(token, function(error) {
  if (!error) {
    var publisher OT.initPublisher();
    session.publish(publisher);
  }
});

に注意してほしい。 Session.connect() メソッドと OT.initPublisher() このメソッドは、API キーをパラメータとして受け付けません。API キーは OT.initSession() メソッド。（ただし、従来の構文も引き続きサポートされています。）

変化への対応

OpenTok JavaScript ライブラリのバージョン 1.0 との下位互換性を維持するよう努めました。ただし、API の変更点によっては、バージョン 1.0 から移植されたアプリにおいて、コードの修正が必要になる場合があります。

クライアントによって公開されたストリームのストリームイベントの変更

Session オブジェクトはディスパッチを行いません streamCreated ストリーム向けのイベントは、あなたの 自身の クライアントが公開します。パブリッシャーに対してストリームが作成されたことを検知するには、 Session.publish() メソッドを使用する：

var publisher = session.publish(publisher, properties, function(error) {
  if (error) {
    console.log("Failed to publish.")
  } else {
    console.log("Stream publishing.")
  }
})

Publisher オブジェクトは、 streamCreated そのストリームが公開するイベント。

さらに、Publisher オブジェクト（Session オブジェクトではなく）が、 streamDestroyed そのパブリッシャーが発行するイベント。パブリッシャーを（再利用のために）HTML DOM 内に保持したい場合は、 preventDefault() のイベントリスナー内のメソッド streamDestroyed パブリッシャーによってディスパッチされたイベント：

publisher = OT.initPublisher(apiKey)
  .on("streamDestroyed", function(event) {
    event.preventDefault(); // This lets you reuse the Publisher.
  }
);

を呼び出す。 preventDefault() のメソッドを使用する。 streamDestroyed そして sessionDisconnected Session オブジェクトによってディスパッチされるイベントオブジェクトは、（バージョン 1.0 のときのように）Publisher オブジェクトの削除を妨げなくなりました。

詳しくは ストリームおよび接続イベントの変更点.

セッション内の初期ストリームおよび接続の検出

現在の OpenTok.js ライブラリでは、 connections そして streams プロパティの sessionConnected イベントは非推奨となっており、これらは空の配列に設定されています。Session オブジェクトは connectionCreated そして streamCreated セッション内の各クライアントおよびストリームに対するイベント（接続時および接続後の両方）。

接続時に、そのセッションに別のクライアントが存在していたかどうかを確認するには、 connection.creationTime プロパティの connectionCreated 以下のイベントオブジェクト connection.creationTime Session オブジェクトのプロパティ：

session.on("connectionCreated", function(event) {
  if (event.connection.creationTime <= session.connection.creationTime) {
    console.log("Detected a client that connected before you.")
  }
}

詳しくは ストリームおよび接続イベントの変更点.

シグナリングAPIの改善

バージョン1.0では、 Session.signal() このメソッドは、セッションに接続しているすべてのクライアントに対して単にpingを送信するだけです。OpenTok.js ライブラリの最新バージョンでは、より多くの機能を備えた新しいシグナリング API が導入されました。これにより、シグナルにデータ文字列を含めることができるほか、セッション全体またはセッションに接続している特定のクライアントに対してシグナルを送信できるようになりました。詳細については、JavaScript の シグナリング・チュートリアル.

その他の変更点および新機能

その他の変更点について確認したり、その他の新機能を活用したりするには、以下をご覧ください。 新機能.

新機能

• インテリジェントな品質管理—公開されたストリームについて、推奨される動画解像度とフレームレートを設定できるようになりました。また、サブスクライバーの動画ストリームの帯域幅使用量を削減することも可能です。
• メソッドの完了ハンドラ—OpenTok.js ライブラリの一部のメソッドには、新たに以下のものが追加されました。 completionHandler パラメータ。このパラメータは、メソッドが成功または失敗した際に呼び出される関数です。
• 新しいイベント登録方法—OpenTok.js ライブラリの最新バージョンには、新しいメソッドが追加されています — on(), once()そして off() — イベントリスナーの追加や削除を行うため。
• ストリームおよび接続イベントの変更点—OpenTok.js ライブラリには、ストリームや、OpenTok セッションへのクライアントの参加・退出に関連するイベントの改善が含まれています。
• パブリッシャーおよびサブスクライバーの DOM API—HTML DOM へのパブリッシャーおよびサブスクライバーの挿入・削除を行うための新しい API が追加されました。
• 新しい Publisher.accessAllowed プロパティ—その accessAllowed このプロパティを使用すると、クライアントがカメラやマイクへのアクセスを許可しているかどうかを確認できます。

新しいAPI

インテリジェントな品質管理

OpenTok.js ライブラリの最新バージョンでは、公開されたストリームの推奨動画解像度とフレームレートを設定する機能が追加されました。

公開ストリームの推奨ビデオ解像度を設定するには、次のように設定します。 resolution プロパティの properties パラメータに渡す OT.initPublisher() メソッドを使用する：

var publisherProperties = {resolution: "1280x720"};
var publisher = OT.initPublisher(apiKey, targetElement, publisherProperties);

これは resolution プロパティは文字列で、ビデオの解像度を指定します。文字列の形式は "widthxheight"ここで、幅と高さはピクセルで表されます。有効な値は "1280x720", "640x480"そして "320x240".

要求されたビデオストリームの解像度は、 videoDimensions.width そして videoDimensions.height Stream オブジェクトのプロパティ。

ストリームのデフォルトの解像度（解像度を指定しない場合）は 640×480 ピクセルです。クライアントシステムが要求された解像度に対応できない場合、ストリームは対応可能な次大きい解像度設定を使用します。

公開ストリームの推奨フレームレートを設定するには frameRate プロパティの properties パラメータに渡す OT.initPublisher() メソッドを使用する：

var publisherProperties = {frameRate: 7};
var publisher = OT.initPublisher(apiKey, targetElement, publisherProperties);

この値を、動画の希望するフレームレート（1秒あたりのフレーム数）に設定してください。有効な値は、30、15、7、1です。

パブリッシャーがフレームレートを指定した場合、ビデオストリームの実際のフレームレートは frameRate Stream オブジェクトのプロパティですが、実際のフレームレートはネットワークやシステムの状態の変化によって異なります。開発者がフレームレートを指定しない場合、このプロパティの値は未定義となります。

OpenTok Media Router を使用するセッション（ メディアモード （ルーティング設定に設定されている場合）、フレームレートを下げたり解像度を下げたりすると、ストリームが使用できる最大帯域幅が減少します。ただし、 メディアモード 「中継」に設定されている場合、フレームレートや解像度を下げても、ストリームの帯域幅は削減されない可能性があります。

また、サブスクライバーのビデオストリームのフレームレートを制限することもできます。サブスクライバーのフレームレートを制限するには、 restrictFrameRate() 加入者のメソッドに、以下を引数として渡して true:

mySubscriber.restrictFrameRate(true);

パス・イン false また、動画ストリームのフレームレートに制限はありません：

mySubscriber.restrictFrameRate(false);

フレームレートが制限されている場合、加入者ビデオフレームは1秒間に1回以下しか更新されない。

この機能はセッション内でのみ利用可能です メディアモード 「routed」に設定されている場合で、メディアモードが「relayed」に設定されているセッション内では実行できません。「relayed」セッションでは、このメソッドを呼び出しても何の効果もありません。

加入者のフレームレートを制限することには、次のような利点がある：

• CPUの使用率を減らすことができる。
• アプリが消費するネットワーク帯域幅を削減します。
• より多くのストリームを同時に購読できる。

加入者のフレームレートを下げても、他のクライアントのビデオのフレームレートには影響しません。

最後に、OpenTok Media Router を使用するセッションでは、OpenTok Media Router がクライアントのネットワーク環境がビデオ通信に対応していないと判断した場合、サブスクライバーは音声のみの通信に切り替えることができます。 この機能は OpenTok.js 1.0 では利用できませんでした。最新の OpenTok ライブラリでは、クライアントのネットワーク接続状態が改善し、ビデオ通信が可能になった場合、クライアントは videoEnabled イベントが終了すると、動画が再開されます。

メソッドの完了ハンドラ

OpenTok.js ライブラリの一部のメソッドには、新たに completionHandler パラメータ。このオプションのパラメータには、メソッドが成功または失敗した際に呼び出される関数を渡すことができます。

例えば、 connect() Session オブジェクトのメソッドには、completionHandler パラメータが追加されました。これは、このメソッドの最後のパラメータです。この関数は 1 つのパラメータを受け取ります―― error. 成功した場合、その completionHandler この関数には引数が渡されません。エラーが発生した場合、この関数には error オブジェクトパラメータ。その error このオブジェクトには2つのプロパティがあります： code （整数）および message （文字列）で、障害の原因を特定します。次のコードでは、 completionHandler を呼び出すときに connect() メソッドを使用する：

// Set apiKey and token to your API key and a token for the session.
session.connect(apiKey, token, function(error) {
  if (error) {
    console.log(error.message);
  } else {
    console.log("Connected to session.");
  }
});

なお、セッションに接続すると、Session オブジェクトは sessionConnected イベントに加え、 completionHandler。しかし、その completionHandler OpenTok.js ライブラリには、メソッド呼び出しの成否を確認するための標準的な方法が用意されています。

以下の各メソッドには、それぞれ completionHander パラメータを、メソッドの最後のパラメータとして指定します：

• OT.initPublisher()
• Session.connect()
• Session.forceDisconnect()
• Session.forceUnpublish()
• Session.publish()
• Session.signal()
• Session.subscribe()

チェック message プロパティを参照してください。

エラーが発生した場合 code の値である。 error パラメータは Error オブジェクトに設定されます。詳細については、OpenTok のドキュメントを参照してください。 エラークラス.

新しいイベント登録方法

OpenTok.js ライブラリに、新しいメソッドが追加されました — on(), once()そして off() — イベントリスナーの追加および削除を行うため。これらのメソッドは、イベントをディスパッチできる各クラスに追加されます：

• 発行元 — on(), off(), once()
• セッション — on(), off(), once()
• 購読者 — on(), off(), once()
• OT — on(), off(), once()

について addEventListener() そして removeEventListener() これらのメソッドは非推奨となりました。これらは新しいメソッドに置き換えられています。新しいメソッドには、次のような利点があります：

• 1回の呼び出しで、複数のイベントハンドラを追加または削除することができます。 on() または off().

  たとえば、次のコードは、 accessAllowed, accessDeniedそして streamDestroyed Publisher オブジェクトのイベント：

  コピー

  publisher.on({
    accessAllowed: function (event) {
      // This is the handler for the accessAllowed event.
    },
    accessDenied:  function (event) {
      // This is the handler for accessDenied.
    }
    streamDestroyed: function (event) {
      // This is the handler for the streamDestroyed event.
    },
  });
  

• について once() このメソッドを使えば、1回だけ呼び出されるイベントリスナーを簡単に追加できます。（これは、 on() そして、次のように呼び出して off() イベントハンドラ関数内で。

• を使用することができます。 context の値を設定するためのパラメータ this ハンドラメソッド内で。

ストリームおよび接続イベントの変更点

OpenTok.js ライブラリでは、ストリームやクライアントのセッションへの参加・離脱に関連するイベントについて、いくつかの改善が追加されました。

StreamEvent または ConnectionEvent ごとに 1 つの項目

最新の OpenTok.js ライブラリでは、 ConnectionEvent クラス。これは、 connectionCreated そして connectionDestroyed イベントには、 connection プロパティ。これは、作成または破棄された単一のConnectionを表します。この connections property（バージョン 1.0 以降）は非推奨となっています。

同様に StreamEvent クラス。これは、 streamCreated そして streamDestroyed イベントには、 stream プロパティ。これは、作成または破棄された単一のストリームを表します。この streams property（バージョン 1.0 以降）は非推奨となっています。

そこで、セッション内で他のクライアントやそのストリームを検出するには（初回接続時またはそれ以降）、単に connectionCreated そして streamCreated セッションオブジェクトによってディスパッチされるイベント：

var connectionCount = 0;
session.on(
  {
    connectionCreated: function(event) {
      connectionCount++;
      console.log("New client: " event.connection.connectionId);
      console.log("Clients in the session: " connectionCount);
    },
    connectionDestroyed: function(event) {
      connectionCount--;
      console.log("Client left the session: " event.connection.connectionId);
      console.log("Clients in the session: " connectionCount);
    },
    streamCreated: function(event) {
      console.log("Stream created: " event.stream.streamId);
      // This is another client's stream, so you may want to subscribe to it.
    },
    streamDestroyed: function(event) {
      console.log("Stream destroyed: " event.stream.streamId);
      // This is another client's stream leaving the session.
    }
  }
).connect(apiKey, token, function(error) {
  if (error) {
    console.log("Failed to connect: " error.message);
  } else {
    connectionCount++;
  }
});

sessionConnected イベントからのストリームおよび接続の非推奨化

OpenTok.js ライブラリのバージョン 2 では、 connections そして streams プロパティの sessionConnected イベントは非推奨となっており、これらは空の配列に設定されています。バージョン 2 では、Session オブジェクトは connectionCreated そして streamCreated セッション内の各クライアントおよびストリームに対するイベント（接続時および接続後の両方）。

接続時に、そのセッション内に存在する他のクライアントを検出するには、 connection.creationTime プロパティの connectionCreated イベントを、以下のものと比較し、 connection.creationTime Session オブジェクトのプロパティ：

session.on("connectionCreated", function(event) {
  if (event.connection.creationTime <= session.connection.creationTime) {
    console.log("Detected a client that connected before you.")
  }
}

のコンプリートハンドラを使用できます。 Session.connect() の代わりに、 sessionConnected イベント（サンプルコードに示されているように）。

配信するストリームのイベントに関する変更点

OpenTok.js ライブラリのバージョン 2 では、Publisher オブジェクト（Session オブジェクトではない）がディスパッチを行います streamCreated そして streamDestroyed 配信するストリームに関するイベント。

publisher = OT.initPublisher(apiKey)
  .on(
    {
      streamCreated: function(event) {
        // The Publisher started streaming.
      },
      streamDestroyed: function(event) {
        // The Publisher stopped streaming.
      }
    }
);

Session オブジェクトはディスパッチを行いません streamCreated ストリーム向けのイベントは、あなたの 自身の クライアントが公開します。したがって、このイベントが自身が公開したストリームのいずれかに該当するかどうかを確認する必要はありません。たとえば、セッション内のすべてのサードパーティ製ストリームを購読したい場合は、単に次のコードを使用すればよいです：

session.on("streamCreated", function(event) {
    session.subscribe(event.stream);
  },
}

ストリームが破棄された際の Publisher オブジェクトの保持

（再利用のために）HTML DOM 内に Publisher を保持したい場合は、 preventDefault() のイベントリスナー内のメソッド streamDestroyed パブリッシャーによってディスパッチされたイベント：

publisher = OT.initPublisher(apiKey)
  .on("streamDestroyed", function(event){
    event.preventDefault(); // This lets you reuse the Publisher.
  }
);

を呼び出す。 preventDefault() のメソッドを使用する。 sessionDisconnected このイベントが発生しても、パブリッシャーが保持されることはなくなりました。

パブリッシャーおよびサブスクライバーの DOM API

OpenTok.js ライブラリのバージョン 2 には、HTML DOM への Publisher および Subscriber の挿入および削除を行うための新しい API が含まれています。

について insertMode プロパティの properties パラメーターの OT.initPublisher() これは、Publisher オブジェクトが HTML DOM 内に、 targetElement パラメータを設定します。このパラメータには、以下のいずれかの値を設定できる：

• "replace" - Publisherオブジェクトは、targetElementのコンテンツを置換します。これは既定です。
• "after" - Publisherオブジェクトは、HTML DOMのtargetElementの後に挿入される新しい要素です。(PublisherとtargetElementはどちらも同じ親要素を持ちます)。
• "before" - Publisherオブジェクトは、HTML DOMのtargetElementの前に挿入される新しい要素です。(PublisherとtargetElementはどちらも同じ親要素を持ちます)。
• "append" - Publisherオブジェクトは、targetElementの子要素として追加される新しい要素です。他の子要素がある場合、Publisher は targetElement の最後の子要素として追加されます。

例えば、次のコードは、新しいPublisherオブジェクトを publisherContainer DOM要素：

var publisherProperties = {insertMode: "append"};
var publisher = OT.initPublisher('publisher', publisherContainer, function(error) {
  if (error) {
    console.log(error);
  } else {
    console.log("Publisher initialized.");
  }
});

各 Publisher オブジェクトおよび Subscriber オブジェクトには、 element プロパティ。これは、パブリッシャーまたはサブスクライバーを含む HTML DOM 要素に設定されます。

各 Publisher オブジェクトおよび Subscriber オブジェクトは、 destroyed オブジェクトがHTML DOMから削除された際に発生するイベントです。このイベントに応答して、削除されたパブリッシャーまたはサブスクライバーに関連するDOM要素を調整（または削除）することができます。

新しい Publisher.accessAllowed プロパティ

新しい accessAllowed このプロパティは、クライアントがカメラとマイクへのアクセスを許可したかどうかを示します。さらに、パブリッシャーは引き続き accessAllowed そして accessDenied イベントについては、バージョン1.0と同様です。