Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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

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

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

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

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

CastReceiverContext は、デベロッパーに公開される最も外側のクラスです。基盤となるライブラリの読み込みを管理し、ウェブレシーバー 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 では、DRM 情報、再試行構成、cast.framework.PlaybackConfig を使用したリクエストハンドラなどの再生変数を構成できます。この情報は PlayerManager によって処理され、プレーヤーの作成時に評価されます。プレーヤーは、新しい読み込みがウェブレシーバー SDK に渡されるたびに作成されます。プレーヤーの作成後に PlaybackConfig を変更すると、次のコンテンツの読み込み時に評価されます。SDK には、PlaybackConfig を変更するための次のメソッドが用意されています。

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

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

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

イベントリスナー

ウェブレシーバー SDK を使用すると、ウェブレシーバーアプリでプレーヤーイベントを処理できます。イベントリスナーは、リスナーをトリガーするイベントを指定する 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
});

メッセージの傍受

ウェブレシーバー SDK を使用すると、ウェブレシーバーアプリでメッセージをインターセプトし、それらのメッセージに対してカスタムコードを実行できます。メッセージインターセプタは、インターセプトするメッセージのタイプを指定する 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 には、entity、contentUrl、contentId など、cast.framework.messages.MessageType.LOAD メッセージにメディアを読み込むためのプロパティが多数用意されています。

entity は、送信側アプリと受信側アプリの両方の実装で使用することをおすすめするプロパティです。このプロパティは、プレイリストまたはメディアコンテンツのディープリンク URL です。アプリケーションは、この URL を解析して、他の 2 つのフィールドの少なくとも 1 つに入力する必要があります。
contentUrl は、プレーヤーがコンテンツの読み込みに使用する再生可能な URL に対応しています。たとえば、この URL は DASH マニフェストを指すことができます。
contentId には、再生可能なコンテンツの URL（contentUrl プロパティと同様）か、読み込まれるコンテンツまたは再生リストの固有識別子を指定できます。このプロパティを識別子として使用する場合、アプリは 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 メソッドは、接続されているキャストデバイスと、それに接続されている動画またはオーディオ機器に関するデバイス情報を提供します。getDeviceCapabilities メソッドは、Google アシスタント、Bluetooth、接続されたディスプレイ、オーディオデバイスのサポート情報を提供します。

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

この例では、ウェブレシーバーデバイスが HDR と DolbyVision（DV）を再生できるかどうかを、それぞれ IS_HDR_SUPPORTED キーと IS_DV_SUPPORTED キーで確認しています。

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 に反映されます。また、iOS と Android の送信側の拡張コントローラの UI を更新するために、送信 MediaStatus メッセージを介してブロードキャストされます。

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

音声コマンド

アシスタント搭載デバイス用のウェブレシーバー 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 コマンドがウェブレシーバーアプリケーションでシークをトリガーしないようにします。

アプリがサポートしていないメディアコマンドについては、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 のときにメディアを一時停止することがあります。

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

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 などのスマートディスプレイといった新しいタイプのインターフェースでメタデータが適切に表示されるようになります。

ストリーミング転送

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

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

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

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

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

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

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

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

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

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

セッション状態の保持

ウェブレシーバー SDK には、ウェブレシーバーアプリのデフォルトの実装が用意されています。この実装では、現在のメディアステータスのスナップショットを取得し、ステータスを読み込みリクエストに変換して、読み込みリクエストでセッションを再開することで、セッションの状態を保持します。

ウェブレシーバーによって生成された読み込みリクエストは、必要に応じて 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 秒前にプリロードされます。プリロードまでの時間が currentItem の残り時間よりも長い場合、プリロードはできるだけ早く行われます。したがって、queueItem に非常に大きな preload 値を指定すると、現在のアイテムを再生しているときに、次のアイテムをプリロードする効果が得られます。ただし、この値は現在再生中のアイテムの帯域幅とストリーミングパフォーマンスに影響する可能性があるため、この設定と選択はデベロッパーに委ねられています。

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

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

カスタムメッセージ

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

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

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

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

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

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 ウェブレシーバーは、デバイスのコントロール入力（ハンドヘルドリモコンなど）からの入力を、メディア再生メッセージで説明されているように、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 テストページで、サイトの信頼できる証明書パスに「追加ダウンロード」というラベルの付いた CA 証明書が含まれているかどうかを確認します。含まれている場合、Android ベースのプラットフォームでは読み込まれない可能性があります。
Chromecast は 720p のグラフィックプレーンにレシーバーページを表示しますが、Android TV を含む他の Cast プラットフォームでは、最大 1080p でページを表示できます。レシーバーページがさまざまな解像度で適切にスケーリングされるようにします。

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

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