このページは Cloud Translation API によって翻訳されました。

カスタムウェブレシーバーに主要な機能を追加する

このページには、カスタムウェブレシーバアプリで使用できる機能のコードスニペットと説明が記載されています。

Web Receiver に付属の組み込みプレーヤー UI を表す cast-media-player 要素。
cast-media-player 要素のカスタム CSS 風のスタイル設定。background-image、splash-image、font-family などのさまざまな UI 要素のスタイルを設定します。
ウェブレシーバーフレームワークを読み込むためのスクリプト要素。
メッセージをインターセプトしてイベントを処理する JavaScript コード。
自動再生のキュー。
再生を構成するオプション。
Web Receiver コンテキストを設定するオプション。
Web Receiver アプリでサポートされているコマンドを設定するオプション。
ウェブレシーバーアプリケーションを開始する JavaScript 呼び出し。

アプリケーションの構成とオプション

アプリケーションを構成する

CastReceiverContext は、デベロッパーに公開される最も外側のクラスであり、基盤となるライブラリの読み込みを管理し、Web Receiver SDK の初期化を処理します。SDK は、アプリデベロッパーが CastReceiverOptions を通じて SDK を構成できるようにする API を提供します。これらの構成は、アプリの起動ごとに 1 回評価され、start の呼び出しでオプションのパラメータを設定するときに SDK に渡されます。

次の例は、送信者の接続がまだアクティブに接続されているかどうかを検出するデフォルトの動作をオーバーライドする方法を示しています。ウェブレシーバが maxInactivity 秒間送信側と通信できなかった場合、SENDER_DISCONNECTED イベントがディスパッチされます。次の構成では、このタイムアウトがオーバーライドされます。これは、IDLE 状態の接続された送信者がゼロの場合に、ウェブレシーバーアプリが Chrome リモートデバッガセッションを終了しないようにするため、問題のデバッグに役立ちます。

const context = cast.framework.CastReceiverContext.getInstance();
const options = new cast.framework.CastReceiverOptions();
options.maxInactivity = 3600; // Development only
context.start(options);

プレーヤーを構成する

コンテンツを読み込む際、ウェブレシーバ SDK は cast.framework.PlaybackConfig を使用して、DRM 情報、再試行構成、リクエストハンドラなどの再生変数を構成する方法を提供します。この情報は PlayerManager によって処理され、プレーヤーの作成時に評価されます。プレーヤーは、新しい読み込みが Web Receiver SDK に渡されるたびに作成されます。プレーヤーの作成後に PlaybackConfig に変更を加えた場合、その変更は次のコンテンツ読み込み時に評価されます。SDK には、PlaybackConfig を変更するための次のメソッドが用意されています。

CastReceiverOptions.playbackConfig CastReceiverContext の初期化時にデフォルトの構成オプションをオーバーライドします。
PlayerManager.getPlaybackConfig(): 現在の構成を取得します。
PlayerManager.setPlaybackConfig() 現在の構成をオーバーライドします。この設定は、後続のすべての読み込みに適用されるか、再度オーバーライドされるまで適用されます。
PlayerManager.setMediaPlaybackInfoHandler() を使用して、現在の構成に加えて、読み込まれるメディアアイテムにのみ追加の構成を適用します。ハンドラは、プレーヤーの作成直前に呼び出されます。ここで行った変更は永続的ではなく、getPlaybackConfig() へのクエリには含まれません。次のメディアアイテムが読み込まれると、このハンドラが再度呼び出されます。

次の例は、CastReceiverContext を初期化する際に PlaybackConfig を設定する方法を示しています。この構成は、マニフェストを取得するための送信リクエストをオーバーライドします。ハンドラは、CORS Access-Control リクエストが Cookie や認可ヘッダーなどの認証情報を使用して行われるように指定します。

const playbackConfig = new cast.framework.PlaybackConfig();
playbackConfig.manifestRequestHandler = requestInfo => {
  requestInfo.withCredentials = true;
};
context.start({playbackConfig: playbackConfig});

次の例は、PlayerManager で提供されるゲッターとセッターを使用して PlaybackConfig をオーバーライドする方法を示しています。この設定では、1 つのセグメントが読み込まれた後にコンテンツの再生を再開するようにプレーヤーを構成します。

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
const playbackConfig = (Object.assign(
            new cast.framework.PlaybackConfig(), playerManager.getPlaybackConfig()));
playbackConfig.autoResumeNumberOfSegments = 1;
playerManager.setPlaybackConfig(playbackConfig);

次の例は、メディア再生情報ハンドラを使用して、特定の読み込みリクエストの PlaybackConfig をオーバーライドする方法を示しています。ハンドラは、アプリケーション実装メソッド getLicenseUrlForMedia を呼び出して、現在のアイテムの contentId から licenseUrl を取得します。

playerManager.setMediaPlaybackInfoHandler((loadRequestData, playbackConfig) => {
  const mediaInformation = loadRequestData.media;
  playbackConfig.licenseUrl = getLicenseUrlForMedia(mediaInformation.contentId);

  return playbackConfig;
});

イベントリスナー

Web Receiver SDK を使用すると、Web Receiver アプリでプレーヤーイベントを処理できます。イベントリスナーは、リスナーをトリガーするイベントを指定する cast.framework.events.EventType パラメータ（またはこれらのパラメータの配列）を受け取ります。デバッグに役立つ cast.framework.events.EventType の事前構成済み配列は、cast.framework.events.category にあります。イベントパラメータは、イベントに関する追加情報を提供します。

たとえば、mediaStatus の変更がブロードキャストされるタイミングを知りたい場合は、次のロジックを使用してイベントを処理できます。

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
playerManager.addEventListener(
    cast.framework.events.EventType.MEDIA_STATUS, (event) => {
      // Write your own event handling code, for example
      // using the event.mediaStatus value
});

メッセージの傍受

Web Receiver SDK を使用すると、Web Receiver アプリでメッセージをインターセプトし、それらのメッセージに対してカスタムコードを実行できます。メッセージインターセプタは、インターセプトするメッセージのタイプを指定する cast.framework.messages.MessageType パラメータを受け取ります。

インターセプタは、変更されたリクエストまたは変更されたリクエスト値で解決される Promise を返す必要があります。null を返すと、デフォルトのメッセージハンドラが呼び出されなくなります。詳しくは、メディアの読み込みをご覧ください。

たとえば、読み込みリクエストのデータを変更する場合は、次のロジックを使用してインターセプトし、変更できます。

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_FAILED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      if (!loadRequestData.media.entity) {
        return loadRequestData;
      }

      return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
                                          loadRequestData.credentials)
        .then(asset => {
          if (!asset) {
            throw cast.framework.messages.ErrorReason.INVALID_REQUEST;
          }

          loadRequestData.media.contentUrl = asset.url;
          loadRequestData.media.metadata = asset.metadata;
          loadRequestData.media.tracks = asset.tracks;
          return loadRequestData;
        }).catch(reason => {
          error.reason = reason; // cast.framework.messages.ErrorReason
          return error;
        });
    });

context.start();

エラー処理

メッセージインターセプタでエラーが発生した場合、ウェブレシーバーアプリは適切な cast.framework.messages.ErrorType と cast.framework.messages.ErrorReason を返す必要があります。

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_CANCELLED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      ...

      return fetchAssetAndAuth(loadRequestData.media.entity,
                               loadRequestData.credentials)
        .then(asset => {
          ...
          return loadRequestData;
        }).catch(reason => {
          error.reason = reason; // cast.framework.messages.ErrorReason
          return error;
        });
    });

メッセージのインターセプトとイベントリスナー

メッセージインターセプトとイベントリスナーの主な違いは次のとおりです。

イベントリスナーではリクエストデータを変更できません。
イベントリスナーは、分析やカスタム関数をトリガーするのに最適です。

playerManager.addEventListener(cast.framework.events.category.CORE,
    event => {
        console.log(event);
    });

メッセージのインターセプトを使用すると、メッセージをリッスンしてインターセプトし、リクエストデータ自体を変更できます。
メッセージのインターセプトは、リクエストデータに関するカスタムロジックを処理する場合に最適です。

メディアの読み込み

MediaInformation は、cast.framework.messages.MessageType.LOAD メッセージでメディアを読み込むための多数のプロパティ（entity、contentUrl、contentId など）を提供します。

entity は、送信側アプリと受信側アプリの両方の実装で使用することが推奨されるプロパティです。このプロパティは、プレイリストまたはメディアコンテンツのいずれかであるディープリンク URL です。アプリケーションはこの URL を解析し、他の 2 つのフィールドのうち少なくとも 1 つに値を入力する必要があります。
contentUrl は、プレーヤーがコンテンツの読み込みに使用する再生可能な URL に対応します。たとえば、この URL は DASH マニフェストを指す可能性があります。
contentId には、再生可能なコンテンツの URL（contentUrl プロパティの URL と同様）または読み込まれるコンテンツや再生リストの一意の識別子を指定できます。このプロパティを識別子として使用する場合は、アプリで contentUrl に再生可能な URL を入力する必要があります。

entity を使用して実際の ID またはキーパラメータを保存し、contentUrl を使用してメディアの URL を保存することをおすすめします。次のスニペットは、entity が LOAD リクエストに存在し、再生可能な contentUrl が取得される例を示しています。

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      ...

      if (!loadRequestData.media.entity) {
        // Copy the value from contentId for legacy reasons if needed
        loadRequestData.media.entity = loadRequestData.media.contentId;
      }

      return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
                                          loadRequestData.credentials)
        .then(asset => {
          loadRequestData.media.contentUrl = asset.url;
          ...
          return loadRequestData;
        });
    });

デバイスの機能

getDeviceCapabilities メソッドは、接続されている Cast デバイスと、それに接続されている動画デバイスまたは音声デバイスに関するデバイス情報を提供します。getDeviceCapabilities メソッドは、Google アシスタント、Bluetooth、接続されたディスプレイとオーディオデバイスのサポート情報を提供します。

このメソッドは、指定された列挙型のいずれかを渡してクエリを実行し、その列挙型のデバイス機能を取得できるオブジェクトを返します。列挙型は cast.framework.system.DeviceCapabilities で定義されています。

この例では、それぞれ IS_HDR_SUPPORTED キーと IS_DV_SUPPORTED キーを使用して、Web レシーバデバイスが HDR とドルビービジョン（DV）を再生できるかどうかを確認します。

const context = cast.framework.CastReceiverContext.getInstance();
context.addEventListener(cast.framework.system.EventType.READY, () => {
  const deviceCapabilities = context.getDeviceCapabilities();
  if (deviceCapabilities &&
      deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED]) {
    // Write your own event handling code, for example
    // using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED] value
  }
  if (deviceCapabilities &&
      deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED]) {
    // Write your own event handling code, for example
    // using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED] value
  }
});
context.start();

ユーザー操作の処理

ユーザーは、送信側アプリケーション（ウェブ、Android、iOS）、アシスタント対応デバイスの音声コマンド、スマートディスプレイのタッチコントロール、Android TV デバイスのリモコンを使用して、ウェブレシーバアプリケーションを操作できます。Cast SDK には、ウェブレシーバーアプリがこれらの操作を処理し、ユーザーアクションの状態を通じてアプリケーション UI を更新し、必要に応じて変更を送信してバックエンドサービスを更新できるようにするさまざまな API が用意されています。

サポートされているメディアコマンド

UI コントロールの状態は、iOS と Android の送信側拡張コントローラ、タッチデバイスで実行されるレシーバーアプリとリモコンアプリ、Android TV デバイスのレシーバーアプリの MediaStatus.supportedMediaCommands によって制御されます。プロパティで特定のビット単位の Command が有効になっている場合、そのアクションに関連するボタンが有効になります。値が設定されていない場合、ボタンは無効になります。これらの値は、ウェブレシーバで次のように変更できます。

PlayerManager.setSupportedMediaCommands を使用して特定の Commands を設定する
addSupportedMediaCommands を使用して新しいコマンドを追加する
removeSupportedMediaCommands を使用して既存のコマンドを削除します。

playerManager.setSupportedMediaCommands(cast.framework.messages.Command.SEEK |
  cast.framework.messages.Command.PAUSE);

受信側が更新された MediaStatus を準備するときに、supportedMediaCommands プロパティに変更を含めます。ステータスがブロードキャストされると、接続されている送信側アプリは、UI のボタンを適宜更新します。

サポートされているメディアコマンドとタッチデバイスの詳細については、Accessing UI controls ガイドをご覧ください。

ユーザーアクションの状態を管理する

ユーザーが UI を操作したり、音声コマンドを送信したりすると、コンテンツの再生と、再生中のアイテムに関連するプロパティを制御できます。再生を制御するリクエストは、SDK によって自動的に処理されます。LIKE コマンドなど、現在再生中のアイテムのプロパティを変更するリクエストは、レシーバアプリケーションで処理する必要があります。SDK には、これらのタイプのリクエストを処理するための一連の API が用意されています。これらのリクエストをサポートするには、次の操作を行う必要があります。

メディアアイテムを読み込むときに、ユーザーの設定で MediaInformation userActionStates を設定します。
USER_ACTION メッセージをインターセプトし、リクエストされたアクションを特定します。
MediaInformation UserActionState を更新して UI を更新します。

次のスニペットは、LOAD リクエストをインターセプトし、LoadRequestData の MediaInformation を入力します。この場合、ユーザーは読み込まれているコンテンツを気に入っています。

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      const userActionLike = new cast.framework.messages.UserActionState(
          cast.framework.messages.UserAction.LIKE);
      loadRequestData.media.userActionStates = [userActionLike];

      return loadRequestData;
    });

次のスニペットは、USER_ACTION メッセージをインターセプトし、リクエストされた変更でバックエンドを呼び出す処理を行います。その後、呼び出しを行ってレシーバーの UserActionState を更新します。

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.USER_ACTION,
  (userActionRequestData) => {
    // Obtain the media information of the current content to associate the action to.
    let mediaInfo = playerManager.getMediaInformation();

    // If there is no media info return an error and ignore the request.
    if (!mediaInfo) {
        console.error('Not playing media, user action is not supported');
        return new cast.framework.messages.ErrorData(messages.ErrorType.BAD_REQUEST);
    }

    // Reach out to backend services to store user action modifications. See sample below.
    return sendUserAction(userActionRequestData, mediaInfo)

    // Upon response from the backend, update the client's UserActionState.
    .then(backendResponse => updateUserActionStates(backendResponse))

    // If any errors occurred in the backend return them to the cast receiver.
    .catch((error) => {
      console.error(error);
      return error;
    });
});

次のスニペットは、バックエンドサービスへの呼び出しをシミュレートします。この関数は UserActionRequestData をチェックして、ユーザーがリクエストした変更の種類を確認し、アクションがバックエンドでサポートされている場合にのみネットワーク呼び出しを行います。

function sendUserAction(userActionRequestData, mediaInfo) {
  return new Promise((resolve, reject) => {
    switch (userActionRequestData.userAction) {
      // Handle user action changes supported by the backend.
      case cast.framework.messages.UserAction.LIKE:
      case cast.framework.messages.UserAction.DISLIKE:
      case cast.framework.messages.UserAction.FOLLOW:
      case cast.framework.messages.UserAction.UNFOLLOW:
      case cast.framework.messages.UserAction.FLAG:
      case cast.framework.messages.UserAction.SKIP_AD:
        let backendResponse = {userActionRequestData: userActionRequestData, mediaInfo: mediaInfo};
        setTimeout(() => {resolve(backendResponse)}, 1000);
        break;
      // Reject all other user action changes.
      default:
        reject(
          new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType.INVALID_REQUEST));
    }
  });
}

次のスニペットは、UserActionRequestData を取得し、MediaInformation から UserActionState を追加または削除します。MediaInformation の UserActionState を更新すると、リクエストされたアクションに関連付けられているボタンの状態が変更されます。この変更は、スマートディスプレイのコントロール UI、リモコンアプリ、Android TV UI に反映されます。また、送信 MediaStatus メッセージを介してブロードキャストされ、iOS と Android の送信側の展開されたコントローラの UI を更新します。

function updateUserActionStates(backendResponse) {
  // Unwrap the backend response.
  let mediaInfo = backendResponse.mediaInfo;
  let userActionRequestData = backendResponse.userActionRequestData;

  // If the current item playing has changed, don't update the UserActionState for the current item.
  if (playerManager.getMediaInformation().entity !== mediaInfo.entity) {
    return;
  }

  // Check for existing userActionStates in the MediaInformation.
  // If none, initialize a new array to populate states with.
  let userActionStates = mediaInfo.userActionStates || [];

  // Locate the index of the UserActionState that will be updated in the userActionStates array.
  let index = userActionStates.findIndex((currUserActionState) => {
    return currUserActionState.userAction == userActionRequestData.userAction;
  });

  if (userActionRequestData.clear) {
    // Remove the user action state from the array if cleared.
    if (index >= 0) {
      userActionStates.splice(index, 1);
    }
    else {
      console.warn("Could not find UserActionState to remove in MediaInformation");
    }
  } else {
    // Add the UserActionState to the array if enabled.
    userActionStates.push(
      new cast.framework.messages.UserActionState(userActionRequestData.userAction));
  }

  // Update the UserActionState array and set the new MediaInformation
  mediaInfo.userActionStates = userActionStates;
  playerManager.setMediaInformation(mediaInfo, true);
  return;
}

音声コマンド

現在、アシスタント対応デバイスの Web Receiver SDK でサポートされているメディアコマンドは次のとおりです。これらのコマンドのデフォルト実装は cast.framework.PlayerManager にあります。

コマンド	説明
Play	一時停止状態から再生を開始または再開します。
一時停止	現在再生中のコンテンツを一時停止します。
前へ	メディアキュー内の前のメディア項目にスキップします。
次へ	メディアキューの次のメディア項目にスキップします。
停止	現在再生中のメディアを停止します。
リピートなし	キュー内の最後のアイテムの再生が完了したら、キュー内のメディアアイテムの繰り返しを無効にします。
1 曲リピート	現在再生中のメディアを無期限に繰り返します。
全曲リピート	キュー内の最後のアイテムが再生されたら、キュー内のすべてのアイテムを繰り返します。
すべてリピートとシャッフル	キュー内の最後のアイテムの再生が完了したら、キューをシャッフルして、キュー内のすべてのアイテムを繰り返します。
シャッフル	メディアキュー内のメディアアイテムをシャッフルします。注: `LOAD` メッセージの `loadRequestData` で `shuffle` フラグが設定されている場合は、再生前にメディアをシャッフルすることもできます。
字幕のオン / オフ	メディアの字幕を有効 / 無効にします。言語ごとに有効 / 無効にすることもできます。
絶対時間にシークする	指定された絶対時間にジャンプします。
現在の時刻を基準とした相対時刻にシークする	現在の再生時間から指定した時間だけ前後にスキップします。
もう一度プレイ	現在再生中のメディアを再開するか、現在再生中のメディアがない場合は最後に再生したメディアアイテムを再生します。
再生速度を設定する	メディアの再生レートを変更します。これはデフォルトで処理されるはずです。`SET_PLAYBACK_RATE` メッセージインターセプタを使用すると、受信レートリクエストをオーバーライドできます。

音声でサポートされているメディアコマンド

音声コマンドによってアシスタント対応デバイスでメディアコマンドがトリガーされないようにするには、まずサポートする予定のサポート対象のメディアコマンドを設定する必要があります。次に、CastReceiverOptions.enforceSupportedCommands プロパティを有効にして、これらのコマンドを適用する必要があります。Cast SDK 送信側とタッチ対応デバイスの UI が、これらの設定を反映するように変更されます。フラグが有効になっていない場合、受信した音声コマンドが実行されます。

たとえば、送信側アプリとタッチ対応デバイスからの PAUSE を許可する場合は、それらの設定を反映するように受信側も構成する必要があります。設定すると、サポートされているコマンドのリストに含まれていない音声コマンドはすべて破棄されます。

次の例では、CastReceiverContext の開始時に CastReceiverOptions を指定しています。PAUSE コマンドのサポートを追加し、プレーヤーがそのコマンドのみをサポートするように強制しました。音声コマンドが SEEK などの別のオペレーションをリクエストした場合、拒否されるようになります。コマンドがまだサポートされていないことをユーザーに通知します。

const context = cast.framework.CastReceiverContext.getInstance();

context.start({
  enforceSupportedCommands: true,
  supportedCommands: cast.framework.messages.Command.PAUSE
});

制限するコマンドごとに個別のロジックを適用できます。enforceSupportedCommands フラグを削除し、制限するコマンドごとに、受信メッセージをインターセプトできます。ここでは、SDK によって提供されたリクエストをインターセプトし、アシスタント対応デバイスに発行された SEEK コマンドが Web レシーバアプリケーションでシークをトリガーしないようにします。

アプリがサポートしていないメディアコマンドについては、NOT_SUPPORTED などの適切なエラー理由を返します。

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.SEEK,
  seekData => {
    // Block seeking if the SEEK supported media command is disabled
    if (!(playerManager.getSupportedMediaCommands() & cast.framework.messages.Command.SEEK)) {
      let e = new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType
      .INVALID_REQUEST);
      e.reason = cast.framework.messages.ErrorReason.NOT_SUPPORTED;
      return e;
    }

    return seekData;
  });

音声アクティビティからのバックグラウンド処理

ユーザーの発言をリッスンしたり、応答したりするなどのアシスタントアクティビティにより、Cast プラットフォームがアプリの音声をバックグラウンドに移行した場合、アクティビティの開始時に NOT_IN_FOCUS の FocusState メッセージがウェブレシーバーアプリに送信されます。アクティビティが終了すると、IN_FOCUS を含む別のメッセージが送信されます。アプリケーションと再生中のメディアによっては、メッセージタイプ FOCUS_STATE をインターセプトして、FocusState が NOT_IN_FOCUS のときにメディアを一時停止することが望ましい場合があります。

たとえば、Google アシスタントがユーザーのクエリに応答している場合は、オーディオブックの再生を一時停止するのが望ましいユーザーエクスペリエンスです。

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.FOCUS_STATE,
  focusStateRequestData => {
    // Pause content when the app is out of focus. Resume when focus is restored.
    if (focusStateRequestData.state == cast.framework.messages.FocusState.NOT_IN_FOCUS) {
      playerManager.pause();
    } else {
      playerManager.play();
    }

    return focusStateRequestData;
  });

音声で指定された字幕の言語

ユーザーが字幕の言語を明示的に指定しない場合、字幕に使用される言語は、コマンドが発話された言語と同じになります。このようなシナリオでは、受信メッセージの isSuggestedLanguage パラメータは、関連付けられた言語がユーザーによって提案されたか、明示的にリクエストされたかを示します。

たとえば、「OK Google, 字幕をオンにして」というコマンドでは、コマンドが話された言語から言語が推測されるため、isSuggestedLanguage は true に設定されます。「OK Google, 英語の字幕をオンにして」のように言語が明示的にリクエストされた場合、isSuggestedLanguage は false に設定されます。

メタデータと音声キャスト

音声コマンドはデフォルトで Web レシーバによって処理されますが、コンテンツのメタデータが完全かつ正確であることを確認する必要があります。これにより、アシスタントが音声コマンドを適切に処理し、Google Home アプリや Google Home Hub などのスマートディスプレイといった新しいタイプのインターフェースでメタデータが適切に表示されるようになります。

ストリーミング転送

セッションの状態を保持することは、ストリーム転送の基本です。ストリーム転送では、音声コマンド、Google Home アプリ、スマートディスプレイを使用して、既存の音声ストリームと動画ストリームをデバイス間で移動できます。メディアの再生が 1 つのデバイス（ソース）で停止し、別のデバイス（宛先）で続行されます。最新のファームウェアを搭載した Cast デバイスは、ストリーム転送の転送元または転送先として機能します。

ストリーム転送のイベントフローは次のとおりです。

ソースデバイス:
1. メディアの再生が停止します。
2. Web Receiver アプリケーションは、現在のメディアの状態を保存するコマンドを受け取ります。
3. ウェブレシーバーアプリケーションがシャットダウンされます。
移行先のデバイスで、次の操作を行います。
1. ウェブレシーバーアプリケーションが読み込まれます。
2. Web レシーバーアプリケーションは、保存されたメディアの状態を復元するコマンドを受け取ります。
3. メディアの再生が再開されます。

メディアの状態の要素には次のものがあります。

曲、動画、メディアアイテムの特定の位置またはタイムスタンプ。
より大きなキュー（プレイリストやアーティストラジオなど）での位置。
認証されたユーザー。
再生状態（再生中、一時停止など）。

ストリーム転送を有効にする

ウェブレシーバーにストリーム転送を実装するには:

STREAM_TRANSFER コマンドを使用して supportedMediaCommands を更新します。

playerManager.addSupportedMediaCommands(
cast.framework.messages.Command.STREAM_TRANSFER, true);

必要に応じて、セッション状態の保持で説明されているように、SESSION_STATE メッセージインターセプタと RESUME_SESSION メッセージインターセプタをオーバーライドします。カスタムデータをセッションスナップショットの一部として保存する必要がある場合にのみ、これらをオーバーライドします。それ以外の場合は、セッション状態を保持するためのデフォルトの実装でストリーム転送がサポートされます。

セッションの状態を保持する

Web Receiver SDK は、現在のメディアステータスのスナップショットを取得し、ステータスを読み込みリクエストに変換して、読み込みリクエストでセッションを再開することで、セッションの状態を維持する Web Receiver アプリのデフォルト実装を提供します。

必要に応じて、Web レシーバによって生成された読み込みリクエストは SESSION_STATE メッセージインターセプタでオーバーライドできます。読み込みリクエストにカスタムデータを追加する場合は、loadRequestData.customData に入れることをおすすめします。

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.SESSION_STATE,
    function (sessionState) {
        // Override sessionState.loadRequestData if needed.
        const newCredentials = updateCredentials_(sessionState.loadRequestData.credentials);
        sessionState.loadRequestData.credentials = newCredentials;

        // Add custom data if needed.
        sessionState.loadRequestData.customData = {
            'membership': 'PREMIUM'
        };

        return sessionState;
    });

カスタムデータは、RESUME_SESSION メッセージインターセプタの loadRequestData.customData から取得できます。

let cred_ = null;
let membership_ = null;

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.RESUME_SESSION,
    function (resumeSessionRequest) {
        let sessionState = resumeSessionRequest.sessionState;

        // Modify sessionState.loadRequestData if needed.
        cred_ = sessionState.loadRequestData.credentials;

        // Retrieve custom data.
        membership_ = sessionState.loadRequestData.customData.membership;

        return resumeSessionRequest;
    });

コンテンツのプリロード

Web レシーバは、キュー内の現在の再生アイテムの後にメディアアイテムをプリロードすることをサポートしています。

プリロードオペレーションでは、今後のアイテムの複数のセグメントが事前にダウンロードされます。この指定は、QueueItem オブジェクトの preloadTime 値で行われます（指定がない場合はデフォルトで 20 秒）。この時間は、現在再生中のアイテムの終了を基準とした秒数で表されます。正の値のみが有効です。たとえば、値が 10 秒の場合、このアイテムは前のアイテムが終了する 10 秒前にプリロードされます。プリロードにかかる時間が currentItem の残り時間よりも長い場合、プリロードはできるだけ早く行われます。したがって、queueItem に非常に大きなプリロード値を指定すると、現在のアイテムを再生するたびに次のアイテムをプリロードする効果が得られます。ただし、この値は現在再生中のアイテムの帯域幅とストリーミングパフォーマンスに影響する可能性があるため、この設定と選択はデベロッパーに任されています。

プリロードは、デフォルトで HLS、DASH、Smooth ストリーミングコンテンツで機能します。

MP3 などの通常の MP4 動画ファイルと音声ファイルは、キャストデバイスが 1 つのメディア要素のみをサポートし、既存のコンテンツアイテムが再生されている間はプリロードに使用できないため、プリロードされません。

カスタムメッセージ

メッセージ交換は、ウェブレシーバーアプリケーションの主要なインタラクション方法です。

送信者は、送信者が実行されているプラットフォーム（Android、iOS、ウェブ）の送信者 API を使用して、ウェブレシーバにメッセージを発行します。イベントリスナーに渡されるイベントオブジェクト（メッセージの具現化）には、データが特定のイベントタイプのプロパティを取得するデータ要素（event.data）があります。

ウェブレシーバーアプリケーションは、指定された名前空間でメッセージをリッスンすることを選択できます。これにより、ウェブレシーバーアプリケーションがその名前空間プロトコルをサポートしていることになります。その名前空間で通信を希望する接続された送信者は、適切なプロトコルを使用する必要があります。

すべての名前空間は文字列で定義され、「urn:x-cast:」で始まり、その後に任意の文字列が続きます。（「urn:x-cast:com.example.cast.mynamespace」など）。

接続された送信者からのカスタムメッセージをリッスンする Web レシーバのコードスニペットは次のとおりです。

const context = cast.framework.CastReceiverContext.getInstance();

const CUSTOM_CHANNEL = 'urn:x-cast:com.example.cast.mynamespace';
context.addCustomMessageListener(CUSTOM_CHANNEL, function(customEvent) {
  // handle customEvent.
});

context.start();

同様に、ウェブレシーバーアプリケーションは、接続されている送信者にメッセージを送信することで、ウェブレシーバーの状態を送信者に通知できます。ウェブレシーバアプリケーションは、CastReceiverContext の sendCustomMessage(namespace, senderId, message) を使用してメッセージを送信できます。ウェブレシーバは、受信したメッセージへの応答として、またはアプリケーションの状態の変化により、個々の送信者にメッセージを送信できます。ポイントツーポイントメッセージング（64 KB の制限あり）以外にも、ウェブレシーバは接続されているすべての送信者にメッセージをブロードキャストできます。

オーディオ機器へのキャスト

音声のみの再生のサポートについては、オーディオデバイス向け Google Cast のガイドをご覧ください。

Android TV

このセクションでは、Google ウェブレシーバが入力内容を再生として使用する方法と、Android TV の互換性について説明します。

アプリケーションとリモコンの統合

Android TV デバイスで実行されている Google Web Receiver は、デバイスの制御入力（ハンドヘルドリモコンなど）からの入力を、メディア再生メッセージで説明されているように、urn:x-cast:com.google.cast.media 名前空間で定義されたメディア再生メッセージとして変換します。Android TV のコントロール入力から基本的な再生コントロールを可能にするために、アプリはアプリのメディア再生を制御するこれらのメッセージをサポートする必要があります。

Android TV の互換性に関するガイドライン

Android TV との互換性を確保するために、推奨事項と避けるべき一般的な落とし穴を以下に示します。

ユーザーエージェント文字列には「Android」と「CrKey」の両方が含まれています。一部のサイトでは、「Android」ラベルが検出されるとモバイル専用サイトにリダイレクトされることがあります。ユーザーエージェント文字列の「Android」が常にモバイルユーザーを示すとは限りません。
Android のメディアスタックは、データを取得する際に透過的な GZIP を使用する場合があります。メディアデータが Accept-Encoding: gzip に対応できることを確認します。
Android TV の HTML5 メディアイベントは Chromecast と異なるタイミングでトリガーされるため、Chromecast では隠されていた問題が明らかになることがあります。
メディアを更新するときは、<audio>/<video> 要素によって発生するメディア関連のイベント（timeupdate、pause、waiting など）を使用します。progress、suspend、stalled などのネットワーク関連のイベントは、プラットフォームに依存する傾向があるため、使用しないでください。レシーバでのメディアイベントの処理について詳しくは、メディアイベントをご覧ください。
受信側サイトの HTTPS 証明書を構成する際は、中間 CA 証明書を必ず含めてください。Qualsys SSL テストページで、サイトの信頼できる認証パスに「extra download」とラベル付けされた CA 証明書が含まれている場合、Android ベースのプラットフォームで読み込まれない可能性があることを確認してください。
Chromecast は 720p のグラフィックプレーンでレシーバーページを表示しますが、Android TV などの他の Cast プラットフォームでは最大 1080p でページを表示できます。レシーバーページがさまざまな解像度で適切にスケーリングされるようにします。

カスタムのウェブレシーバー

Shaka プレーヤーの移行における HLS