Migración desde la versión 2.0 de la biblioteca OpenTok.js

El última versión La biblioteca OpenTok.js incluye un conjunto de nuevas funciones que facilitan el desarrollo de aplicaciones OpenTok. Este documento describe los cambios que se incorporaron en la versión 2.2 (que también se incluyen en la última versión).

Si estás migrando código de la versión 1.0 a esta versión, consulta esta página.

Cargando la última versión de la biblioteca OpenTok.js

Para utilizar las nuevas funciones disponibles en la última versión, configura el src del atributo script etiqueta para cargar la nueva biblioteca:

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

Actualización a la última versión de la biblioteca OpenTok.js

Importante: La última versión de la biblioteca OpenTok.js incluye cambios que no son compatibles con OpenTok.js 2.0. En esta sección se explica cómo adaptar el código existente para que funcione con la última versión de la biblioteca OpenTok.js.

El objeto OT

El objeto TB ha pasado a llamarse OT (por OpenTok). Ten en cuenta también que la URL de la biblioteca OpenTok.js ahora apunta al archivo opentok.min.js:

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

No obstante, por motivos de compatibilidad con versiones anteriores, el objeto TB de JavaScript seguirá funcionando, al igual que la URL TB.min.js.

Conectarse a una sesión

Ahora debes introducir tu clave API en el OT.initSession() método (como primer parámetro):

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

Tenga en cuenta que el Session.connect() y el método OT.initPublisher() El método no admite una clave de API como parámetro, ya que la clave de API se pasa al OT.initSession() método. (No obstante, la sintaxis anterior sigue siendo compatible.)

Cambios de última hora

Hemos intentado mantener la compatibilidad con versiones anteriores de la biblioteca OpenTok.js 2.0. Sin embargo, algunos de los cambios en la API de la última versión de OpenTok.js requieren modificaciones en el código de las aplicaciones que se han adaptado desde la biblioteca OpenTok.js 2.0.

Cambios en la transmisión de eventos para las transmisiones publicadas por tu cliente

El objeto «Session» no realiza el despacho streamCreated eventos para tus transmisiones en directo propio publica el cliente. Para detectar cuándo se crea un flujo para tu Publisher, añade un controlador de finalización para el Session.publish() método:

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

El objeto Publisher también envía un streamCreated evento para la transmisión que publica.

Además, en la versión 2.2, el objeto Publisher (y no el objeto Session) se encarga de streamDestroyed eventos del flujo que publica. Si quieres conservar el Publisher en el DOM HTML (para reutilizarlo), llama a la función preventDefault() método en el oyente de eventos para el streamDestroyed Evento enviado por el Publisher:

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

Llamada al preventDefault() método del streamDestroyed y sessionDisconnected Los objetos de evento enviados por el objeto «Session» ya no impiden que se elimine el objeto «Publisher» (como ocurría en la versión 2.0).

Para más información, consulte Cambios en los eventos de flujo y conexión.

Detección de flujos y conexiones iniciales en una sesión

En OpenTok.js 2.2 y versiones posteriores, el connections y streams propiedad del sessionConnected Los eventos están obsoletos y se establecen como matrices vacías. El objeto Session gestiona connectionCreated y streamCreated eventos para cada cliente y cada flujo de la sesión, tanto al conectarse como una vez conectado.

Para comprobar si había otro cliente en la sesión en el momento de conectarte, compara el connection.creationTime propiedad del connectionCreated objeto de evento con el connection.creationTime propiedad del objeto Session:

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

Para más información, consulte Cambios en los eventos de flujo y conexión.

Cambios en el método Session.signal()

En el Session.signal() método, el data propiedad del signal El parámetro debe ser una cadena. (En OpenTok.js 2.0, el data (La propiedad podría establecerse como cualquier objeto serializable en JSON.)

Además, la opción to propiedad del signal El parámetro toma un único objeto `Connection` (que define la conexión a la que se enviará la señal). El to La propiedad no admite un matriz de objetos «Connection», tal y como se hacía en la biblioteca OpenTok.js 2.0.

Para enviar una señal a varios clientes individuales conectados a una sesión, llama a la función signal() método de forma repetida, pasando un único objeto Connection como to parámetro cada vez:

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

Otros cambios y nuevas funciones

Para obtener más información sobre otros cambios y empezar a aprovechar otras nuevas funciones, consulta Novedades de la versión 2.2.

Nuevas funciones

En esta página se describen las funciones que se han añadido en la versión 2.2. Consulta la última notas de la versión para las funciones que se han añadido desde entonces.

  • Control de calidad inteligente—Ahora puedes configurar la resolución y la frecuencia de fotogramas recomendadas para una transmisión publicada. También puedes reducir el consumo de ancho de banda de la transmisión de vídeo de un suscriptor.
  • Manipuladores de finalización para métodos—Algunos métodos de la última versión de la biblioteca OpenTok.js incluyen ahora un completionHandler parámetro. Este parámetro es una función que se invoca cuando el método se ejecuta correctamente o falla.
  • Nuevos métodos de inscripción en eventos—La última versión de la biblioteca OpenTok.js incluye nuevos métodos — on(), once()y off() — para añadir y eliminar detectores de eventos.
  • Cambios en los eventos de flujo y conexión—La última versión de la biblioteca OpenTok.js incluye mejoras en los eventos relacionados con las transmisiones y con los clientes que se unen a las sesiones de OpenTok o las abandonan.
  • API de DOM para editores y suscriptores—Hay nuevas API para insertar y eliminar elementos Publisher y Subscriber del DOM HTML.
  • Nueva propiedad Publisher.accessAllowed—El accessAllowed Esta propiedad te permite comprobar si un cliente ha autorizado el acceso a la cámara y al micrófono.

Control de calidad inteligente

La última versión de la biblioteca OpenTok.js incorpora funciones para configurar la resolución de vídeo y la frecuencia de fotogramas recomendadas para una transmisión publicada.

Para establecer una resolución de vídeo recomendada para una transmisión publicada, configura el resolution propiedad del properties que se pasa al parámetro OT.initPublisher() método:

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

Este resolution es una cadena que define la resolución deseada del vídeo. El formato de la cadena es "widthxheight"donde la anchura y la altura se representan en píxeles. Los valores válidos son "1280x720", "640x480"y "320x240".

La resolución solicitada de una transmisión de vídeo se establece como la videoDimensions.width y videoDimensions.height propiedades del objeto Stream.

La resolución predeterminada de una transmisión (si no se especifica ninguna resolución) es de 640 x 480 píxeles. Si el sistema del cliente no admite la resolución solicitada, la transmisión utilizará la siguiente configuración más alta que admita.

Para establecer una frecuencia de fotogramas recomendada para una transmisión publicada, configura el frameRate propiedad del properties que se pasa al parámetro OT.initPublisher() método:

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

Establece el valor en la velocidad de fotogramas deseada, en fotogramas por segundo, del vídeo. Los valores válidos son 30, 15, 7 y 1.

Si el editor especifica una velocidad de fotogramas, la velocidad de fotogramas real de la secuencia de vídeo se establece como el valor de frameRate propiedad del objeto Stream, aunque la frecuencia de fotogramas real variará en función de las condiciones cambiantes de la red y del sistema. Si el desarrollador no especifica una frecuencia de fotogramas, esta propiedad no está definida.

En el caso de las sesiones que utilizan el OpenTok Media Router (sesiones con el modo multimedia configurado en «enrutado»), reducir la frecuencia de fotogramas o la resolución reduce el ancho de banda máximo que puede utilizar la transmisión. Sin embargo, en las sesiones que tienen el modo multimedia Si está configurado en «retransmitido», es posible que reducir la frecuencia de fotogramas o la resolución no reduzca el ancho de banda de la transmisión.

También puedes limitar la frecuencia de fotogramas de la transmisión de vídeo de un suscriptor. Para limitar la frecuencia de fotogramas de un suscriptor, llama a la función restrictFrameRate() método del suscriptor, pasando como parámetro true:

mySubscriber.restrictFrameRate(true);

Pasa el balón a false y la frecuencia de fotogramas de la transmisión de vídeo no está limitada:

mySubscriber.restrictFrameRate(false);

Cuando la frecuencia de imagen está restringida, la imagen de vídeo del abonado se actualizará una vez por segundo o menos.

Esta función solo está disponible en las sesiones modo multimedia configurado en «routed», no en sesiones en las que el modo multimedia esté configurado en «relayed». En sesiones «relayed», llamar a este método no tiene ningún efecto.

La restricción de la frecuencia de imagen del abonado tiene las siguientes ventajas:

  • Reduce el uso de la CPU.
  • Reduce el ancho de banda de red que consume la aplicación.
  • Te permite suscribirte a más flujos simultáneamente.

Reducir la frecuencia de fotogramas de un suscriptor no afecta a la frecuencia de fotogramas del vídeo en otros clientes.

Por último, en las sesiones que utilizan el OpenTok Media Router, un suscriptor puede pasar a modo de solo audio cuando el OpenTok Media Router determine que las condiciones de red del cliente no permiten el vídeo. Esta función ya estaba disponible en OpenTok.js 2.0. En la última versión de la biblioteca OpenTok.js, si la conectividad de red del cliente mejora lo suficiente como para admitir vídeo, el cliente envía un videoEnabled evento, y el vídeo se reanuda.

Manipuladores de finalización para métodos

Algunos métodos de la biblioteca OpenTok.js incluyen ahora un nuevo completionHandler parámetro. Para este parámetro opcional, puedes pasar una función que se ejecutará cuando el método tenga éxito o falle.

Por ejemplo, el connect() El método de un objeto `Session` incluye ahora un parámetro llamado `completionHandler`. Se trata del último parámetro del método. Esta función toma un parámetro: error. Si se realiza correctamente, el completionHandler A la función no se le pasa ningún argumento. En caso de error, se le pasa a la función un error parámetro de objeto. El error El objeto tiene dos propiedades: code (un número entero) y message (una cadena), que identifica la causa del fallo. El siguiente código añade un completionHandler al llamar a la connect() método:

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

Ten en cuenta que, al conectarse a la sesión, el objeto Session envía un sessionConnected evento, además de llamar a la función completionHandler. Sin embargo, el completionHandler En la nueva biblioteca de OpenTok se ofrece una forma estándar de comprobar si una llamada a un método se ha realizado con éxito o ha fallado.

Cada uno de los siguientes métodos incluye un completionHander parámetro, como último parámetro del método:

Compruebe el message para obtener más detalles sobre el error.

En caso de error, el code valor del error El parámetro se establece en un objeto Error. Para obtener más información, consulta la documentación de OpenTok Clase de error.

Nuevos métodos de inscripción en eventos

La biblioteca OpenTok.js incluye ahora nuevos métodos: — on(), once()y off() — para añadir y eliminar oyentes de eventos. Estos métodos se añaden a cada clase que pueda disparar un evento:

El addEventListener() y removeEventListener() Estos métodos están obsoletos. Han sido sustituidos por los nuevos métodos. Los nuevos métodos presentan las siguientes ventajas:

  • Puedes añadir o eliminar varios controladores de eventos en una sola llamada a on() o off().

    Por ejemplo, el siguiente código añade detectores de eventos para el accessAllowed, accessDeniedy streamDestroyed eventos de un objeto 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.
  },
});

  • El once() Este método te permite añadir fácilmente un detector de eventos que solo se activa una vez. (Es equivalente a llamar a on() y, a continuación, llamar a off() en la función del controlador de eventos.

  • Puedes utilizar el context parámetro para establecer el valor de this en el método del controlador.

Cambios en los eventos de flujo y conexión

La biblioteca OpenTok.js incluye ahora una serie de mejoras en los eventos relacionados con las transmisiones y con la incorporación y salida de clientes de una sesión.

Un elemento por cada StreamEvent o ConnectionEvent

El ConnectionEvent clase, que define el connectionCreated y connectionDestroyed eventos, cuenta ahora con un connection propiedad, que representa la única conexión creada o eliminada. La connections La propiedad (a partir de la versión 2.0) ha quedado obsoleta.

Del mismo modo, el StreamEvent clase, que define el streamCreated y streamDestroyed eventos, tiene un stream propiedad, que representa el único Stream creado o eliminado. El streams La propiedad (a partir de la versión 2.0) ha quedado obsoleta.

Por lo tanto, para detectar los clientes y sus flujos en una sesión (tanto al conectarse por primera vez como posteriormente), basta con registrar los detectores de eventos para el connectionCreated y streamCreated eventos emitidos por el objeto 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);
  }
});

Se desaconseja el uso de flujos y conexiones desde el evento «sessionConnected»

En la nueva biblioteca OpenTok.js, el connections y streams propiedad del sessionConnected Los eventos están obsoletos y se establecen como matrices vacías. En la versión 2.2, el objeto Session gestiona connectionCreated y streamCreated eventos para cada cliente y cada flujo de la sesión, tanto al conectarse como una vez conectado.

Para detectar si hay otros clientes conectados en una sesión en el momento de conectarte, compara el connection.creationTime propiedad del connectionCreated evento y compararlo con el connection.creationTime propiedad del objeto Session:

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

Puedes utilizar el controlador de finalización para el Session.connect() método en lugar del sessionConnected evento (tal y como se muestra en el código de ejemplo).

Cambios en los eventos de las transmisiones que publicas

En la nueva biblioteca OpenTok.js, es el objeto Publisher (y no el objeto Session) el que se encarga de distribuir streamCreated y streamDestroyed eventos relacionados con las retransmisiones que publica.

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

El objeto «Session» no realiza el despacho streamCreated eventos para tus transmisiones en directo propio publica el cliente. Por lo tanto, no es necesario comprobar si este evento corresponde a uno de tus propios flujos publicados. Por ejemplo, si quieres suscribirte a todos los flujos de terceros de la sesión, basta con utilizar el siguiente código:

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

Cómo conservar un objeto «Publisher» cuando se destruye su flujo

Si quieres conservar el Publisher en el DOM de HTML (para poder reutilizarlo), llama a la función preventDefault() método en el oyente de eventos para el streamDestroyed Evento enviado por el Publisher:

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

Llamada al preventDefault() método del sessionDisconnected Este evento ya no hace que se conserve un «Publisher».

API de DOM para editores y suscriptores

La biblioteca OpenTok.js incluye ahora nuevas API para insertar y eliminar «Publisher» y «Subscriber» del DOM de HTML.

El insertMode propiedad del properties del OT.initPublisher() especifica cómo se insertará el objeto Publisher en el DOM HTML, en relación con el targetElement parámetro. Puede establecer este parámetro en uno de los siguientes valores:

  • "replace" — El objeto Publisher sustituye el contenido del `targetElement`. Esta es la opción predeterminada.
  • "after" - El objeto Publisher es un nuevo elemento insertado después del targetElement en el DOM HTML. (Tanto el Publisher como el targetElement tienen el mismo elemento padre).
  • "before" - El objeto Publisher es un nuevo elemento insertado antes del targetElement en el DOM HTML. (Tanto el Publisher como el targetElement tienen el mismo elemento padre).
  • "append" — El objeto «Publisher» es un nuevo elemento añadido como elemento secundario del «targetElement». Si hay otros elementos secundarios, el «Publisher» se añade al final como último elemento secundario del «targetElement».

Por ejemplo, el siguiente código añade un nuevo objeto Publisher como hijo de un objeto publisherContainer Elemento DOM:

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

Cada objeto Publisher y Subscriber tiene un element propiedad, cuyo valor es el elemento del DOM de HTML que contiene al editor o al suscriptor.

Cada objeto «Publisher» y «Subscriber» envía un destroyed evento que se produce cuando el objeto se ha eliminado del DOM HTML. En respuesta a este evento, puedes optar por ajustar (o eliminar) los elementos del DOM relacionados con el editor o el suscriptor que se ha eliminado.

Nueva propiedad Publisher.accessAllowed

El nuevo accessAllowed Esta propiedad indica si un cliente ha concedido acceso a la cámara y al micrófono. Además, el Publisher sigue enviando accessAllowed y accessDenied eventos, tal y como ocurría en la versión 2.0.