Vidéo en tête-à-tête avec l'API Video de Vonage

L'API Video de Vonage vous permet de créer à peu près n'importe quelle expérience vidéo. L'un des cas d'utilisation les plus courants pour les développeurs est le besoin de sessions vidéo individuelles simples, comme un médecin avec un patient ou un expert en sinistres avec un client.

Dans ce tutoriel

L'API Video de Vonage vous permet de créer rapidement une salle et d'y placer des participants. Nous verrons comment mettre en place une démo et la faire fonctionner avec nos démos existantes afin que vous n'ayez pas à écrire de code, mais nous expliquerons également ce que le code fait en arrière-plan.

1. Voir la démo - Découvrez la démo sans écrire de code
2. Fonctionnement de la démo - Côté client - Ce que fait le code côté client
3. Fonctionnement de la démo - Côté serveur - Ce que fait le code côté serveur

Conditions préalables

Pour compléter le tutoriel, vous avez besoin de :

• A Account Vonage - pour votre clé d'API et votre secret

Voir la démo

Si vous souhaitez tester la démo avant d'écrire le moindre code, nous disposons d'un exemple de serveur web et de code JavaScript pour tester ce à quoi ressemble un appel vidéo de base. Tout le code est open source et accessible au public, vous pouvez donc essayer la démo et utiliser le code pour faire vos propres modifications.

Lancer le serveur Node.js

La démo vidéo nécessite un serveur dorsal pour gérer des tâches telles que la création de jetons clients pour l'autorisation et la gestion générale de la session. Bien que vous puissiez construire ceci dans le langage de votre choix, nous avons un serveur pré-construit que vous pouvez utiliser pour commencer à l'adresse suivante Serveur d'apprentissage vidéo de Vonage (Node.js) sur Code Hub. De la Documentation pour les développeursCliquez sur "Code Hub" dans la barre de navigation supérieure, puis faites défiler vers le bas et trouvez la carte "Vonage Video Learning Server (Node.js)". Cliquez dessus pour l'ouvrir.

Vous obtiendrez une description de ce que fait ce projet. Pour l'instant, cliquons sur "Get code" afin de pouvoir le charger dans l'éditeur en ligne Code Hub. Cliquez sur "Créer un nouvel environnement de développement". Nommez l'espace de travail "Vonage Video Demo" car nous pouvons utiliser ce backend pour plusieurs démonstrations. Cette démo nécessite l'attribution d'un numéro, car le serveur d'apprentissage prend en charge les appels téléphoniques via SIP. Nous ne l'utiliserons pas dans cette démonstration, mais vous pouvez cliquer sur "Attribuer un numéro" pour attribuer un numéro existant que vous avez obtenu auprès de Vonage, ou en acheter un nouveau que vous utiliserez pour des démonstrations ultérieures.

Code Hub créera automatiquement une application pour vous, y compris la mise en place des clés publiques et privées que notre application utilisera. Une fois l'espace de travail créé, vous serez dirigé vers l'éditeur de code, qui est une version en ligne de Visual Studio Code. N'hésitez pas à suivre les parties ultérieures de cette démo pour voir le code, et vous pouvez modifier ce code si nécessaire pour vos propres projets.

Pour exécuter l'application, cliquez sur "View" en haut de l'éditeur, puis sur "Terminal". Cela ouvrira une ligne de commande dans laquelle nous pourrons exécuter des commandes. Tout ce que nous avons à faire est de taper vcr deploy et le code sera déployé. Cela prendra quelques instants, car le code est emballé et exécuté sur les serveurs de Vonage Code Hub. Nous voudrons prendre note de "l'adresse de l'hôte de l'instance" qu'il produit vers la fin.

Si tout fonctionne correctement, vous devriez pouvoir visiter l'adresse de l'hôte de l'instance et être accueilli par la page suivante :

Tester la partie frontale

Le serveur dorsal fonctionne directement avec toutes nos démonstrations préconstruites, y compris cette démo en tête-à-tête. Rendez-vous sur le site de https://github.com/Vonage-Community/video-api-web-samples/tree/main/Basic Video Chatqui est le code source de la partie frontale de cette démo. Cet exemple permet à deux utilisateurs ayant l'URL de se joindre à un chat vocal.

La façon la plus simple d'exécuter cette démo est de cliquer sur le bouton "Open in Stackblitz" dans le README.

Ceci ouvrira le projet dans Stackblitz. Comme pour le serveur backend, vous pouvez parcourir le code et le modifier ici si vous le souhaitez. Pour cette démo, tout ce que nous avons besoin de faire est d'ouvrir le fichier js/config.js et ajoutez l'URL de l'instance de Code Hub dans le fichier SAMPLE_SERVER_BASE_URL variable :

Une fois le fichier enregistré, vous pouvez actualiser la vue de démonstration sur le côté droit de Stackblitz et votre navigateur devrait vous demander d'autoriser votre microphone et votre caméra. Une fois l'autorisation obtenue, votre image devrait apparaître dans le coin inférieur de la barre latérale. Si vous copiez l'URL de Stackblitz au-dessus de la fenêtre de démonstration et que vous la visitez sur votre appareil mobile, sur un autre ordinateur ou que vous la donnez à un ami, toute personne qui se joindra à vous devrait être connectée à votre démo !

Comment fonctionne la démo

Configurer une application Vonage

Pour que notre application vidéo fonctionne, il faut que notre client et notre serveur puissent communiquer avec les serveurs de Vonage. Code Hub configure cela pour nous, mais si vous exécutez le code localement ou si vous voulez savoir ce que cela implique, une application Video est configurée comme n'importe quelle autre API. Nous devons mettre en place une Applications Vonage pour héberger toute la configuration de notre application, ainsi que pour aider à générer les éléments nécessaires à l'authentification.

Rendez-vous sur votre Tableau de bord des clients de Vonage et se connecter. Une fois que vous êtes connecté :

1. Cliquez sur "Applications" sous "Construire".
2. Cliquez sur "Créer une nouvelle application".
3. Donnez un nom à l'application, par exemple "Démonstration vidéo de base".
4. Cliquez sur "Generate public and private key", ce qui vous permettra de télécharger un fichier nommé private.key. Gardez une trace de ce fichier pour plus tard.
5. Faites défiler vers le bas et cliquez sur "Vidéo". Nous laisserons ces valeurs vides pour l'instant.
6. Cliquez sur "Générer une nouvelle application" pour créer l'application.

Une fois l'application créée, notez l'identifiant de l'application. Si vous exécutez le code localement, nous en aurons besoin pour configurer le backend. Si vous utilisez Code Hub, le code du serveur a déjà accès à l'identifiant de l'application et à la clé privée.

Le côté client

La partie client de la démo se compose de deux parties différentes : quelques éléments HTML pour placer les flux vidéo, puis du JavaScript pour récupérer les informations de connexion et communiquer avec les serveurs vidéo de Vonage.

Comme il s'agit d'une démonstration par navigateur, nous utilisons le SDK JavaScript situé à l'adresse suivante https://unpkg.com/@vonage/client-sdk-video@latest/dist/js/opentok.jset l'inclure dans une balise de script dans notre HTML en index.html.

Pour ajouter des personnes à une salle, nous n'avons besoin que de deux éléments : un endroit où placer l'utilisateur actuel, par exemple, vous, que nous appelons "éditeur". Nous avons ensuite besoin d'un endroit où placer toute autre personne qui rejoint la salle, à laquelle vous vous "abonnerez". Nous les placerons dans un élément "abonné".

Nous allons créer deux div et donner à l'un d'entre eux un identifiant de publisher et l'autre un ID de subscriber. Nous ferons référence à ces éléments dans le JavaScript lorsque la page sera visitée et lorsque nous détecterons qu'un autre utilisateur est entré dans l'appel vidéo.

Côté JavaScript, nous allons d'abord obtenir des informations sur l'appel vidéo lui-même. Pour se connecter à l'appel vidéo, nous avons besoin d'un identifiant d'application, d'un identifiant de session et d'un jeton.

• Les ID de l'application est un identifiant que le Client SDK utilise pour référencer les différents paramètres de notre application vidéo du côté de Vonage.
• Les ID de la session est une session vidéo spécifique à laquelle nous voulons nous connecter, car une seule Application peut avoir plusieurs sessions vidéo simultanées.
• Les Jeton est un jeton d'authentification JWT qui vous permet de rejoindre une session spécifique avec des droits spécifiques.

Bien que vous puissiez générer l'identifiant de session et le jeton à l'avance, dans le monde réel, vous les générerez à la demande. Notre code représente la façon de procéder. Nous montrerons comment les informations sont créées dans un instant, mais nous allons récupérer ces informations sur le serveur dorsal que nous avons déployé.

// src/app.js

// ...
} else if (SAMPLE_SERVER_BASE_URL) {
  // Make a GET request to get the Vonage Video Application ID, session ID, and token from the server
  fetch(SAMPLE_SERVER_BASE_URL + '/session')
  .then((response) => response.json())
  .then((json) => {
    applicationId = json.applicationId;
    sessionId = json.sessionId;
    token = json.token;
    // Initialize a Vonage Video Session object
    initializeSession();
  }).catch((error) => {
    handleError(error);
    alert('Failed to get Vonage Video sessionId and token. Make sure you have updated the config.js file.');
  });
}

Une fois que nous avons toutes les informations de connexion, nous pouvons appeler le SDK JavaScript de Vonage Video, qui gère tout le travail de connexion à l'API Video de Vonage du côté frontal. Tout d'abord, nous saisissons un objet de session avec OT.initSession(). Nous commençons alors à écouter sur le streamCreated événement avec session.on(). Cela nous permet de définir un rappel à exécuter lorsqu'un flux provenant d'un autre éditeur est créé. Dans ce cas, nous utilisons session.subscribe() pour se connecter à l'événement entrant, et le pousser dans le fichier subscriber que nous avons mis en place dans le HTML. Nous sommes également à l'écoute de l'élément sessionDisconnected pour savoir quand l'autre utilisateur se déconnecte, mais tout ce que nous faisons pour cette démo, c'est enregistrer le fait que nous avons remarqué qu'il est parti.

Ensuite, nous créons le publisher avec l'objet OT.initPublisher(). Nous lui indiquons à quelle div il doit s'attacher (publisher) et quelques options de formatage de base. Cela permet de connecter votre caméra et votre microphone à l'API Video.

Nous appelons ensuite session.connect() pour se connecter à la session, en utilisant le jeton de connexion JWT que nous avons récupéré sur le serveur. C'est tout ce qu'il faut pour que deux personnes rejoignent une salle !

// src/app.js

function initializeSession() {
  const session = OT.initSession(applicationId, sessionId);

  // Subscribe to a newly created stream
  session.on('streamCreated', (event) => {
    const subscriberOptions = {
      insertMode: 'append',
      width: '100%',
      height: '100%'
    };
    session.subscribe(event.stream, 'subscriber', subscriberOptions, handleError);
  });

  session.on('sessionDisconnected', (event) => {
    console.log('You were disconnected from the session.', event.reason);
  });

  // initialize the publisher
  const publisherOptions = {
    insertMode: 'append',
    width: '100%',
    height: '100%',
    resolution: '1280x720'
  };
  const publisher = OT.initPublisher('publisher', publisherOptions, handleError);

  // Connect to the session
  session.connect(token, (error) => {
    if (error) {
      handleError(error);
    } else {
      // If the connection is successful, publish the publisher to the session
      session.publish(publisher, handleError);
    }
  });
}

Le côté serveur

La partie serveur de toute application Vonage Video est utilisée pour gérer la création de sessions, la génération de jetons d'authentification et les tâches administratives telles que le démarrage et l'arrêt des archives. Pour cette démonstration, tout ce qui nous préoccupe est de créer des sessions et des jetons pour que les utilisateurs puissent rejoindre la salle. Bien que l'API elle-même soit une API REST et qu'elle puisse être appelée comme vous le souhaitez, nous vous encourageons à utiliser l'API SDK Vonage Node qui gère l'authentification et les appels HTTP pour vous. Vous pouvez l'installer dans votre propre application avec :

npm install -s @vonage/server-sdk

Le code de démonstration l'a déjà préinstallé. Si vous exécutez le code localement, vous devrez exécuter :

npm install

pour télécharger toutes les dépendances, puis copier .envcopy dans un nouveau fichier nommé .env. Vous devrez remplir les informations demandées dans le formulaire suivant .env comme l'ID de l'Application, l'emplacement de la clé privée sur le disque, ainsi que la clé et le secret de l'API de Vonage.

Création d'une session et participation à la session

La première chose que nous faisons est de vérifier si nous disposons déjà d'une session pour la pièce que nous générons. Nous conservons un dictionnaire en mémoire dans roomToSessionIdDictionaryet si la salle a déjà une session, nous extrayons simplement la session du dictionnaire. Nous utilisons ensuite le Vonage Client SDK pour créer un jeton de client en appelant vonage.video.generateClientToken()en lui transmettant l'identifiant de la session et un objet contenant une certaine configuration. Pour l'instant, tout ce que nous faisons, c'est attribuer à l'utilisateur une valeur de moderator pour cette simple démonstration. Nous renvoyons ensuite l'identifiant d'application, l'identifiant de session et le jeton configurés au front-end.

Si la session n'existe pas, nous en créons une nouvelle avec vonage.video.createSession(). Cela permet de contacter l'API de Vonage et de créer une session à laquelle les utilisateurs peuvent se connecter. Nous n'avons pas de paramètres spécifiques pour cette session, mais c'est ici que nous configurons des choses comme les règles d'archivage et la façon dont la session doit être gérée, comme le routage ou le peer-to-peer. Ensuite, comme précédemment, nous créons un jeton et renvoyons toutes ces informations au navigateur.

// routes/index.js

async function createSession(response, roomName, sessionProperties = {}, role = 'moderator') {
  let sessionId;
  let token;
  console.log(`Creating ${role} creds for ${roomName}`);

  if (roomToSessionIdDictionary[roomName]) {
    sessionId = roomToSessionIdDictionary[roomName];
    // generate token for user
    token = vonage.video.generateClientToken(sessionId, { role })
    response.setHeader('Content-Type', 'application/json');
    response.send({
      applicationId: appId,
      sessionId: sessionId,
      token: token
    });
  } else {
    try {
      // Create the session
      const session = await vonage.video.createSession(sessionProperties);
      roomToSessionIdDictionary[roomName] = session.sessionId;

      // generate token for user
      token = vonage.video.generateClientToken(session.sessionId, { role });
      response.setHeader('Content-Type', 'application/json');
      response.send({
        applicationId: appId,
        sessionId: session.sessionId,
        token: token
      });
    } catch(error) {
      console.error("Error creating session: ", error);
      response.status(500).send({ error: 'createSession error:' + error });
    }
  }
}

Conclusion

Dans ce tutoriel, vous avez vu ce que contient le serveur dorsal pour une simple session vidéo individuelle, comment créer un client Web pour que les utilisateurs puissent rejoindre une session et se voir et s'entendre, ainsi qu'un aperçu de la facilité avec laquelle il est possible d'utiliser le Vonage Code Hub et Stack Blitz pour tester rapidement des échantillons.

Pour en savoir plus

• Documentation du développeur vidéo de Vonage
• Spécification REST de l'API Video
• Guides