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

Les dernière version La bibliothèque OpenTok.js intègre désormais un ensemble de nouvelles fonctionnalités qui facilitent le développement d'applications OpenTok. Ce document décrit les modifications apportées dans la version 2.2 (qui figurent également dans la dernière version).

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

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

Pour utiliser les nouvelles fonctionnalités disponibles dans la dernière version, configurez le src de l'attribut script balise permettant de charger la nouvelle bibliothèque :

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

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

Vous devez maintenant 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 bibliothèque OpenTok.js 2.0. Cependant, certaines modifications apportées à l'API dans la dernière version d'OpenTok.js nécessitent des modifications du code pour les applications portées depuis la bibliothèque OpenTok.js 2.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, dans la version 2.2, c'est l'objet Publisher (et non l'objet Session) qui se charge de la distribution 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 2.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 OpenTok.js 2.2 et versions ultérieures, 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.

Modifications apportées à la méthode Session.signal()

Dans le cadre de la Session.signal() la méthode data de la propriété signal Le paramètre doit être une chaîne de caractères. (Dans OpenTok.js 2.0, le data (Cette propriété peut être définie sur n'importe quel objet sérialisable au format JSON.)

Par ailleurs, l'option to de la propriété signal Le paramètre prend un seul objet Connection (définissant la connexion vers laquelle le signal sera envoyé). Le to la propriété ne prend pas de réseau d'objets Connection, comme c'était le cas dans la bibliothèque OpenTok.js 2.0.

Pour envoyer un signal à plusieurs clients individuels connectés à une session, appelez la fonction signal() méthode de manière répétée, en lui transmettant un seul objet Connection en tant que to paramètre à chaque fois :

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

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 de la version 2.2.

Nouvelles fonctionnalités

Cette page présente les fonctionnalités ajoutées dans la version 2.2. Consultez la dernière notes de mise à jour pour les fonctionnalités ajoutées depuis lors.

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é était disponible dans OpenTok.js 2.0. Dans la dernière version de la bibliothèque OpenTok.js, 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 nouvelle bibliothèque OpenTok, 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 :

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 :

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 :

    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

Les ConnectionEvent classe, qui définit le connectionCreated et connectionDestroyed événements, dispose désormais d'un connection propriété, représentant la connexion unique créée ou supprimée. La connections La propriété (à partir de la version 2.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 2.0) est obsolète.

Ainsi, pour détecter les 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 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);
  }
});

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

Dans la nouvelle 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.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 nouvelle bibliothèque OpenTok.js, c'est un objet Publisher (et non l'objet Session) qui gère 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 bibliothèque OpenTok.js intègre désormais de nouvelles API permettant d'ajouter et de supprimer des éléments « 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 2.0.