Guide de transition des callbacks du SDK JS vers les Promises

Ce guide explique comment migrer le code existant du SDK JavaScript de la Video API de Vonage, en passant des gestionnaires de fin d'exécution basés sur les callbacks à des API basées sur les promesses.

Vue d'ensemble

À partir de la version 2.35.1, le SDK JavaScript prend en charge l'exécution basée sur les « promises » pour les utilitaires de l'espace de noms OT ainsi que pour un large éventail d'API Session, Publisher et Subscriber. Cela vous permet de :

• Remplacer les callbacks imbriqués par async / await
• Gérer les erreurs à l'aide de la norme try / catch
• Présenter plus clairement les flux de publication et d'abonnement
• Effectuez la migration de manière progressive, car les signatures des fonctions de rappel restent disponibles pour assurer la compatibilité ascendante.

On distingue deux types de migration :

• Remboursement direct garanti: À utiliser lorsque la méthode elle-même résout ou rejette une promesse. Exemple : const devices = await OT.getDevices()
• .promise assistant: À utiliser lorsque la méthode héritée renvoie toujours Session, Publisherou Subscriber, et l'API « promise » est exposée sur cette méthode sous la forme d'un .promise(...) fonction d'aide. Exemple : await session.connect.promise(token)

Remarque : Les écouteurs d'événements ne changent pas. Continuez à les utiliser session.on(...), publisher.on(...)et subscriber.on(...) pour les événements asynchrones.

Ce qui a changé

La mise en œuvre du projet « Promisification » s'est déroulée par étapes :

• Utilitaires de l'espace de noms OT, tels que la recherche de périphériques, la vérification des capacités de partage d'écran et le signalement des problèmes
• Aides relatives au cycle de vie des sessions et à la modération
• Session.publish() et Session.subscribe()
• Statistiques des éditeurs et API de gestion des éditeurs
• Statistiques sur les abonnés et API de gestion des abonnés

Concrètement, cela signifie que la majeure partie du code des gestionnaires de fin d'opération dans un client web peut désormais être réécrite à l'aide de promesses.

Stratégie de migration

1. Convertissez la fonction qui gère votre flux Video API Vonage en async.
2. Remplacer les gestionnaires d’achèvement par await.
3. Enveloppez les appels d'API dans try/catch.
4. Conservez le code piloté par les événements sous forme d'événements.
5. Utiliser le .promise lorsque la méthode héritée renvoie encore un objet permettant d'enchaîner les méthodes.

Modèle courant « avant-après »

Flux basé sur les rappels

const session = OT.initSession(apiKey, sessionId);

session.connect(token, function(connectError) {
  if (connectError) {
    console.error(connectError);
    return;
  }

  const publisher = OT.initPublisher('publisher', publisherOptions, function(publisherError) {
    if (publisherError) {
      console.error(publisherError);
      return;
    }

    session.publish(publisher, function(publishError) {
      if (publishError) {
        console.error(publishError);
      }
    });
  });
});

Flux basé sur les promesses

async function joinAndPublish() {
	const session = OT.initSession(apiKey, sessionId);

	try {
		await session.connect.promise(token);

		const publisher = await OT.initPublisher.promise('publisher', publisherOptions);

		await session.publish.promise(publisher);
	} catch (error) {
		console.error(error.name, error.message);
	}
}

API renvoyant directement un « Promise »

La migration de ces API peut s'effectuer en supprimant le gestionnaire de fin d'exécution et en attendant directement le résultat.

Espace de noms OT

Exemple :

try {
	const capability = await OT.checkScreenSharingCapability();

	if (!capability.supported) {
		console.warn('Screen sharing is not supported in this browser.');
		return;
	}

	const devices = await OT.getDevices();
	console.log(devices);
} catch (error) {
	console.error(error.name, error.message);
}

API de session

Les méthodes de session suivantes renvoient également directement des promesses :

• session.disconnect()
• session.disableForceMute()
• session.forceMuteStream(stream)
• session.forceMuteAll(excludedStreams)
• session.setEncryptionSecret(secret)
• session.setIceConfig(iceConfig)

API des éditeurs

Les méthodes Publisher suivantes renvoient également directement des promesses :

• publisher.publishCaptions(value)
• publisher.cycleVideo()
• publisher.setAudioSource(audioSource)
• publisher.setVideoSource(videoSourceId)
• publisher.setVideoContentHint(hint)
• publisher.setPreferredFrameRate(frameRate)
• publisher.setPreferredResolution(resolution)
• publisher.setMaxVideoBitrate(bitrateBps)
• publisher.setVideoBitratePreset(preset)
• publisher.setVideoMediaProcessorConnector(connector)
• publisher.setAudioMediaProcessorConnector(connector)

API pour les abonnés

Les méthodes « Subscriber » suivantes renvoient également des promesses directement :

• subscriber.subscribeToCaptions(value)
• subscriber.setPreferredFrameRate(frameRate)
• subscriber.setPreferredResolution(resolution)
• subscriber.setCaptionsTranslationLanguage(langCode)
• subscriber.setVideoMediaProcessorConnector(connector)
• subscriber.setAudioMediaProcessorConnector(connector)

API qui utilisent .promise

Certaines méthodes conservent leur valeur de retour d'origine afin que le code de chaînage existant continue de fonctionner. Utilisez la .promise une aide utile lorsque vous devez attendre la fin d'une opération.

Espace de noms OT

Aides de session

Assistants d'édition

Assistants pour les abonnés

Exemple :

try {
	await publisher.publishAudio.promise(false);
	await publisher.publishVideo.promise(true);

	const subscriber = await session.subscribe.promise(stream, 'subscriber', {
		insertMode: 'append',
		width: '100%',
		height: '100%'
	});

	await subscriber.subscribeToAudio.promise(true);
	await subscriber.setAudioVolume.promise(40);
} catch (error) {
	console.error(error.name, error.message);
}

Gestion des erreurs

Dans le code basé sur les callbacks, les erreurs sont généralement transmises en tant que premier argument au gestionnaire de fin d'exécution. Dans le code basé sur les promesses, ces mêmes échecs se manifestent sous la forme de promesses rejetées.

try {
	const stats = await subscriber.getStats();
	console.log(stats);
} catch (error) {
	console.error(error.name);
	console.error(error.message);
}

Cela facilite l'utilisation d'un seul try/catch bloc comprenant une séquence d'opérations liées entre elles.

Adoption progressive

Il n'est pas nécessaire de migrer l'intégralité de l'application en une seule fois. Voici l'approche recommandée :

1. Commencez par les flux de connexion, de publication et d'abonnement
2. Passer ensuite à la migration des aides à la modération et à la signalisation
3. Migrer en dernier le code de contrôle de l'éditeur et de l'abonné

La compatibilité avec les callbacks étant préservée, vous pouvez migrer un chemin de code à la fois.

Remarques sur la compatibilité

• OT.initSession() renvoie toujours un Session de manière synchrone.
• session.unpublish() et session.unsubscribe() restent des aides à la démolition immédiate.
• Les écouteurs d'événements tels que streamCreated, sessionDisconnectedet videoDisabled restent basés sur les événements.
• Si votre application doit prendre en charge d'anciennes versions du SDK, conservez la structure de rappel jusqu'à ce que tous les clients déployés aient été mis à jour vers une version incluant ces API « promise ».

Prochaines étapes

• Consultez le Référence sur les sessions JavaScript, Référence de l'éditeuret Référence de l'abonné pour plus de détails sur chaque méthode.
• Mettre à jour les tests de l'application afin qu'ils await des API basées sur des « promesses » plutôt que de s'appuyer sur l'exécution des callbacks.
• Préférer async les fonctions d'aide plutôt que les callbacks imbriqués lors de l'écriture de nouveau code.