Leitfaden zum Übergang von JS-SDK-Callbacks zu Promises

In dieser Anleitung wird erläutert, wie Sie bestehenden JavaScript-SDK-Code für die Vonage Video API von Callback-basierten Abschlusshandlern auf Promise-basierte APIs umstellen können.

Übersicht

Ab Version 2.35.1 unterstützt das JavaScript-SDK die Promise-basierte Ausführung in OT-Namespace-Dienstprogrammen sowie in einer Vielzahl von Session-, Publisher- und Subscriber-APIs. Damit haben Sie folgende Möglichkeiten:

• Ersetzen Sie verschachtelte Callbacks durch async / await
• Fehler mit Standardverfahren behandeln try / catch
• Die Abläufe beim Veröffentlichen und Abonnieren von Sequenzen übersichtlicher darstellen
• Führen Sie die Migration schrittweise durch, da die Callback-Signaturen aus Gründen der Abwärtskompatibilität weiterhin verfügbar bleiben.

Es gibt zwei Migrationsmuster:

• Direkte Rückgabe bei Versprechen: Verwenden Sie dies, wenn die Methode selbst ein Promise auflöst oder ablehnt. Beispiel: const devices = await OT.getDevices()
• .promise Helfer: Verwenden Sie dies, wenn die alte Methode weiterhin Session, Publisher, oder Subscriber, und die Promise-API wird für die Methode als .promise(...) Hilfsfunktion. Beispiel: await session.connect.promise(token)

Anmerkung: Ereignis-Listener ändern sich nicht. Verwenden Sie sie weiterhin. session.on(...), publisher.on(...)und subscriber.on(...) für asynchrone Ereignisse.

Was sich geändert hat

Die Umstellung auf Promisification erfolgte schrittweise:

• OT-Namespace-Dienstprogramme wie Gerätesuche, Überprüfung der Bildschirmfreigabefunktionen und Fehlermeldung
• Hilfsfunktionen für den Sitzungslebenszyklus und die Moderation
• Session.publish() und Session.subscribe()
• Publisher-Statistiken und APIs zur Publisher-Steuerung
• Abonnentenstatistiken und APIs zur Abonnentensteuerung

In der Praxis bedeutet dies, dass der Großteil des Codes für Abschluss-Handler in einem Web-Client nun mithilfe von Promises umgeschrieben werden kann.

Migrationsstrategie

1. Konvertieren Sie die Funktion, die Ihren Vonage Video API-Ablauf verwaltet, in async.
2. Ersetzen Sie die Abschluss-Handler durch await.
3. API-Aufrufe in try/catch.
4. Verwenden Sie ereignisgesteuerten Code als Ereignisse.
5. Verwenden Sie die .promise Form, wenn die alte Methode weiterhin ein Objekt für die Verkettung zurückgibt.

Typisches Vorher-Nachher-Muster

Callback-basierter Ablauf

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

Promise-basierter Ablauf

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

APIs, die direkt ein „Promise“ zurückgeben

Diese APIs lassen sich migrieren, indem man den Completion-Handler entfernt und direkt auf das Ergebnis wartet.

OT-Namensraum

Beispiel:

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

Session-APIs

Die folgenden Session-Methoden geben ebenfalls direkt Promises zurück:

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

Publisher-APIs

Die folgenden Publisher-Methoden geben ebenfalls direkt Promises zurück:

• 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)

Abonnenten-APIs

Die folgenden Subscriber-Methoden geben ebenfalls direkt Promises zurück:

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

APIs, die … verwenden .promise

Einige Methoden behalten ihren bisherigen Rückgabewert bei, sodass bestehender Code mit Kettenaufrufen weiterhin funktioniert. Verwenden Sie die .promise Eine Hilfe, wenn Sie auf den Abschluss warten müssen.

OT-Namensraum

Session-Helfer

Hilfsmittel für Verlage

Hilfsmittel für Abonnenten

Beispiel:

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

Fehlerbehandlung

In Callback-basiertem Code werden Fehler in der Regel als erstes Argument an den Completion-Handler übergeben. In Promise-basiertem Code werden dieselben Fehler als abgelehnte Promises zurückgegeben.

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

Dadurch lässt sich ein einziges try/catch Block für eine Abfolge zusammenhängender Vorgänge.

Schrittweise Einführung

Sie müssen nicht die gesamte Anwendung in einem Durchgang migrieren. Ein empfohlener Ansatz ist folgender:

1. Beginnen Sie mit den Abläufen „Verbindung herstellen“, „Veröffentlichen“ und „Abonnieren“
2. Als Nächstes die Moderations- und Signalisierungs-Helper migrieren
3. Den Steuerungscode für Publisher und Subscriber zuletzt migrieren

Da die Callback-Kompatibilität weiterhin gewährleistet ist, können Sie jeweils nur einen Codepfad auf einmal umstellen.

Hinweise zur Kompatibilität

• OT.initSession() gibt immer noch ein Session synchron.
• session.unpublish() und session.unsubscribe() bleiben weiterhin Helfer beim sofortigen Abbau.
• Ereignis-Listener wie beispielsweise streamCreated, sessionDisconnectedund videoDisabled bleiben ereignisgesteuert.
• Falls Ihre Anwendung ältere SDK-Versionen unterstützen muss, behalten Sie die Callback-Formular-Methode bei, bis alle bereitgestellten Clients auf eine Version aktualisiert wurden, die diese Promise-APIs enthält.

Nächste Schritte

• Überprüfen Sie die JavaScript-Sitzungsreferenz, Verlagsangabeund Abonnentenreferenz für methodenspezifische Einzelheiten.
• Die Anwendungstests so aktualisieren, dass sie await Promise-basierte APIs, anstatt sich auf die Ausführung von Callbacks zu verlassen.
• Bevorzugen async Beim Schreiben von neuem Code ziehe ich Hilfsfunktionen den verschachtelten Callbacks vor.