為自訂網路接收器新增核心功能

本頁說明自訂 Web Receiver 應用程式的功能程式碼片段和說明。

注意：建議您嘗試下列做法：

• 投放 Web Receiver 程式碼研究室 - 瞭解如何使用 Google Cast SDK 建立可接收影片投放項目的 Web Web 接收器應用程式。
• CastReceiver 範例應用程式 (GitHub) - 執行、瀏覽及查看這個參考範例應用程式 (符合使用者體驗指南和設計檢查清單) 的說明。

1. cast-media-player 元素，代表透過 Web Receiver 提供的內建玩家 UI。
2. cast-media-player 元素的自訂 CSS 樣式樣式，可以為 background-image、splash-image 和 font-family 等各種 UI 元素設定樣式。
3. 用於載入網路接收器架構的指令碼元素。
4. 用於攔截訊息和處理事件的 JavaScript 程式碼。
5. 待播清單。
6. 設定播放的選項。
7. 設定網路接收器結構定義的選項。
8. 設定 Web Receiver 應用程式支援的指令選項。
9. 啟動 Web Receiver 應用程式的 JavaScript 呼叫。

注意： 強烈建議使用 cast-media-player HTML 元素，因為該元素會處理玩家的所有 UI 狀態及其樣式。

應用程式設定和選項

CastReceiverContext 是向開發人員公開最外部的類別，用於管理基礎程式庫的載入作業，並處理 Web Receiver SDK 的初始化作業

如果 Web Receiver API 偵測到寄件者連線中斷，就會發出 SENDER_DISCONNECTED 事件。如果網路接收器無法與 maxInactivity 秒中所述的內容進行通訊，系統也會傳送 SENDER_DISCONNECTED 事件。在開發期間，建議您將 maxInactivity 設為較高的值，方便使用 Chrome 遠端偵錯工具對應用程式進行偵錯時，Web 接收器應用程式不會關閉：

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

然而，對於「已發布」的網頁接收器應用程式，最好不要設定 maxInactivity，而是要依賴預設值。請注意，網路接收器選項只能在應用程式中設定一次。

另一個設定是 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() 會傳回空值物件。而PlaybackConfig that 中的任何屬性 undefined都將使用預設值。

事件監聽器

Web Receiver SDK 可讓網路接收器應用程式處理玩家事件。事件監聽器會採用 cast.framework.events.EventType 參數 (或這些參數的陣列)，以指定應觸發事件監聽器的事件。你可以在 cast.framework.events.category 中找到 cast.framework.events.EventType 預先設定的陣列，用於偵錯。事件參數提供事件的其他相關資訊。

舉例來說，如要瞭解廣播 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
});

注意： 網路接收器架構會在寄件者連線或中斷連線時自動追蹤，而且不需要在您自己的網路接收器邏輯中使用明確的 SENDER_DISCONNECTED 事件監聽器。

訊息攔截

Web Receiver SDK 可讓網路接收器應用程式攔截訊息，並在這些訊息中執行自訂程式碼。訊息攔截器會使用 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();

處理錯誤

如果訊息攔截器發生錯誤，您的網路接收器應用程式應傳回適當的 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 提供多種屬性，用於在 cast.framework.messages.MessageType.LOAD 訊息中載入媒體，包括 entity、contentUrl 和 contentId。

entity 是建議事件，適用於傳送者和接收器應用程式。房源是深層連結的網址，可以是播放清單或特定媒體內容。

contentUrl 專為可播放網址設計，一旦提供就會使用。

contentId 由於值是媒體的網址、真實 ID 或自訂查詢的鍵參數不明確，因此已淘汰。

建議您使用 entity 儲存真實 ID 或鍵參數，並在媒體網址使用 contentUrl。以下程式碼片段範例如下所示，在 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 助理、藍牙，以及已連結的螢幕和音訊裝置。

這個方法會傳回一個物件，您可以傳入其中一個指定的列舉值，藉此取得該列舉的裝置功能。列舉是在 cast.framework.system.DeviceCapabilities 中定義。

此範例會檢查 Web Receiver 裝置是否可分別使用 IS_HDR_SUPPORTED 和 IS_DV_SUPPORTED 鍵播放 HDR 和 DolbyVision (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)、支援 Google 助理裝置的語音指令、智慧螢幕上的觸控設定，以及 Android TV 裝置的遙控器。Cast SDK 提供多種 API，讓 Web Receiver 應用程式處理這些互動、透過使用者動作狀態更新應用程式 UI，並視需要傳送變更來更新任何後端服務。

支援的媒體指令

UI 控制項狀態是由 MediaStatus.supportedMediaCommands 針對 iOS 和 Android 寄件者展開的控制器、接收器和遠端控制應用程式執行，以及 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 指南。

管理使用者動作狀態

當使用者與使用者介面互動或傳送語音指令時，他們可以控制與播放項目相關的內容和屬性的播放作業。控製播放的要求會自動由 SDK 處理。要求修改目前項目的屬性 (例如 LIKE 指令) 會要求接收器應用程式處理這些屬性。這個 SDK 提供一系列的 API 來處理這類要求。如要支援這些要求，請按照下列步驟操作：

• 攔截 USER_ACTION 訊息並決定要求的動作。
• 更新 MediaInformation UserActionState 以更新使用者介面。

注意： 如有需要，您可以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 寄件者更新展開控制器的使用者介面。

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

語音指令

支援 Google 助理的裝置的 Web Receiver SDK 目前支援下列媒體指令：這些指令的預設實作方式位於 cast.framework.PlayerManager 中。

指令	說明
開始	播放或恢復已暫停狀態。
暫停	暫停播放目前正在播放的內容。
返回	跳至媒體佇列中的上一個媒體項目。
繼續	跳至媒體佇列中的下一個媒體項目。
停止	停止目前正在播放的媒體。
不重複播放	佇列中的最後一個項目播放完畢後，停止在佇列中重複播放媒體項目。
重複播放單一曲目	反覆播放目前播放的媒體。
重複播放所有項目	播放佇列中的最後一個項目之後，重複播放佇列中的所有項目。
重複播放所有歌曲	待播清單最後一個項目播放完畢之後，隨機播放佇列，並重複播放所有項目。
隨機播放	隨機播放媒體佇列中的媒體項目。 注意：你也可以在 shuffle 旗標 (位於 LOAD 訊息的 loadRequestData 標記中) 播放影片前隨機播放媒體項目。
開啟 / 關閉字幕	啟用 / 停用媒體的隱藏式輔助字幕。系統亦提供以語言啟用 / 停用的功能。
跳轉至 絕對時間	跳至指定的絕對時間。
跳轉至與目前時間差	根據目前播放時間，快轉或倒轉指定的時間。
再玩一次	如果目前未播放任何媒體，請重新啟動目前播放的媒體，或播放上一個播放的媒體項目。
設定播放速率	可用的媒體播放速率。根據預設，系統會處理這個事件。您可以使用 SET_PLAYBACK_RATE 訊息攔截器覆寫傳入的費率要求。

支援的語音指令指令

如要防止語音指令在支援 Google 助理的裝置上觸發媒體指令，您必須先設定一個支援的媒體指令。然後，您必須啟用 CastReceiverOptions.enforceSupportedCommands 屬性來強制執行這些指令。Cast SDK 傳送者和支援觸控裝置的使用者介面會變更，以反映這些設定。如果旗標未啟用，則系統會執行傳入的語音指令。

舉例來說，如果您允許來自寄件者應用程式和支援觸控裝置的裝置使用 PAUSE，就必須將接收器設定為反映這些設定。設定之後，如未在支援的指令清單中加入任何語音指令，系統就會捨棄這些語音指令。

在以下範例中，我們會在啟動 CastReceiverContext 時提供 CastReceiverOptions。我們已新增 PAUSE 指令的支援，並強制玩家僅支援該指令。現在，如果語音指令要求其他作業 (例如 SEEK)，就會遭到拒絕。系統會向使用者說明這項指令尚未支援。

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

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

您可以為每個限制指令分別套用邏輯。移除 enforceSupportedCommands 旗標，以及您要限制傳入的每個指令。在這裡，我們會攔截 SDK 提供的要求，讓支援 Google 助理的裝置發出 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;
  });

從語音活動進行背景

如果投放平台基於 Google 助理活動 (例如監聽使用者語音或朗讀內容) 而為應用程式背景播放音訊，系統會在活動啟動時將 NOT_IN_FOCUS 的 FocusState 訊息傳送至 Web 接收器。活動結束時，會再傳送一則含有 IN_FOCUS 的訊息。視您的應用程式和播放的媒體而定，如果 FocusState 是 NOT_IN_FOCUS，您可以攔截訊息類型 FOCUS_STATE，藉此暫停媒體。

舉例來說，如果 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。

中繼資料和語音投放

雖然網路接收器預設會處理語音指令，但您應確保內容的中繼資料完整且正確。這樣可確保 Google 助理能夠正確處理語音指令，而且中繼資料會在新的介面上 (例如 Google Home 應用程式) 和智慧螢幕 (如 Google Home Hub) 適當顯示。

變更串流裝置

注意： 音訊網路接收器預設支援串流擴充，因此會將其他支援 Cast 的裝置新增至工作階段。影片網路接收者必須執行本節所述的步驟，才能支援串流傳輸。

保留工作階段狀態是串流傳輸的基礎，使用者可透過語音指令、Google Home 應用程式或智慧螢幕，在不同裝置上移動現有的音訊和視訊串流。在某裝置上 (來源) 停止播放，並在另一部裝置上 (目的地) 繼續播放。任何搭載最新韌體的投放裝置都可以在串流轉移作業中做為來源或目的地。

串流傳輸的事件流程如下：

1. 在來源裝置上：
   1. 媒體已停止播放。
   2. 網路接收器應用程式會收到用於儲存現有媒體狀態的指令。
   3. Web Receiver 應用程式已關閉。
2. 在目標裝置上：
   1. 該網路接收器應用程式已載入。
   2. 網路接收器應用程式會收到指令，可還原已儲存的媒體狀態。
   3. 繼續播放媒體內容。

媒體狀態的元素包括：

• 歌曲、影片或媒體項目的特定位置或時間戳記。
• 這個播放清單會收錄較寬的佇列 (例如播放清單或藝人電台)。
• 通過驗證的使用者。
• 播放狀態 (例如播放或暫停)。

啟用串流傳輸

如要實作網路接收器的串流傳輸：

1. 使用 STREAM_TRANSFER 指令更新 supportedMediaCommands：

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

2. 視需要按照「保留工作階段狀態」一文的說明，覆寫 SESSION_STATE 和 RESUME_SESSION 訊息攔截器。只有在自訂資料必須儲存為工作階段快照的一部分時，才覆寫這些值。否則，保留工作階段狀態的預設實作將支援串流傳輸。

保留工作階段狀態

Web Receiver SDK 為網路接收器應用程式提供預設實作方式，方法是拍攝目前的媒體狀態快照、將狀態轉換為載入要求，以及使用載入要求恢復工作階段。

如有需要，您可以在 SESSION_STATE 訊息攔截器中覆寫 Web Receiver 產生的載入要求。如要將自訂資料新增至載入要求，建議您將其放入 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 秒預先載入。如果預先載入時間超過目前項目的剩餘時間，系統則會盡快執行預先載入作業。因此，如果 由於您在 itemItem 中指定了非常大量的預先載入值，就可能在每次播放目前項目時達到的效果，就是因為系統已經預先載入下一個項目。不過，我們會保留這個開發人員的設定和選項，因為這個值可能會影響目前播放項目的頻寬和串流效能。

根據預設，預先載入功能適用於 HLS、DASH 和流暢串流內容。

預載 MP4 影片和音訊檔案 (例如 MP3) 不會預先載入，因為投放裝置僅支援一個媒體元素，無法在現有內容項目播放時預先載入。

自訂訊息

訊息交換是網路接收器應用程式的主要互動方式。

傳送者使用傳送者平台 (Android、iOS、網頁) 的傳送者 API 向網路接收器發出訊息。傳遞至事件監聽器的事件物件 (也就是訊息的資訊清單) 具有資料元素 (event.data)，資料會用於特定事件類型的屬性。

網路接收器應用程式可以選擇監聽特定命名空間的訊息。透過這種做法，網路接收器應用程式可以支援該命名空間通訊協定。之後，任何想對該命名空間通訊的已連線寄件者，都必須使用適當的通訊協定。

所有命名空間都以字串定義，且開頭必須是「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 網路接收器，可將裝置控制輸入 (亦即手持遙控器) 的輸入轉譯為 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 憑證時，請務必納入中繼憑證授權單位憑證。請參閱 Qualsys 安全資料傳輸層 (SSL) 測試頁面來進行驗證：如果網站的信任認證路徑包含標記為「額外下載」的 CA 憑證，則可能無法在 Android 平台上載入。
• Chromecast 在 720p 平面平面上顯示接收器頁面，而 Android TV 等其他投放平台，頁面最多可以顯示 1080p 的頁面。確保接收器頁面能夠以不同解析度妥善縮放。