Rejoindre une session — Web

À l'aide d'un identifiant de session et d'un jeton, vous pouvez vous connecter à la session OpenTok à l'aide de la bibliothèque OpenTok.js.

Cette rubrique comprend les sections suivantes :

Pour plus d'informations sur la création d'un identifiant de session et d'un jeton d'authentification, consultez Création de la session et Création de jetons.

Initialisation d'un objet Session

Avant de pouvoir vous connecter à une session, vous devez instancier un objet Session en appelant la méthode OT.initSession() méthode avec votre Clé API OpenTok et l'identifiant de session correspondant :

// Replace with your OpenTok API key and session ID:
var session = OT.initSession(apiKey, sessionID);

Les OT.initSession() renvoie un objet Session, par l'intermédiaire duquel les appels ultérieurs à l'API sont effectués.

Notez que l'appel à la fonction OT.initSession() n'est pas créer une session OpenTok ; cela crée un objet Session JavaScript, qui représente une session OpenTok existante. Vous créez une session OpenTok à l'aide des bibliothèques côté serveur d'OpenTok. Voir Création d'une session OpenTok.

Si le navigateur de l'utilisateur ne prend pas en charge WebRTC, l'appel à OT.initSession() la page affiche un message à l'intention de l'utilisateur. Pour vérifier la prise en charge de WebRTC et empêcher l'affichage de ce message, vous pouvez appeler la fonction OT.checkSystemRequirements() avant d'appeler la méthode OT.initSession():

if (OT.checkSystemRequirements() == 1) {
  var session = OT.initSession(apiKey, sessionId);
} else {
  // The client does not support WebRTC.
  // You can display your own message.
}

Connexion à une session

Une fois que vous avez a initialisé un objet Session, appelez son connect() méthode, en lui transmettant un jeton et une fonction de gestion des événements de fin :

var session = OT.initSession(apiKey, sessionId);
session.connect(token, function(error) {
  if (error) {
    console.log("Error connecting: ", error.name, error.message);
  } else {
    console.log("Connected to the session.");
  }
});

Un objet d'erreur est transmis au gestionnaire d'achèvement de la fonction connect événement se produisant lorsque le client ne parvient pas à se connecter à la session OpenTok. Dans le cas contraire, aucun objet d'erreur n'est transmis, ce qui indique que le client s'est connecté avec succès à la session.

L'objet Session envoie également un sessionConnected événement lorsque le client se connecte à la session OpenTok. Et l'objet OT déclenche un exception en cas d'erreur de connexion. Cependant, il est plus simple de vérifier le succès de la connexion en passant un gestionnaire d'achèvement dans l'événement connect() comme dernier paramètre.

Déconnexion d'une session

Pour se déconnecter d'une session, appelez le disconnect() de l'objet Session :

session.disconnect();

Détection de la déconnexion

Lorsque votre client se déconnecte d'une session, l'objet Session envoie un message de type sessionDisconnected événement :

session.on("sessionDisconnected", function (event) {
  // The event is defined by the SessionDisconnectEvent class
  if (event.reason == "networkDisconnected") {
    alert("Your network connection terminated.")
  }
});
session.connect(token);

Les reason La propriété de l'événement est une chaîne de caractères qui explique la raison de la déconnexion de la session. Par exemple, l'exemple précédent informe l'utilisateur s'il a été déconnecté en raison de l'interruption de la connexion réseau. Pour plus de détails, voir SessionDisconnectEvent.

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). Vous n'avez pas besoin d'ajouter de code pour que les clients se reconnectent automatiquement, sauf si vous souhaitez réagir aux événements déclenchés lorsque votre client se déconnecte puis se reconnecte. Pour obtenir un exemple de code illustrant l'utilisation de ces événements, consultez la section opentok-reconnexion sur GitHub.

Lorsque la connexion est interrompue et que le client tente de se reconnecter, l'objet Session envoie un message de type reconnecting . Lorsque la connexion est rétablie, l'objet Session envoie un événement reconnected événement. Si le client ne parvient pas à rétablir la connexion, il se déconnecte de la session OpenTok, et l'objet Session déclenche l'événement sessionDisconnected événement.

En réponse à ces événements, votre application peut (éventuellement) afficher des notifications d'interface utilisateur indiquant les états de déconnexion temporaire, de reconnexion et de déconnexion :

session.on(
  sessionReconnecting: function() {
    // Display a user interface notification.
  },
  sessionReconnected: function() {
    // Adjust user interface.
  },
  sessionDisconnected: function() {
    // Adjust user interface.
  }
);

Lorsque votre client se déconnecte temporairement d'une session, les objets Subscriber des clients souscrivant à un flux que vous publiez envoient des événements lorsque votre flux publié tombe et lorsque (et si) il reprend automatiquement. Pour plus d'informations, voir Reconnexion automatique dans le guide du développeur "S'abonner à des flux".

Par défaut, tous les signaux que vous envoyez lorsque votre client est temporairement déconnecté d'une session sont mis en file d'attente et envoyés lorsque (et si) vous vous reconnectez avec succès. Vous pouvez définir l'option retryAfterReconnect à la propriété false dans les options que vous passez dans le Session.signal() pour éviter que des signaux ne soient mis en file d'attente pendant que vous êtes déconnecté. Pour plus d'informations, voir Empêcher l'envoi de signaux lors d'une reconnexion automatique.

Détection de la connexion et de la déconnexion des clients

L'objet Session envoie un connectionCreated lorsqu'un nouveau client (y compris le vôtre) se connecte à la session. L'objet Session envoie un connectionDestroyed lorsque d'autres clients quittent la session. Ces événements sont définis par la classe ConnectionEvent, qui possède une fonction connection qui est un objet Connexion pour la connexion (créée ou détruite) liée à l'événement :

var connectionCount;
session.on({
  connectionCreated: function (event) {
    connectionCount++;
    if (event.connection.connectionId != session.connection.connectionId) {
      console.log('Another client connected. ' + connectionCount + ' total.');
    }
  },
  connectionDestroyed: function connectionDestroyedHandler(event) {
    connectionCount--;
    console.log('A client disconnected. ' + connectionCount + ' total.');
  }
});
session.connect(token, function (error) {
  if (error) {
    console.log("Failed to connect.");
  } else {
    console.log('You have connected to the session.');
  }
});

Résolution des problèmes de connexion à la session

Les Session.connect() possède une fonction de rappel à laquelle est transmise une valeur facultative de error paramètre. Si ce paramètre est présent et défini (pas null ou undefined), une erreur s'est produite lors de la connexion. La recherche de cette erreur dans votre code vous aidera à comprendre pourquoi l'utilisateur final n'a pas pu se connecter :

session.connect(token, function(err) {
  if (err) {
    // handle error
  } else {
    // connection succeeded
  }
});

Un grand nombre d'erreurs qui reviennent lors d'une tentative de connexion sont dues à des jetons non valides ou expirés. Veillez à respecter les bonnes pratiques en matière de jetons décrites dans le document suivant ici.

Une autre raison fréquente de l'échec de la connexion à une session est la connexion Internet de l'utilisateur final. Voici quelques exemples :

  • L'utilisateur final a perdu sa connexion internet
  • L'utilisateur final a des ports communs bloqués parce qu'il se trouve sur un réseau restrictif.

Cela entraînera une erreur avec le code 1006. Nous vous recommandons de gérer cette situation à l'aide du code ci-dessous. Parmi les autres raisons pouvant expliquer l'échec de la connexion à une session, on peut citer la panne des serveurs OpenTok ou la survenue d'une erreur imprévue (telle qu'une erreur de niveau 500 sur le serveur). Bien que cela n'arrive pas souvent, il est recommandé de prévoir une gestion de ces erreurs.

Si vous suivez ces instructions, votre code de gestion des erreurs devrait ressembler à ce qui suit :

session.connect(token, function(err) {
  if (err) {
    if (err.name === "OT_NOT_CONNECTED") {
      showMessage('Failed to connect. Please check your connection and try connecting again.');
    } else {
      showMessage('An unknown error occurred connecting. Please try again later.');
    }
  }
});

Vous pouvez perdre votre connexion après vous être connecté avec succès à une session. Vous pouvez gérer ce cas en écoutant la commande sessionDisconnected avec pour motif "networkDisconnected" :

session.on({
  sessionDisconnected: function(event) {
    if (event.reason === 'networkDisconnected') {
      showMessage('You lost your internet connection.'
        + 'Please check your connection and try connecting again.');
    }
  }
});

La mise en place de l'ensemble

Le code suivant contient un connect() méthode qui permet de se connecter à une session. Une fois connecté, le code détecte quand les clients rejoignent ou quittent la session. Il dispose également d'une méthode permettant de se déconnecter de la session :

var session;
var connectionCount = 0;

function connect() {
  // Replace apiKey and sessionId with your own values:
  session = OT.initSession(apiKey, sessionId);
  session.on({
    connectionCreated: function (event) {
      connectionCount++;
      console.log(connectionCount + ' connections.');
    },
    connectionDestroyed: function (event) {
      connectionCount--;
      console.log(connectionCount + ' connections.');
    },
    sessionDisconnected: function sessionDisconnectHandler(event) {
      // The event is defined by the SessionDisconnectEvent class
      console.log('Disconnected from the session.');
      document.getElementById('disconnectBtn').style.display = 'none';
      if (event.reason == 'networkDisconnected') {
        alert('Your network connection terminated.')
      }
    }
  });
  // Replace token with your own value:
  session.connect(token, function(error) {
    if (error) {
      console.log('Unable to connect: ', error.message);
    } else {
      document.getElementById('disconnectBtn').style.display = 'block';
      console.log('Connected to the session.');
      connectionCount = 1;
    }
  });
}

function disconnect() {
  session.disconnect();
}

connect();