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

について 最新バージョン OpenTok.js ライブラリのこのバージョンには、OpenTok アプリの開発をより容易にする一連の新機能が含まれています。このドキュメントでは、バージョン 2.2 で追加された変更点（これらは最新バージョンにも含まれています）について説明します。

• OpenTok.js ライブラリの最新バージョンを読み込んでいます
• OpenTok.js ライブラリの最新バージョンへの移行
• バージョン2.2の新機能

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

OpenTok.js ライブラリの最新バージョンを読み込んでいます

最新バージョンで利用可能な新機能を使用するには、 src 属性の script 新しいライブラリを読み込むためのタグ：

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

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

重要だ： OpenTok.js ライブラリの最新バージョンには、OpenTok.js 2.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も引き続き利用可能です。

セッションへの接続

ここで、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.js 2.0 ライブラリとの下位互換性を維持するよう努めてきました。しかし、OpenTok.js の最新バージョンにおける API の変更の一部により、OpenTok.js 2.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 そのストリームが公開するイベント。

さらに、v2.2 では、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 オブジェクトによってディスパッチされるイベント オブジェクトは、（v2.0 のときのように）Publisher オブジェクトの削除を妨げなくなりました。

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

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

OpenTok.js 2.2 以降では、 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.")
  }
}

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

Session.signal() メソッドの変更点

の中で Session.signal() メソッドでは data プロパティの signal パラメータは文字列でなければなりません。（OpenTok.js 2.0 では、 data （プロパティには、JSONシリアライズ可能な任意のオブジェクトを設定できます。）

また、オプションの to プロパティの signal このパラメータには、1つのConnectionオブジェクト（信号が送信される接続を定義するもの）が渡されます。この to このプロパティは 配列 OpenTok.js 2.0 ライブラリと同様に、Connection オブジェクトの

セッションに接続している複数のクライアントに信号を送信するには、 signal() メソッドを繰り返し呼び出し、単一の Connection オブジェクトを to 毎回パラメータを指定する：

var connections;
// Set the connections object to an array of Connection objects corresponding to the clients you want to signal.

for (var i = 0; i < a.connections; i++) {
  session.signal(
    {
      type: "foo",
      to: connections[i],
      data: "hello"
    },
    function(error) {
      if (error) {
        console.log("signal error: " + error.reason);
      } else {
        console.log("signal sent");
      }
    }
  );
}

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

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

新機能

このページでは、バージョン 2.2 で追加された機能について説明しています。最新情報については、 リリースノート それ以降に追加された機能については。

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

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

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 2.0 で利用可能でした。 OpenTok.js ライブラリの最新バージョンでは、クライアントのネットワーク接続状態が改善し、ビデオ通信が可能になった場合、クライアントは 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 ライブラリでは、メソッド呼び出しの成否を確認するための標準的な方法が用意されています。

以下の各メソッドには、それぞれ 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 つの項目

について ConnectionEvent クラス。これは、 connectionCreated そして connectionDestroyed イベントには、現在、 connection プロパティ。これは、作成または破棄された単一のConnectionを表します。この connections プロパティ（v2.0以降）は非推奨となっています。

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

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

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);
  }
});

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

新しい OpenTok.js ライブラリでは、 connections そして streams プロパティの sessionConnected イベントは非推奨となっており、これらは空の配列に設定されています。v2.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 ライブラリでは、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 ライブラリには、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 イベントについては、バージョン2.0と同様です。