Signalisation — Web

Utilisez l'API de signalisation OpenTok pour échanger du texte et des données entre les clients connectés à une session OpenTok.

Pour obtenir des informations conceptuelles sur l'API de signalisation OpenTok, consultez le Aperçu de la signalisation guide du développeur.

Cette rubrique comprend les sections suivantes :

Envoi d'un signal à un client spécifique au cours d'une session

Pour envoyer un signal à un client spécifique au cours d'une session, appelez la fonction signal() méthode de l'objet Session et définir la to de la propriété signal paramètre :

session.signal(
  {
    to: connection1,
    data:"hello"
  },
  function(error) {
    if (error) {
      console.log("signal error ("
                   + error.name
                   + "): " + error.message);
    } else {
      console.log("signal sent.");
    }
  }
);

Les to La propriété est une Connexion objet correspondant aux clients connectés à la session à laquelle vous souhaitez envoyer un signal. Vous obtenez des références aux objets `Connection` lorsque l'objet `Session` déclenche sessionConnected et connectionCreated événements. Vous pouvez également obtenir l'objet Connection correspondant à un flux en récupérant le connection de l'objet Stream.

Les data de la propriété signal Le paramètre correspond à la chaîne de données que vous envoyez avec le message. Cette propriété est facultative. Si vous ne la spécifiez pas, le message sera envoyé sans données. La taille maximale des données est de 8 Ko.

Les completerHandler du paramètre signal() La méthode est appelée lorsque l'appel de la méthode aboutit ou échoue. La error Le paramètre transmis au gestionnaire de complétion est défini sur null si l'appel aboutit. Lorsque l'appel de la méthode échoue, l'objet d'erreur possède les propriétés suivantes : code (un code d'erreur numérique), message (une chaîne de caractères décrivant l'erreur), et signal (un objet correspondant au signal passé dans le paramètre signal() ).

De plus, vous pouvez passer un type de la propriété signal paramètre. Il s'agit d'une chaîne de caractères que les clients peuvent utiliser comme critère de filtrage lorsque être à l'écoute des signaux:

session.signal(
  {
    data:"hello",
    type:"textMessage"
  },
  function(error) {
    if (error) {
      console.log("signal error ("
                   + error.name
                   + "): " + error.message);
    } else {
      console.log("signal sent.");
    }
  }
);

La longueur maximale du type est de 128 octets et ne doit contenir que des lettres (A-Z et a-z), des chiffres (0-9), des "-", des "_" et des "~".

Pour plus d'informations, consultez la documentation relative à la Session.signal() méthode.

Envoi d'un signal à tous les clients d'une session

Pour envoyer un signal à tous les clients d'une session, appelez la fonction signal() méthode de l'objet Session, mais ne pas définir un to pour la propriété signal paramètre :

session.signal(
  {
    data:"hello"
  },
  function(error) {
    if (error) {
      console.log("signal error ("
                   + error.name
                   + "): " + error.message);
    } else {
      console.log("signal sent.");
    }
  }
);

Pour plus de détails sur les autres options que vous transmettez à la fonction signal() méthode, voir la section précédente.

L'appel de cette méthode sans limiter l'ensemble des clients destinataires entraînera l'envoi de plusieurs signaux (un à chaque client de la session).

Réception de signaux au cours d'une session

Pour commencer à recevoir tous les signaux envoyés au cours d'une session, ajoutez un écouteur d'événements pour le signal événement, déclenché par l'objet Session :

    session.on("signal", function(event) {
      console.log("Signal sent from connection " + event.from.id);
      // Process the event.data property, if there is any data.
    });

Vous pouvez également n'écouter que les signaux d'un type spécifique. (Vous pouvez définir le type d'un signal, si vous le souhaitez, lorsque vous envoyer un signal.) Enregistrer un écouteur d'événement pour le signal:type événement, en remplaçant « type » par la chaîne de caractères correspondant au type. Par exemple, le code suivant écoute les signaux de type « foo » :

session.on("signal:foo", function(event) {
 console.log("Signal sent from connection " + event.from.id);
 // Process the event.data property, if there is any data.
});

Vous pouvez comparer les from propriété de l'objet événement avec la connection propriété de l'objet Session permettant de vérifier si le signal a été envoyé par votre client ou par un autre :

session.on("signal:foo", function(event) {
  if (connection && event.from.connectionId != session.connection.id) {
    // Signal received from another client
  }
}

Notez que vous pouvez utiliser un Appel à l'API REST pour envoyer un signal depuis votre serveur, plutôt que depuis un client connecté à la session. Dans ce cas, le from de l'objet événement est fixée à null.

Empêcher l'envoi de signaux lors d'une reconnexion automatique

Les clients tenteront de se reconnecter automatiquement à une session dont ils se sont déconnectés de manière inattendue (par exemple, en raison d'une interruption de la connexion réseau). Par défaut, tous les signaux que vous envoyez pendant que le client est temporairement déconnecté d'une session sont mis en file d'attente et envoyés lorsque (et si) la reconnexion aboutit. Vous pouvez configurer le retryAfterReconnect à la propriété false dans les options que vous passez dans le Session.signal() méthode permettant d'éviter que les signaux ne soient mis en file d'attente lorsque le client est déconnecté. Pour plus d'informations, consultez Reconnexion automatique.