Migration von Version 2.0 der OpenTok.js-Bibliothek

Die neueste Version Die OpenTok.js-Bibliothek enthält eine Reihe neuer Funktionen, die die Entwicklung von OpenTok-Apps vereinfachen. Dieses Dokument beschreibt die Änderungen, die in Version 2.2 hinzugefügt wurden (und auch in der aktuellen Version enthalten sind).

Wenn Sie Code von Version 1.0 auf diese Version migrieren, lesen Sie bitte diese Seite.

Die neueste Version der OpenTok.js-Bibliothek wird geladen

Um die neuen Funktionen der aktuellen Version nutzen zu können, legen Sie die src Attribut des script Tag zum Laden der neuen Bibliothek:

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

Umstellung auf die neueste Version der OpenTok.js-Bibliothek

Das ist wichtig: Die neueste Version der OpenTok.js-Bibliothek enthält Änderungen, die nicht mit OpenTok.js 2.0 kompatibel sind. In diesem Abschnitt erfahren Sie, wie Sie bestehenden Code anpassen können, damit er mit der neuesten Version der OpenTok.js-Bibliothek funktioniert.

Das OT-Objekt

Das TB-Objekt wurde in OT (für OpenTok) umbenannt. Beachten Sie außerdem, dass die URL für die OpenTok.js-Bibliothek nun auf die Datei „opentok.min.js“ verweist:

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

Aus Gründen der Abwärtskompatibilität funktioniert das JavaScript-TB-Objekt jedoch weiterhin, und auch die URL „TB.min.js“ ist nach wie vor gültig.

Verbinden mit einer Sitzung

Sie übergeben nun Ihren API-Schlüssel an die OT.initSession() Methode (als erster Parameter):

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

Beachten Sie, dass die Session.connect() Methode und die OT.initPublisher() Die Methode nimmt keinen API-Schlüssel als Parameter entgegen, da Sie den API-Schlüssel an die OT.initSession() Methode. (Die alte Syntax wird jedoch weiterhin unterstützt.)

Wechselnde Änderungen

Wir haben versucht, die Abwärtskompatibilität mit der OpenTok.js 2.0-Bibliothek zu gewährleisten. Einige der API-Änderungen in der neuesten Version von OpenTok.js erfordern jedoch gewisse Codeänderungen für Apps, die aus der OpenTok.js 2.0-Bibliothek portiert wurden.

Änderungen bei der Übertragung von Ereignissen für von Ihrem Client veröffentlichte Streams

Das Session-Objekt führt keine Weiterleitung durch streamCreated Ereignisse für Streams, Ihre eigene Client veröffentlicht. Um zu erkennen, wann ein Stream für Ihren Publisher erstellt wird, fügen Sie einen Abschluss-Handler für den Session.publish() Methode:

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

Das Publisher-Objekt löst außerdem ein streamCreated Ereignis für den von ihm veröffentlichten Stream.

Zudem wird in Version 2.2 das Publisher-Objekt (nicht das Session-Objekt) ausgelöst streamDestroyed Ereignisse für den von ihm veröffentlichten Stream. Wenn Sie den Publisher im HTML-DOM beibehalten möchten (zur Wiederverwendung), rufen Sie die preventDefault() Methode im Ereignis-Listener für die streamDestroyed Vom Publisher ausgelöstes Ereignis:

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

Aufrufen der preventDefault() Methode der streamDestroyed und sessionDisconnected Ereignisobjekte, die vom Session-Objekt ausgelöst werden, verhindern nicht mehr, dass das Publisher-Objekt entfernt wird (wie es noch in Version 2.0 der Fall war).

Für weitere Einzelheiten siehe Änderungen an Stream- und Verbindungsereignissen.

Erkennung von ersten Datenströmen und Verbindungen in einer Sitzung

In OpenTok.js 2.2+ ist die connections und streams Eigenschaft der sessionConnected Ereignisse sind veraltet und werden auf leere Arrays gesetzt. Das Session-Objekt löst connectionCreated und streamCreated Ereignisse für jeden Client und jeden Stream in der Sitzung, sowohl beim Herstellen der Verbindung als auch danach.

Um festzustellen, ob sich zum Zeitpunkt Ihrer Verbindung bereits ein anderer Client in der Sitzung befand, vergleichen Sie die connection.creationTime Eigenschaft der connectionCreated Ereignisobjekt mit dem connection.creationTime Eigenschaft des Session-Objekts:

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

Für weitere Einzelheiten siehe Änderungen an Stream- und Verbindungsereignissen.

Änderungen an der Methode „Session.signal()“

In der Session.signal() Methode, die data Eigenschaft der signal Der Parameter muss eine Zeichenkette sein. (In OpenTok.js 2.0 ist der data Die Eigenschaft könnte auf ein beliebiges JSON-serialisierbares Objekt gesetzt werden.)

Außerdem ist die optionale to Eigenschaft der signal Der Parameter erwartet ein einzelnes Connection-Objekt (das die Verbindung definiert, an die das Signal gesendet wird). Der to Die Eigenschaft akzeptiert kein Array von „Connection“-Objekten, wie es in der OpenTok.js 2.0-Bibliothek der Fall war.

Um ein Signal an mehrere einzelne Clients zu senden, die mit einer Sitzung verbunden sind, rufen Sie die Funktion signal() Methode wiederholt aufrufen und dabei ein einzelnes Connection-Objekt als to jedes Mal den Parameter:

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

Weitere Änderungen und neue Funktionen

Um mehr über weitere Änderungen zu erfahren und die neuen Funktionen zu nutzen, lesen Sie bitte Neue Funktionen in Version 2.2.

Neue Funktionen

Auf dieser Seite werden die Funktionen beschrieben, die in Version 2.2 hinzugefügt wurden. Siehe die aktuelle Versionshinweise für Funktionen, die seitdem hinzugefügt wurden.

  • Intelligente Qualitätskontrolle—Sie können nun eine empfohlene Videoauflösung und Bildrate für einen veröffentlichten Stream festlegen. Außerdem können Sie die Bandbreitennutzung des Videostreams eines Abonnenten reduzieren.
  • Abschluss-Handler für Methoden—Einige Methoden in der neuesten Version der OpenTok.js-Bibliothek enthalten nun eine zusätzliche completionHandler Parameter. Dieser Parameter ist eine Funktion, die aufgerufen wird, wenn die Methode erfolgreich ist oder fehlschlägt.
  • Neue Verfahren zur Anmeldung zu Veranstaltungen—Die neueste Version der OpenTok.js-Bibliothek enthält neue Methoden — on(), once()und off() — zum Hinzufügen und Entfernen von Ereignis-Listenern.
  • Änderungen an Stream- und Verbindungsereignissen—Die neueste Version der OpenTok.js-Bibliothek enthält Verbesserungen bei Ereignissen im Zusammenhang mit Streams sowie beim Beitritt und Austritt von Clients aus OpenTok-Sitzungen.
  • Publisher- und Subscriber-DOM-APIs—Es gibt neue APIs für das Einfügen und Entfernen von Publishern und Subscribern in das bzw. aus dem HTML-DOM.
  • Neue Eigenschaft „Publisher.accessAllowed“—Das accessAllowed Anhand dieser Eigenschaft können Sie erkennen, ob ein Kunde den Zugriff auf die Kamera und das Mikrofon freigegeben hat.

Intelligente Qualitätskontrolle

Die neueste Version der OpenTok.js-Bibliothek bietet nun Funktionen zur Festlegung der empfohlenen Videoauflösung und Bildrate für einen veröffentlichten Stream.

Um eine empfohlene Videoauflösung für einen veröffentlichten Stream festzulegen, setzen Sie die resolution Eigenschaft der properties Parameter, den Sie an die OT.initPublisher() Methode:

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

Diese resolution ist ein String, der die gewünschte Auflösung des Videos angibt. Das Format des Strings ist "widthxheight"wobei die Breite und Höhe in Pixeln angegeben werden. Gültige Werte sind "1280x720", "640x480"und "320x240".

Die gewünschte Auflösung eines Videostreams wird als videoDimensions.width und videoDimensions.height Eigenschaften des Stream-Objekts.

Die Standardauflösung für einen Stream (sofern Sie keine Auflösung angeben) beträgt 640 × 480 Pixel. Wenn das Client-System die von Ihnen angeforderte Auflösung nicht unterstützt, verwendet der Stream die nächsthöhere unterstützte Einstellung.

Um eine empfohlene Bildrate für einen veröffentlichten Stream festzulegen, setzen Sie die frameRate Eigenschaft der properties Parameter, den Sie an die OT.initPublisher() Methode:

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

Stellen Sie den Wert auf die gewünschte Bildrate des Videos in Bildern pro Sekunde ein. Gültige Werte sind 30, 15, 7 und 1.

Wenn der Herausgeber eine Bildrate angibt, wird die tatsächliche Bildrate des Video-Streams als frameRate Eigenschaft des Stream-Objekts, wobei die tatsächliche Bildrate je nach den jeweiligen Netzwerk- und Systembedingungen variieren kann. Wenn der Entwickler keine Bildrate angibt, ist diese Eigenschaft undefiniert.

Für Sitzungen, bei denen der OpenTok Media Router verwendet wird (Sitzungen mit dem Medienbetrieb (auf „geroutet“ eingestellt), eine Verringerung der Bildrate oder der Auflösung reduziert die maximale Bandbreite, die der Stream nutzen kann. In Sitzungen, bei denen die Medienbetrieb Wenn die Einstellung auf „Relayed“ gesetzt ist, führt eine Verringerung der Bildrate oder der Auflösung möglicherweise nicht zu einer Reduzierung der Bandbreite des Streams.

Sie können außerdem die Bildrate des Videostreams eines Abonnenten begrenzen. Um die Bildrate eines Abonnenten zu begrenzen, rufen Sie die restrictFrameRate() Methode des Teilnehmers, wobei true:

mySubscriber.restrictFrameRate(true);

Einreichen false und die Bildrate des Videostreams ist nicht begrenzt:

mySubscriber.restrictFrameRate(false);

Wenn die Bildrate eingeschränkt ist, wird das Videobild des Teilnehmers einmal oder weniger pro Sekunde aktualisiert.

Diese Funktion ist nur in Sitzungen verfügbar. Medienbetrieb auf „routed“ gesetzt sein; dies gilt nicht für Sitzungen, bei denen der Medienmodus auf „relayed“ gesetzt ist. In „relayed“-Sitzungen hat der Aufruf dieser Methode keine Auswirkung.

Die Begrenzung der Teilnehmerbildrate hat folgende Vorteile:

  • Es reduziert die CPU-Nutzung.
  • Dadurch wird die von der Anwendung verbrauchte Netzwerkbandbreite reduziert.
  • Damit können Sie mehrere Streams gleichzeitig abonnieren.

Die Reduzierung der Bildrate eines Teilnehmers hat keine Auswirkungen auf die Bildrate des Videos in anderen Clients.

Schließlich kann ein Teilnehmer in Sitzungen, die den OpenTok Media Router nutzen, auf reinen Audiobetrieb umschalten, wenn der OpenTok Media Router feststellt, dass die Netzwerkbedingungen des Clients keine Videoübertragung zulassen. Diese Funktion war bereits in OpenTok.js 2.0 verfügbar. In der neuesten Version der OpenTok.js-Bibliothek sendet der Client ein videoEnabled Ereignis, und das Video wird fortgesetzt.

Abschluss-Handler für Methoden

Einige Methoden in der OpenTok.js-Bibliothek enthalten nun eine neue completionHandler Parameter. Für diesen optionalen Parameter können Sie eine Funktion übergeben, die aufgerufen wird, wenn die Methode erfolgreich ist oder fehlschlägt.

Zum Beispiel die connect() Die Methode eines Session-Objekts enthält nun einen Parameter namens „completionHandler“. Dies ist der letzte Parameter der Methode. Diese Funktion nimmt einen Parameter entgegen — error. Bei Erfolg wird die completionHandler Der Funktion werden keine Argumente übergeben. Im Fehlerfall wird der Funktion ein error Objektparameter. Der error Das Objekt hat zwei Eigenschaften: code (eine ganze Zahl) und message (eine Zeichenkette), die die Ursache des Fehlers angibt. Der folgende Code fügt eine completionHandler beim Aufruf der connect() Methode:

// 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.");
  }
});

Beachten Sie, dass das Session-Objekt beim Herstellen der Verbindung zur Sitzung eine sessionConnected Ereignis zusätzlich zum Aufruf der completionHandler. Allerdings ist die completionHandler In der neuen OpenTok-Bibliothek gibt es eine Standardmethode, um zu prüfen, ob ein Methodenaufruf erfolgreich war oder fehlgeschlagen ist.

Die folgenden Methoden enthalten jeweils eine completionHander Parameter als letzten Parameter der Methode:

Prüfen Sie die message Eigenschaft für weitere Details über den Fehler.

Im Falle eines Fehlers wird die code Wert des error Der Parameter ist auf ein Error-Objekt gesetzt. Weitere Informationen finden Sie in der Dokumentation zu OpenTok. Fehlerklasse.

Neue Verfahren zur Anmeldung zu Veranstaltungen

Die OpenTok.js-Bibliothek enthält nun neue Methoden — on(), once()und off() — zum Hinzufügen und Entfernen von Ereignis-Listenern. Diese Methoden werden jeder Klasse hinzugefügt, die ein Ereignis auslösen kann:

Die addEventListener() und removeEventListener() Die bisherigen Methoden sind veraltet. Sie werden durch die neuen Methoden ersetzt. Die neuen Methoden bieten folgende Vorteile:

  • Sie können mehrere Ereignisbehandler in einem einzigen Aufruf von on() oder off().

    Der folgende Code fügt beispielsweise Ereignis-Listener für das accessAllowed, accessDeniedund streamDestroyed Ereignisse für ein Publisher-Objekt:

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

  • Die once() Mit dieser Methode können Sie ganz einfach einen Ereignis-Listener hinzufügen, der nur einmal aufgerufen wird. (Dies entspricht dem Aufruf von on() und anschließend den Aufruf off() in der Ereignisbehandlungsfunktion.

  • Sie können die context Parameter zum Festlegen des Werts von this in der Handler-Methode.

Änderungen an Stream- und Verbindungsereignissen

Die OpenTok.js-Bibliothek enthält nun eine Reihe von Verbesserungen bei den Ereignissen, die sich auf Streams sowie auf das Hinzufügen und Verlassen einer Sitzung durch Clients beziehen.

Ein Eintrag pro StreamEvent oder ConnectionEvent

Die ConnectionEvent Klasse, die die connectionCreated und connectionDestroyed Veranstaltungen, verfügt nun über eine connection Eigenschaft, die die einzelne erstellte oder gelöschte Verbindung darstellt. Die connections Die Eigenschaft (ab Version 2.0) ist veraltet.

Ähnlich verhält es sich mit der StreamEvent Klasse, die die streamCreated und streamDestroyed Veranstaltungen, hat eine stream Eigenschaft, die den einzelnen erstellten oder gelöschten Stream repräsentiert. Die streams Die Eigenschaft (ab Version 2.0) ist veraltet.

Um also Clients und deren Streams in einer Sitzung zu erkennen (bei der ersten Verbindung oder später), registrieren Sie einfach Ereignis-Listener für die connectionCreated und streamCreated Vom Session-Objekt ausgelöste Ereignisse:

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

Streams und Verbindungen aus dem „sessionConnected“-Ereignis werden nicht mehr unterstützt

In der neuen OpenTok.js-Bibliothek ist die connections und streams Eigenschaft der sessionConnected Die Ereignisse sind veraltet und werden auf leere Arrays gesetzt. In Version 2.2 löst das Session-Objekt connectionCreated und streamCreated Ereignisse für jeden Client und jeden Stream in der Sitzung, sowohl beim Herstellen der Verbindung als auch danach.

Um bei der Verbindung andere Clients zu erkennen, die sich bereits in einer Sitzung befinden, vergleichen Sie die connection.creationTime Eigenschaft der connectionCreated Ereignis und vergleiche es mit dem connection.creationTime Eigenschaft des Session-Objekts:

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

Sie können den Abschluss-Handler für die Session.connect() Methode anstelle der sessionConnected Ereignis (wie im Beispielcode gezeigt).

Änderungen an Ereignissen für von Ihnen veröffentlichte Streams

In der neuen OpenTok.js-Bibliothek sendet ein Publisher-Objekt (nicht das Session-Objekt) streamCreated und streamDestroyed Ereignisse für die von ihr veröffentlichten Streams.

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

Das Session-Objekt führt keine Weiterleitung durch streamCreated Ereignisse für Streams, Ihre eigene der Client veröffentlicht. Es ist also nicht erforderlich zu prüfen, ob dieses Ereignis einem Ihrer eigenen veröffentlichten Streams entspricht. Wenn Sie beispielsweise alle Streams von Drittanbietern in der Sitzung abonnieren möchten, können Sie einfach den folgenden Code verwenden:

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

Ein Publisher-Objekt beibehalten, wenn dessen Stream zerstört wird

Wenn Sie den Publisher im HTML-DOM beibehalten möchten (zur Wiederverwendung), rufen Sie die preventDefault() Methode im Ereignis-Listener für die streamDestroyed Vom Publisher ausgelöstes Ereignis:

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

Aufrufen der preventDefault() Methode der sessionDisconnected Dieses Ereignis führt nicht mehr dazu, dass ein Publisher beibehalten wird.

Publisher- und Subscriber-DOM-APIs

Die OpenTok.js-Bibliothek enthält nun neue APIs zum Einfügen und Entfernen von Publishern und Subscribern in das bzw. aus dem HTML-DOM.

Die insertMode Eigenschaft der properties Parameter des OT.initPublisher() legt fest, wie das Publisher-Objekt in das HTML-DOM eingefügt wird, im Verhältnis zum targetElement Parameter. Sie können diesen Parameter auf einen der folgenden Werte einstellen:

  • "replace" - Das Publisher-Objekt ersetzt den Inhalt des targetElements. Dies ist der Standard.
  • "after" - Das Publisher-Objekt ist ein neues Element, das nach dem targetElement im HTML-DOM eingefügt wird. (Publisher und targetElement haben beide dasselbe Elternelement).
  • "before" - Das Publisher-Objekt ist ein neues Element, das vor dem targetElement im HTML-DOM eingefügt wird. (Publisher und targetElement haben beide dasselbe Elternelement).
  • "append" - Das Publisher-Objekt ist ein neues Element, das als untergeordnetes Element des targetElements hinzugefügt wird. Wenn es weitere untergeordnete Elemente gibt, wird der Publisher als letztes untergeordnetes Element des targetElements angefügt.

Der folgende Code fügt zum Beispiel ein neues Publisher-Objekt als Kind einer publisherContainer DOM-Element:

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

Jedes Publisher- und Subscriber-Objekt verfügt über ein element Eigenschaft, die auf das HTML-DOM-Element gesetzt ist, das den Publisher oder Subscriber enthält.

Jedes Publisher- und Subscriber-Objekt sendet ein destroyed Ereignis, das ausgelöst wird, wenn das Objekt aus dem HTML-DOM entfernt wurde. Als Reaktion auf dieses Ereignis können Sie DOM-Elemente, die mit dem entfernten Publisher oder Subscriber in Verbindung stehen, anpassen (oder entfernen).

Neue Eigenschaft „Publisher.accessAllowed“

Das neue accessAllowed Diese Eigenschaft gibt an, ob ein Client den Zugriff auf die Kamera und das Mikrofon gewährt hat. Darüber hinaus sendet der Publisher weiterhin accessAllowed und accessDenied Ereignisse, so wie es in Version 2.0 der Fall war.