カスタム ウェブ レシーバーにコア機能を追加する

このページでは、Custom Web Receiver アプリで使用できる機能のコード スニペットと説明について説明します。

注: 次の手順を行うことをおすすめします。

• Codelab ウェブキャスト レシーバーの Codelab チュートリアル - Google Cast SDK を使用して動画キャストを受信できる Cast 対応レシーバー アプリの作成方法を順を追って説明します。
• CastReceiver サンプルアプリ（GitHub） - UX ガイドラインと設計チェックリストに沿って、このリファレンス サンプルアプリを実行、操作、表示します。

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

注: プレーヤーのすべての UI 状態とスタイルを処理するため、cast-media-player HTML 要素を使用することを強くおすすめします。

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

CastReceiverContext は、デベロッパーに公開される最も外側のクラスで、基盤となるライブラリの読み込みを管理し、Web Receiver SDK の初期化を処理します。

Web Receiver API で送信者が切断されたことを検出すると、SENDER_DISCONNECTED イベントが発生します。ウェブ レシーバが maxInactivity 秒の間記述されているとおりに送信者と通信できない場合も、SENDER_DISCONNECTED イベントが発生します。開発中は、Chrome リモート デバッガでアプリをデバッグするときにウェブレシーバー アプリが閉じないように、maxInactivity に大きな値を設定することをおすすめします。

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

ただし、公開ウェブレシーバ アプリケーションの場合は、maxInactivity を設定せずに、デフォルト値を使用することをおすすめします。Web Receiver オプションは、アプリケーション内で一度だけ設定されることに注意してください。

もう一つの構成は cast.framework.PlaybackConfig です。次のように設定できます。

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

この構成は各コンテンツの再生に影響を与え、基本的にオーバーライド動作を提供します。デベロッパーがオーバーライドできる動作のリストについては、cast.framework.PlaybackConfig の定義をご覧ください。コンテンツ間で構成を変更するには、PlayerManager を使用して現在の playbackConfig を取得し、オーバーライドを変更または追加して、playbackConfig を次のようにリセットします。

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

PlaybackConfig がオーバーライドされていない場合、getPlaybackConfig() は null オブジェクトを返します。PlaybackConfig that のプロパティはすべて undefined でデフォルト値を使用します。

イベント リスナー

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

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

注: ウェブ レシーバ フレームワークは、送信者がフレームワークから接続または切断すると自動的に追跡します。独自のウェブ レシーバ ロジックで明示的な SENDER_DISCONNECTED イベント リスナーは必要ありません。

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 を返すと、デフォルトのメッセージ ハンドラは呼び出されません。詳しくは、メディアを読み込むをご覧ください。

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

注意: LOAD インターセプタの LoadRequestData の queueData プロパティを追加または変更しないでください。queueData はすでに読み取られてキューに適用されているため、再生には影響しません。詳細については、キューガイドをご覧ください。

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

エラー処理

メッセージ インターセプトでエラーが発生した場合、Web Receiver アプリから適切な 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;
        });
    });

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

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

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

注: イベント リスナーは、CORE、DEBUG、FINE の列挙型を使用して、包括性のないイベントをリッスンすることもできます。

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

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

メディアの読み込み

MediaInformation には、entity、contentUrl、contentId など、cast.framework.messages.MessageType.LOAD メッセージでメディアを読み込むためのさまざまなプロパティが用意されています。

entity は、送信側アプリと受信側アプリの両方の実装で使用が推奨されるプロパティです。ディープリンク URL は、再生リストまたは特定のメディア コンテンツのいずれかです。

contentUrl は再生可能な URL 用に設計されており、利用可能になると使用できます。

contentId のサポートは終了しました。値がカスタム URL のメディア URL、実際の ID、キーパラメータのいずれであるかがあいまいなためです。

entity を使用して実際の ID またはキーのパラメータを保存し、contentUrl を使用してメディアの URL を取得することをおすすめします。例として、LOAD リクエストに entity が存在し、再生可能な 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 メソッドは、接続されたキャスト デバイスと、それに接続された動画またはオーディオ デバイスのデバイス情報を提供します。getDeviceCapabilities メソッドは、Google アシスタント、Bluetooth、接続されたディスプレイ、オーディオ デバイスのサポート情報を提供します。

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

この例では、ウェブレシーバー デバイスが IS_HDR_SUPPORTED キー、IS_DV_SUPPORTED キーでそれぞれ 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 センダー拡張コントローラの MediaStatus.supportedMediaCommands、タッチデバイスで実行されているレシーバー アプリとリモコンアプリ、Android TV デバイスのレシーバー アプリによって駆動されます。特定のビット単位の Command がプロパティで有効になっている場合、そのアクションに関連するボタンが有効になります。値が設定されていない場合、ボタンは無効になります。これらの値は、次の方法で Web Receiver で変更できます。

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

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

レシーバーは、更新された MediaStatus を準備すると、supportedMediaCommands プロパティの変更を含めます。ステータスがブロードキャストされると、接続された送信者アプリはそれに応じて UI のボタンを更新します。

注: supportedMediaCommands に変更を加えても、表示されるボタンのタイプは変更されません。これらは、送信側のアプリ（iOS、Android）と受信側の Controls API で直接設定します。そのような変更を推進するために supportedMediaCommands を使用する唯一の例外は、スマートディスプレイ デバイスのホーム画面に表示されるメディア再生カードです。

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

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

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

• USER_ACTION メッセージをインターセプトし、リクエストされたアクションを確認します。
• MediaInformation UserActionState を更新して UI を更新します。

注: 必要に応じて、関連するバックエンドに対してこの操作をPOSTして、ユーザーの設定を保持することもできます。

以下のスニペットは、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 回	現在再生中のメディアを無期限に繰り返します。
すべて繰り返す	キュー内の最後のアイテムが再生されたら、キュー内のすべてのアイテムを繰り返します。
すべて繰り返し、シャッフル	キュー内の最後のアイテムの再生が完了したら、キューをシャッフルしてキュー内のすべてのアイテムを繰り返します。
シャッフル	メディアキュー内のメディア アイテムをシャッフルします。 注: shuffle フラグを使用して、再生前にメディアをシャッフルすることもできます（LOAD メッセージの loadRequestData に設定されている場合）。
字幕のオン / オフ	メディアの字幕を有効または無効にする。有効 / 無効を言語別に確認することもできます。
シーク時間に移動	指定された絶対時間にジャンプします。
シークから現在時刻への相対移動	現在の再生時間に基づいて、指定した期間だけ前後にジャンプします。
もう一度プレイ	現在再生中のメディアを再開します。または、何も再生されていない場合は、最後に再生したメディア アイテムを再生します。
再生速度を設定する	メディアの再生速度はさまざまです。これはデフォルトで処理されます。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 フラグを削除し、制限するコマンドごとに受信メッセージをインターセプトできます。ここでは、アシスタントが提供するデバイスに発行された SEEK コマンドがウェブレシーバー アプリケーションでシークをトリガーしないように、SDK から提供されたリクエストをインターセプトします。

アプリがサポートしていないメディア コマンドの場合は、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;
  });

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

キャスト プラットフォームが、ユーザーの音声の聞き取りや戻るなどのアシスタントのアクティビティのためにアプリの音声をバックグラウンド処理する場合、アクティビティの起動時に NOT_IN_FOCUS の FocusState メッセージがウェブレシーバー アプリに送信されます。アクティビティが終了すると、IN_FOCUS という別のメッセージが送信されます。 再生するメディアとアプリによっては、FocusState が NOT_IN_FOCUS のときにメッセージ タイプ FOCUS_STATE をインターセプトしてメディアを一時停止できます。

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

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 に設定されます。

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

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

ストリーミング転送

注: オーディオ ウェブレシーバーはデフォルトでストリーム拡張をサポートし、Cast 対応デバイスがセッションに追加されます。動画ウェブレシーバーは、ストリーム転送をサポートするように、このセクションのステップを実行する必要があります。

セッション状態を維持することはストリーム転送の基礎であり、ユーザーは音声コマンド、Google Home アプリ、スマートディスプレイを使用して、既存の音声や動画のストリームをデバイス間で移動できます。メディアは、あるデバイス（ソース）で再生を停止し、別のデバイス（宛先）で再生を続けます。最新のファームウェアを搭載したキャスト デバイスは、ストリーミング転送でソースまたは宛先として機能できます。

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

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

メディア状態の要素は次のとおりです。

• 曲、動画、メディア アイテムの具体的な位置またはタイムスタンプ。
• 幅広いキュー（プレイリスト、アーティスト ラジオなど）に配置されていること。
• 認証されたユーザー。
• 再生状態（再生、一時停止など）。

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

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

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

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

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

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

Web Receiver SDK には、現在のメディア ステータスのスナップショットを作成し、ステータスを読み込みリクエストに変換して読み込みリクエストでセッションを再開することにより、セッション状態を保持するための Web Receiver アプリのデフォルト実装が用意されています。

ウェブ レシーバによって生成された読み込みリクエストは、必要に応じて 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;
    });

コンテンツのプリロード

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

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

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

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

カスタム メッセージ

メッセージ交換は、ウェブ受信側のアプリケーションでの主要な操作方法です。

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

ウェブ レシーバ アプリケーションは、指定された名前空間のメッセージをリッスンできます。これは、Web Receiver アプリケーションがその名前空間プロトコルをサポートしていると言われているためです。そのうえで、その Namespace で適切なプロトコルを使用することを希望する接続済みの送信者が対応します。

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

注: メディア メッセージの名前空間「urn:x-cast:com.google.cast.media」は予約されています。送信者とウェブ受信者の両方で Cast API を使用して送信されるメディア メッセージは、慣例として、メディア名前空間プロトコルを使用します。メディア メッセージの詳細については、メディアとプレーヤーをご覧ください。

次のコードでは、接続された送信者からのカスタム メッセージをリッスンするウェブ レシーバーのコード スニペットを示します。

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 Web Receiver が入力を再生および 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 で隠れていた問題が明らかになる可能性があります。
• メディアを更新するときは、timeupdate、pause、waiting などの <audio>/<video> 要素によって配信されるメディア関連のイベントを使用します。progress、suspend、stalled などのネットワーク関連のイベントは、プラットフォームに依存することが多いため、使用しないでください。レシーバでのメディア イベントの処理について詳しくは、メディア イベントをご覧ください。
• レシーバサイトの HTTPS 証明書を構成する場合は、必ず中間 CA 証明書を含めてください。詳しくは、Qualsys SSL テストページをご覧ください。このテスト用証明書には、サイトの信頼できる認証パスに「追加ダウンロード」というラベルの付いた CA 証明書が含まれていると、Android ベースのプラットフォームでは読み込まれないことがあります。
• Chromecast ではレシーバー ページが 720p グラフィック プレーンで表示されますが、Android TV などの他のキャスト プラットフォームでは、最大で 1080p のページが表示されることがあります。レシーバー ページが、異なる解像度で適切にスケーリングされるようにします。