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

El última versión de la biblioteca OpenTok.js utiliza WebRTC en lugar de Adobe Flash para las comunicaciones de audio y vídeo. Esta guía te ayuda a migrar tu sitio web de la versión 1.0 a la última versión de la biblioteca OpenTok.js.

La última versión de la biblioteca OpenTok.js interactúa con las aplicaciones mediante las siguientes bibliotecas de OpenTok:

• El SDK de OpenTok para Android 2.3+
• El SDK de OpenTok para iOS 2.3+

Si estás migrando código desde la versión 2.0, consulta esta página.

• Cargando la última versión de la biblioteca OpenTok.js
• Modos de soporte para la creación de sesiones
• Migración a la última versión de la biblioteca OpenTok.js
• Nuevas funciones

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

Fije el src del atributo script Añade la siguiente URL para cargar la última versión de la biblioteca OpenTok.js:

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

Creación de sesiones y modos multimedia

Debes crear nuevas sesiones para utilizarlas en la nueva biblioteca OpenTok.js. Las sesiones que se utilizaban anteriormente en OpenTok 1.0 no se pueden utilizar en la última versión de OpenTok.

En la versión 1.0, las transmisiones se enviaban directamente entre clientes (punto a punto) o mediante el OpenTok Media Router. Al crear una sesión para la versión 1.0 utilizando uno de los SDK de servidor de OpenTok, se configuraba un p2p.preference parámetro a "enabled" o "disabled". Esto cambia en la última versión de OpenTok.

Ahora, al crear una sesión, debes especificar cómo enviarán los clientes de la sesión las transmisiones de audio y vídeo, lo que se conoce como el modo multimedia. Hay dos opciones:

• Retransmitido — En una sesión con retransmisión, los clientes intentarán enviar flujos de audio y vídeo directamente entre sí (punto a punto). Sin embargo, si los clientes no pueden conectarse debido a restricciones del cortafuegos, la sesión utiliza el servidor TURN de OpenTok para retransmitir los flujos de audio y vídeo. (Antes de la versión 2.2, los SDK del servidor OpenTok se referían a estas sesiones como sesiones «peer-to-peer». No obstante, incluso al utilizar esos SDK, las sesiones seguirán recurriendo al servidor TURN de OpenTok para retransmitir las transmisiones si las restricciones del cortafuegos bloquean la transmisión «peer-to-peer»).

• Enrutado — La sesión utiliza el OpenTok Media Router para enrutar las transmisiones de audio y vídeo entre los clientes. El OpenTok Media Router ofrece las siguientes ventajas:

  • El OpenTok Media Router puede reducir el consumo de ancho de banda en sesiones con varios participantes. (Cuando la propiedad «mode» de multimedia está configurada en «relayed», cada cliente debe enviar un flujo de audio y vídeo independiente a cada cliente suscrito a él.)
  • El OpenTok Media Router puede mejorar la calidad de la experiencia del usuario a través de recuperación de audio y vídeo. Con esta función, si la conexión de un cliente se deteriora hasta tal punto que no permite la reproducción de vídeo de una transmisión a la que está suscrito, el vídeo se interrumpe para ese cliente (sin que ello afecte al resto de clientes), y el cliente solo recibe audio. Si la conexión del cliente mejora, el vídeo vuelve a mostrarse.
  • El OpenTok Media Router es compatible con el Función de archivado de OpenTok 2.0, que te permite grabar, guardar y recuperar sesiones de OpenTok.

Nota: En las nuevas versiones de los SDK del servidor de OpenTok, el modo multimedia predeterminado es el de retransmisión. (En versiones anteriores, el valor predeterminado era utilizar el OpenTok Media Router.)

<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 1.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.

API eliminada

Las siguientes clases, propiedades, métodos y eventos de la versión 1.0 no se incluyen en la última versión de OpenTok.js.

En desuso

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

En la última versión de la biblioteca OpenTok.js, 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 JavaScript de OpenTok 1.0. Sin embargo, algunos de los cambios en la API requieren modificaciones en el código de las aplicaciones portadas desde la versión 1.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, el objeto Publisher (no el objeto Session) ahora envía 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 1.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 la biblioteca actual de OpenTok.js, 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.

API de señalización mejorada

En la versión 1.0, el Session.signal() Este método simplemente envía un ping a todos los clientes conectados a la sesión. La última versión de la biblioteca OpenTok.js introduce una nueva API de señalización, con más funcionalidades. Ahora puedes incluir una cadena de datos en la señal y puedes enviar la señal a toda la sesión o a clientes específicos conectados a ella. Para más detalles, consulta la documentación de JavaScript Tutorial de señalización.

Otros cambios y nuevas funciones

Para obtener más información sobre otros cambios y empezar a aprovechar otras nuevas funciones, consulta Nuevas funciones.

Nuevas funciones

• 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 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 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.

Nueva API

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 no estaba disponible en OpenTok.js 1.0. En la última versión de la biblioteca OpenTok, 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 biblioteca OpenTok.js se ofrece una forma estándar de comprobar si la 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:

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

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:

• Editor — on(), off(), una vez()
• Sesión — on(), off(), una vez()
• Suscriptor — on(), off(), una vez()
• OT — on(), off(), una vez()

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:

  Copia

  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 incorpora 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

En la última versión de la biblioteca OpenTok.js, el ConnectionEvent clase, que define el connectionCreated y connectionDestroyed eventos, tiene un connection propiedad, que representa la única conexión creada o eliminada. La connections La propiedad (a partir de la versión 1.0) está en desuso.

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 1.0) está en desuso.

Por lo tanto, para detectar otros clientes y sus flujos en una sesión (tanto al conectarte por primera vez como posteriormente), basta con registrar detectores de eventos para el connectionCreated y streamCreated eventos emitidos por el objeto de sesión:

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

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

En la versión 2 de la 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, 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 versión 2 de la biblioteca OpenTok.js, es un 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 versión 2 de la biblioteca OpenTok.js incluye nuevas API para insertar y eliminar componentes 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 1.0.