JS SDK：コールバックからPromiseへの移行ガイド

このガイドでは、既存のVonage Video API JavaScript SDKコードを、コールバックベースの完了ハンドラからPromiseベースのAPIへ移行する方法について説明します。

概要

バージョン 2.35.1 以降、JavaScript SDK では、OT ネームスペースのユーティリティおよび、Session、Publisher、Subscriber の幅広い API において、Promise ベースの完了処理がサポートされるようになりました。これにより、以下のことが可能になります：

• ネストしたコールバックを次のように置き換えてください async / await
• 標準的な方法でエラーを処理する try / catch
• パブリッシュ・サブスクライブのフローをより明確に整理する
• 後方互換性を確保するため、コールバックのシグネチャは引き続き利用可能であるため、段階的に移行してください

移行のパターンには2つあります：

• 直接約束のリターン: メソッド自体がプロミスを解決または拒否する場合にこれを使用します。例： const devices = await OT.getDevices()
• .promise ヘルパー: 従来のメソッドが依然として値を返す場合にこれを使用してください Session, Publisherあるいは Subscriber, そして、このメソッドではプロミス API が .promise(...) ヘルパー。例： await session.connect.promise(token)

注： イベントリスナーは変更されません。引き続きご利用ください session.on(...), publisher.on(...)そして subscriber.on(...) 非同期イベントの場合。

何が変わったのか

プロミシフィケーション作業は段階的に展開されました：

• デバイス検索、画面共有機能の確認、問題報告などのOTネームスペース関連ユーティリティ
• セッションのライフサイクルとモデレーションヘルパー
• Session.publish() そして Session.subscribe()
• パブリッシャーの統計情報とパブリッシャー制御API
• 登録者統計および登録者管理API

実際には、これはWebクライアント内の完了ハンドラのコードのほとんどを、プロミスを使って書き換えられるようになったことを意味します。

移行戦略

1. Vonage Video API フローを管理する関数を、以下の形式に変換してください。 async.
2. 完了ハンドラを以下に置き換えてください await.
3. API呼び出しを try/catch.
4. イベント駆動型のコードは、イベントとして保持してください。
5. を使用する。 .promise レガシーなメソッドがチェーン処理のために依然としてオブジェクトを返す場合。

よくある「ビフォー・アフター」のパターン

コールバックベースのフロー

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

プロミスベースのフロー

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

Promiseを直接返すAPI

これらのAPIは、コンプリートハンドラを削除し、結果を直接待機するようにすることで移行できます。

OT 名前空間

例

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

以下のSessionメソッドも、プロミスを直接返します：

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

パブリッシャーAPI

以下の Publisher メソッドも、プロミスそのものを直接返します：

• 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

以下の Subscriber メソッドも、直接 Promise を返します：

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

以下のAPIを使用する .promise

一部のメソッドは、従来の戻り値を保持しているため、既存のチェーン処理のコードは引き続き動作します。次の .promise 完了を待つ必要がある場合の補助ツール。

OT 名前空間

セッションヘルパー

パブリッシャー・ヘルパー

購読者向けサポート

例

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

エラー処理

コールバックベースのコードでは、通常、エラーはコンプリートハンドラの最初の引数として渡されます。プロミスベースのコードでは、同じ失敗がリジェクトされたプロミスとして表されます。

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

これにより、1つの try/catch 一連の関連する操作を行うためのブロック。

段階的な導入

Applications全体を一度に移行する必要はありません。推奨されるアプローチは以下の通りです：

1. 「接続」「公開」「購読」のフローから始めましょう
2. 次は、モデレーションおよびシグナリングのヘルパーを移行する
3. パブリッシャーおよびサブスクライバーの制御コードは最後に移行する

コールバックの互換性が維持されているため、コードパスを1つずつ移行することができます。

互換性に関する注意事項

• OT.initSession() それでも Session 同期的に。
• session.unpublish() そして session.unsubscribe() 引き続き、解体作業の即戦力として活躍しています。
• 次のようなイベントリスナーなど streamCreated, sessionDisconnectedそして videoDisabled イベント駆動型であり続ける。
• アプリケーションで古いバージョンのClient SDKをサポートする必要がある場合は、デプロイ済みのすべてのクライアントが、これらのPromise APIを含むバージョンに更新されるまで、コールバック形式を維持してください。

次のステップ

• 以下を確認してください JavaScript セッションのリファレンス, 出版社の参照情報そして 加入者番号 メソッドごとの詳細については。
• Applicationsのテストを更新して、それらが await コールバックの完了に依存するのではなく、プロミスベースのAPIを採用する。
• 「Prefer」 async 新しいコードを書く際は、ネストされたコールバックよりもヘルパー関数を使うようにする。