Migration depuis la version 1.0 de la bibliothèque OpenTok.js

Les dernière version de la bibliothèque OpenTok.js utilise WebRTC à la place d'Adobe Flash pour les communications audio-vidéo. Ce guide vous aide à migrer votre site web de la version 1.0 vers la dernière version de la bibliothèque OpenTok.js.

La dernière version de la bibliothèque OpenTok.js interagit avec les applications à l'aide des bibliothèques OpenTok suivantes :

• Le SDK OpenTok pour Android 2.3 et versions ultérieures
• Le SDK OpenTok pour iOS 2.3 et versions ultérieures

Si vous effectuez une migration de code depuis la version 2.0, consultez cette page.

• Chargement de la dernière version de la bibliothèque OpenTok.js
• Modes de support pour la création de sessions
• Migration vers la dernière version de la bibliothèque OpenTok.js
• Nouvelles fonctionnalités

Chargement de la dernière version de la bibliothèque OpenTok.js

Régler le src de l'attribut script Ajoutez la balise suivante à l'URL ci-dessous pour charger la dernière version de la bibliothèque OpenTok.js :

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

Création de sessions et modes multimédia

Vous devez créer de nouvelles sessions pour pouvoir utiliser la nouvelle bibliothèque OpenTok.js. Les sessions qui étaient auparavant utilisées dans OpenTok 1.0 ne peuvent pas être utilisées dans la dernière version d'OpenTok.

Dans la version 1.0, les flux étaient soit transmis directement entre les clients (peer-to-peer), soit acheminés via le routeur multimédia OpenTok. Lorsque vous créiez une session pour la version 1.0 à l'aide de l'un des SDK serveur OpenTok, vous définissiez un p2p.preference au paramètre "enabled" ou "disabled". Cela change dans la dernière version d'OpenTok.

Désormais, lorsque vous créez une session, vous devez préciser comment les clients participant à cette session enverront leurs flux audio et vidéo, ce que l'on appelle le mode média. Il existe deux options :

• Relayé — Dans une session relayée, les clients tentent d’échanger des flux audio-vidéo directement entre eux (peer-to-peer). Toutefois, si les clients ne parviennent pas à se connecter en raison de restrictions de pare-feu, la session utilise le serveur TURN d’OpenTok pour relayer les flux audio-vidéo. (Avant la version 2.2, les SDK du serveur OpenTok désignaient ces sessions comme des sessions peer-to-peer. Cependant, même en utilisant ces SDK, les sessions continueront d’utiliser le serveur TURN d’OpenTok pour relayer les flux si des restrictions de pare-feu bloquent la diffusion peer-to-peer.)

• Acheminé — La session utilise OpenTok Media Router pour acheminer les flux audio-vidéo entre les clients. Le Routeur multimédia OpenTok offre les avantages suivants :

  • Le routeur multimédia OpenTok permet de réduire la consommation de bande passante lors des sessions multipartites. (Lorsque la propriété « media mode » est définie sur « relayed », chaque client doit envoyer un flux audio-vidéo distinct à chaque client qui s'y est abonné.)
  • Le routeur multimédia OpenTok permet d'améliorer la qualité de l'expérience utilisateur grâce à repli audio et récupération vidéo. Grâce à cette fonctionnalité, si la connexion d'un client se détériore au point de ne plus permettre la lecture de la vidéo d'un flux auquel il est abonné, la vidéo est interrompue pour ce client (sans affecter les autres clients), et celui-ci ne reçoit alors que le son. Si la connexion du client s'améliore, la vidéo reprend.
  • Le routeur multimédia OpenTok prend en charge le Fonctionnalité d'archivage d'OpenTok 2.0, qui vous permet d'enregistrer, de sauvegarder et de consulter des sessions OpenTok.

Remarque : Dans les nouvelles versions des SDK serveur OpenTok, le mode multimédia par défaut est le mode relais. (Dans les versions antérieures, le mode par défaut était l'utilisation du routeur multimédia OpenTok.)

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

Mise à jour vers la dernière version de la bibliothèque OpenTok.js

Important : La dernière version de la bibliothèque OpenTok.js comporte des modifications qui ne sont pas compatibles avec OpenTok.js 1.0. Cette section vous explique comment adapter votre code existant afin qu'il fonctionne avec la dernière version de la bibliothèque OpenTok.js.

API supprimée

Les classes, propriétés, méthodes et événements suivants, issus de la version 1.0, ne figurent pas dans la dernière version d'OpenTok.js.

Déclassé

L'objet OT

L'objet TB a été renommé OT (pour OpenTok). Notez également que l'URL de la bibliothèque OpenTok.js pointe désormais vers le fichier opentok.min.js :

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

Toutefois, pour des raisons de compatibilité ascendante, l'objet JavaScript « TB » continuera de fonctionner, tout comme l'URL « TB.min.js ».

Connexion à une session

Dans la dernière version de la bibliothèque OpenTok.js, vous devez transmettre votre clé API à la OT.initSession() méthode (en tant que premier paramètre) :

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

Il convient de noter que le Session.connect() et la méthode OT.initPublisher() Ces méthodes ne prennent pas de clé API en paramètre, puisque vous transmettez la clé API dans le OT.initSession() méthode. (La syntaxe ancienne est toutefois toujours prise en charge.)

Changements en cours

Nous nous sommes efforcés de préserver la compatibilité ascendante avec la version 1.0 de la bibliothèque JavaScript OpenTok. Cependant, certaines modifications apportées à l'API nécessitent des adaptations du code pour les applications portées depuis la version 1.0.

Modifications apportées aux événements de flux pour les flux publiés par votre client

L'objet Session n'effectue pas de répartition streamCreated événements pour vos flux propre le client publie. Pour détecter la création d'un flux pour votre éditeur, ajoutez un gestionnaire d'achèvement pour le Session.publish() méthode :

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

L'objet Publisher déclenche également un streamCreated événement associé au flux qu'il publie.

De plus, c'est désormais l'objet Publisher (et non l'objet Session) qui se charge de streamDestroyed événements liés au flux qu'il publie. Si vous souhaitez conserver l'éditeur dans le DOM HTML (en vue d'une réutilisation), appelez la méthode preventDefault() méthode dans l'écouteur d'événement pour le streamDestroyed événement déclenché par l'éditeur :

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

Appeler le preventDefault() de la méthode streamDestroyed et sessionDisconnected Les objets d'événement émis par l'objet Session n'empêchent plus la suppression de l'objet Publisher (contrairement à ce qui se passait dans la version 1.0).

Pour plus de détails, voir Modifications apportées aux événements de flux et de connexion.

Détection des flux et des connexions initiaux au cours d'une session

Dans la bibliothèque OpenTok.js actuelle, le connections et streams de la propriété sessionConnected Les événements sont obsolètes et sont définis comme des tableaux vides. L'objet Session gère connectionCreated et streamCreated les événements pour chaque client et chaque flux de la session, tant au moment de la connexion qu'après celle-ci.

Pour vérifier si un autre client était connecté au moment où vous vous connectez, comparez le connection.creationTime de la propriété connectionCreated objet d'événement avec le connection.creationTime propriété de l'objet Session :

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

Pour plus de détails, voir Modifications apportées aux événements de flux et de connexion.

API de signalisation améliorée

Dans la version 1.0, le Session.signal() Cette méthode se contente d'envoyer une requête « ping » à tous les clients connectés à la session. La dernière version de la bibliothèque OpenTok.js introduit une nouvelle API de signalisation, offrant davantage de fonctionnalités. Vous pouvez désormais inclure une chaîne de données dans le signal, et envoyer ce signal à l'ensemble de la session ou à des clients spécifiques connectés à celle-ci. Pour plus de détails, consultez la documentation JavaScript Tutoriel sur la signalisation.

Autres modifications et nouvelles fonctionnalités

Pour en savoir plus sur les autres modifications et commencer à profiter des nouvelles fonctionnalités, consultez Nouvelles fonctionnalités.

Nouvelles fonctionnalités

• Contrôle qualité intelligent—Vous pouvez désormais définir une résolution et une fréquence d'images recommandées pour un flux publié. Vous pouvez également réduire la consommation de bande passante du flux vidéo d'un abonné.
• Gestionnaires de fin d'exécution pour les méthodes—Certaines méthodes de la bibliothèque OpenTok.js comportent désormais un completionHandler paramètre. Ce paramètre est une fonction qui est appelée lorsque la méthode aboutit ou échoue.
• Nouvelles méthodes d'inscription aux événements—La dernière version de la bibliothèque OpenTok.js comprend de nouvelles méthodes — on(), once()et off() — pour ajouter et supprimer des écouteurs d'événements.
• Modifications apportées aux événements de flux et de connexion—La bibliothèque OpenTok.js intègre des améliorations concernant les événements liés aux flux et aux clients qui rejoignent ou quittent des sessions OpenTok.
• API DOM « Publisher » et « Subscriber »—De nouvelles API permettent d'ajouter et de supprimer des éléments « Publisher » et « Subscriber » dans le DOM HTML.
• Nouvelle propriété Publisher.accessAllowed—Le accessAllowed Cette propriété vous permet de savoir si un client a autorisé l'accès à la caméra et au microphone.

Nouvelle API

Contrôle qualité intelligent

La dernière version de la bibliothèque OpenTok.js intègre de nouvelles fonctionnalités permettant de définir la résolution vidéo et la fréquence d'images recommandées pour un flux publié.

Pour définir une résolution vidéo recommandée pour un flux publié, définissez le paramètre resolution de la propriété properties que vous passez dans le paramètre OT.initPublisher() méthode :

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

Le présent resolution est une chaîne de caractères définissant la résolution souhaitée pour la vidéo. Le format de la chaîne est le suivant "widthxheight"où la largeur et la hauteur sont représentées en pixels. Les valeurs valables sont "1280x720", "640x480"et "320x240".

La résolution demandée pour un flux vidéo est définie comme suit : videoDimensions.width et videoDimensions.height propriétés de l'objet Stream.

La résolution par défaut d'un flux (si vous n'en spécifiez pas) est de 640 × 480 pixels. Si le système client ne prend pas en charge la résolution que vous avez demandée, le flux utilisera la résolution immédiatement supérieure prise en charge.

Pour définir une fréquence d'images recommandée pour un flux publié, définissez le paramètre frameRate de la propriété properties que vous passez dans le paramètre OT.initPublisher() méthode :

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

Définissez la valeur correspondant à la fréquence d'images souhaitée, en images par seconde, pour la vidéo. Les valeurs valides sont 30, 15, 7 et 1.

Si l'éditeur spécifie une fréquence d'images, la fréquence d'images réelle du flux vidéo est définie comme la fréquence d'images de l'éditeur. frameRate propriété de l'objet Stream, bien que la fréquence d'images réelle varie en fonction des conditions du réseau et du système. Si le développeur ne spécifie pas de fréquence d'images, cette propriété n'est pas définie.

Pour les sessions qui utilisent OpenTok Media Router (sessions avec le mode média (réglé sur « routed »), la réduction de la fréquence d'images ou de la résolution diminue la bande passante maximale que le flux peut utiliser. Cependant, dans les sessions qui ont le mode média Si le mode de diffusion est réglé sur « relais », la réduction de la fréquence d'images ou de la résolution peut ne pas entraîner une diminution de la bande passante du flux.

Vous pouvez également limiter la fréquence d'images du flux vidéo d'un abonné. Pour limiter la fréquence d'images d'un abonné, appelez la fonction restrictFrameRate() méthode de l'abonné, en lui transmettant true:

mySubscriber.restrictFrameRate(true);

Entrer false et la fréquence d'images du flux vidéo n'est pas limitée :

mySubscriber.restrictFrameRate(false);

Lorsque la fréquence d'images est limitée, l'image vidéo de l'abonné est actualisée une fois ou moins par seconde.

Cette fonctionnalité n'est disponible que dans les sessions mode média définie sur « routed », et non dans les sessions où le mode multimédia est défini sur « relayed ». Dans les sessions « relayed », l'appel de cette méthode n'a aucun effet.

La limitation de la fréquence d'images de l'abonné présente les avantages suivants :

• Il réduit l'utilisation de l'unité centrale.
• Il réduit la largeur de bande du réseau consommée par l'application.
• Il vous permet de vous abonner à plusieurs flux simultanément.

La réduction de la fréquence d'images d'un abonné n'a aucun effet sur la fréquence d'images de la vidéo dans les autres clients.

Enfin, dans les sessions utilisant OpenTok Media Router, un abonné peut passer en mode audio uniquement lorsque OpenTok Media Router détermine que les conditions réseau du client ne permettent pas la vidéo. Cette fonctionnalité n'était pas disponible dans OpenTok.js 1.0. Dans la dernière version de la bibliothèque OpenTok, si la connectivité réseau du client s'améliore suffisamment pour prendre en charge la vidéo, le client envoie un videoEnabled événement, et la vidéo reprend.

Gestionnaires de fin d'exécution pour les méthodes

Certaines méthodes de la bibliothèque OpenTok.js intègrent désormais une nouvelle completionHandler paramètre. Pour ce paramètre facultatif, vous pouvez passer une fonction qui sera appelée en cas de réussite ou d'échec de la méthode.

Par exemple, le connect() La méthode d'un objet Session inclut désormais un paramètre « completionHandler ». Il s'agit du dernier paramètre de la méthode. Cette fonction prend un paramètre — error. En cas de réussite, le completionHandler Aucun argument n'est transmis à la fonction. En cas d'erreur, la fonction reçoit un error paramètre d'objet. Le error L'objet possède deux propriétés : code (un nombre entier) et message (une chaîne de caractères), qui identifie la cause de l'échec. Le code suivant ajoute un completionHandler lors de l'appel du connect() méthode :

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

Notez qu’une fois la connexion à la session établie, l’objet Session déclenche un sessionConnected événement, en plus d'appeler la fonction completionHandler. Cependant, le completionHandler Dans la bibliothèque OpenTok.js, cette méthode offre un moyen standard de vérifier si l'appel d'une méthode a abouti ou a échoué.

Chacune des méthodes suivantes comprend un completionHander paramètre, en tant que dernier paramètre de la méthode :

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

Vérifier le message pour plus de détails sur l'erreur.

En cas d'erreur, le code de la valeur de la error Le paramètre est défini sur un objet Error. Pour plus d'informations, consultez la documentation d'OpenTok Classe d'erreur.

Nouvelles méthodes d'inscription aux événements

La bibliothèque OpenTok.js comprend désormais de nouvelles méthodes — on(), once()et off() — pour ajouter et supprimer des écouteurs d'événements. Ces méthodes sont ajoutées à chaque classe capable de déclencher un événement :

• Éditeur — on(), off(), une fois()
• Session — on(), off(), une fois()
• Abonné — on(), off(), une fois()
• Hors sujet — on(), off(), une fois()

Les addEventListener() et removeEventListener() Ces méthodes sont obsolètes. Elles sont remplacées par les nouvelles méthodes. Les nouvelles méthodes présentent les avantages suivants :

• Vous pouvez ajouter ou supprimer plusieurs gestionnaires d'événements en un seul appel à on() ou off().

  Par exemple, le code suivant ajoute des écouteurs d'événements pour le accessAllowed, accessDeniedet streamDestroyed événements associés à un objet Publisher :

  Copie

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

• Les once() Cette méthode vous permet d'ajouter facilement un écouteur d'événement qui n'est appelé qu'une seule fois. (Cela revient à appeler on() puis en appelant off() dans la fonction de gestion des événements.

• Vous pouvez utiliser le context paramètre permettant de définir la valeur de this dans la méthode de gestionnaire.

Modifications apportées aux événements de flux et de connexion

La bibliothèque OpenTok.js intègre désormais plusieurs améliorations concernant les événements liés aux flux et aux clients qui rejoignent ou quittent une session.

Un élément par StreamEvent ou ConnectionEvent

Dans la dernière version de la bibliothèque OpenTok.js, le ConnectionEvent classe, qui définit le connectionCreated et connectionDestroyed événements, dispose d'un connection propriété, représentant la connexion unique créée ou supprimée. La connections La propriété (à partir de la version 1.0) est obsolète.

De même, le StreamEvent classe, qui définit le streamCreated et streamDestroyed événements, dispose d'un stream propriété, représentant le flux unique créé ou détruit. Le streams La propriété (à partir de la version 1.0) est obsolète.

Ainsi, pour détecter les autres clients et leurs flux au cours d'une session (lors de la première connexion ou par la suite), il suffit d'enregistrer des écouteurs d'événements pour le connectionCreated et streamCreated événements déclenchés par l'objet de 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);
  } else {
    connectionCount++;
  }
});

Suppression progressive des flux et des connexions à partir de l'événement « sessionConnected »

Dans la version 2 de la bibliothèque OpenTok.js, le connections et streams de la propriété sessionConnected Les événements sont obsolètes et sont définis comme des tableaux vides. Dans la version 2, l'objet Session déclenche connectionCreated et streamCreated les événements pour chaque client et chaque flux de la session, tant au moment de la connexion qu'après celle-ci.

Pour détecter les autres clients présents dans une session au moment où vous vous connectez, comparez le connection.creationTime de la propriété connectionCreated événement et le comparer avec le connection.creationTime propriété de l'objet Session :

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

Vous pouvez utiliser le gestionnaire de fin pour le Session.connect() méthode au lieu de la sessionConnected événement (comme indiqué dans l'exemple de code).

Modifications apportées aux événements des flux que vous publiez

Dans la version 2 de la bibliothèque OpenTok.js, c'est un objet Publisher (et non l'objet Session) qui se charge de la diffusion streamCreated et streamDestroyed les événements liés aux flux qu'elle publie.

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

L'objet Session n'effectue pas de répartition streamCreated événements pour vos flux propre publié par le client. Il n'est donc pas nécessaire de vérifier si cet événement correspond à l'un de vos propres flux publiés. Par exemple, si vous souhaitez vous abonner à tous les flux tiers de la session, il vous suffit d'utiliser le code suivant :

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

Conservation d'un objet Publisher lorsque son flux est détruit

Si vous souhaitez conserver l'éditeur dans le DOM HTML (à des fins de réutilisation), appelez la méthode preventDefault() méthode dans l'écouteur d'événement pour le streamDestroyed événement déclenché par l'éditeur :

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

Appeler le preventDefault() de la méthode sessionDisconnected Cet événement n'entraîne plus la conservation d'un éditeur.

API DOM « Publisher » et « Subscriber »

La version 2 de la bibliothèque OpenTok.js inclut de nouvelles API permettant d'ajouter et de supprimer des objets « Publisher » et « Subscriber » dans le DOM HTML.

Les insertMode de la propriété properties du paramètre OT.initPublisher() définit la manière dont l'objet Publisher sera inséré dans le DOM HTML, par rapport à l' targetElement paramètre. Ce paramètre peut prendre l'une des valeurs suivantes :

• "replace" - L'objet Publisher remplace le contenu de l'élément targetElement. Il s'agit de la valeur par défaut.
• "after" - L'objet Publisher est un nouvel élément inséré après l'élément cible dans le DOM HTML. (Le Publisher et le targetElement ont tous deux le même élément parent).
• "before" - L'objet Publisher est un nouvel élément inséré avant l'élément cible dans le DOM HTML. (Le Publisher et le targetElement ont tous deux le même élément parent).
• "append" - L'objet Publisher est un nouvel élément ajouté en tant qu'enfant de l'élément cible. S'il existe d'autres éléments enfants, l'objet Publisher est ajouté en tant que dernier élément enfant de l'élément cible.

Par exemple, le code suivant ajoute un nouvel objet Publisher en tant qu'enfant d'un objet publisherContainer Élément DOM :

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

Chaque objet « Publisher » et « Subscriber » possède un element propriété, qui est associée à l'élément DOM HTML contenant l'éditeur ou l'abonné.

Chaque objet « Publisher » et « Subscriber » déclenche un destroyed événement déclenché lorsque l'objet a été supprimé du DOM HTML. En réponse à cet événement, vous pouvez choisir de modifier (ou de supprimer) les éléments du DOM associés à l'éditeur ou à l'abonné qui a été supprimé.

Nouvelle propriété Publisher.accessAllowed

Le nouveau accessAllowed Cette propriété indique si un client a autorisé l'accès à la caméra et au microphone. De plus, l'éditeur continue d'envoyer accessAllowed et accessDenied événements, comme c'était le cas dans la version 1.0.