開始使用

本指南說明如何使用 IMA CAF DAI SDK 播放 DAI 串流。如果想查看或按照已完成的整合範例操作，請下載範例。

運用本指南之前，請務必熟悉 Chromecast 應用程式架構的網路接收器通訊協定。本指南假設您熟悉 CAF 接收器概念 (例如訊息攔截器和 mediaInformation 物件)，並熟悉使用 Cast Command and Control 工具來模擬 CAF 傳送者。

如要使用 IMA DAI，您必須擁有 Ad Manager 360 帳戶。如果你有 Ad Manager 帳戶，請與客戶經理聯絡以瞭解詳情。如需使用 Ad Manager 的相關資訊，請前往 Ad Manager 說明中心。

CAF DAI 總覽

使用 IMA CAF DAI SDK 導入 DAI 涉及兩個主要元件，詳情請參閱本指南：

  • StreamRequest：定義傳送至 Google 廣告伺服器串流要求的物件。StreamRequest 有兩種主要類型：
    • LiveStreamRequest：指定 Asset Key、選用的 API 金鑰，以及其他選用參數。
    • VODStreamRequest：指定內容來源 ID、影片 ID 及選用的 API 金鑰，以及其他選用參數。
  • StreamManager：處理影片串流與 IMA DAI SDK 之間的通訊的物件，例如觸發追蹤連線偵測 (ping)，以及將串流事件轉送至發布商。

必要條件

在您開始之前，請先備妥下列項目：

1. 設定傳送者的 MediaInfo 物件

首先，請設定傳送者應用程式的 MediaInfo 物件，納入下列欄位：

contentId 此媒體項目的專屬 ID
contentUrl 如果 DAI StreamRequest 因故失敗，要載入的備用串流網址
streamType 如果是直播，這個值應設為「LIVE」。如果是 VOD 串流，這個值應設為「BUFFERED」
customData assetKey 僅限直播。找出要載入的直播
contentSourceId 僅限隨選影片串流。識別包含所要求串流的媒體動態饋給。
videoId 僅限隨選影片串流。識別指定媒體動態饋給中要求的串流。
ApiKey 從 IMA DAI SDK 擷取串流網址所需的選用 API 金鑰。
senderCanSkip 這個布林值可讓接收端知道傳送裝置是否能顯示略過按鈕，以便支援可略過廣告

如要在投放指令和控制工具中設定這些值，請按一下 [Load Media] 分頁，然後將自訂載入要求類型設為「LOAD」。接著將文字區域中的 JSON 資料替換為下列其中一個 JSON 物件：

直播

{
  "media": {
    "contentId": "bbb",
    "contentUrl": "https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8",
    "streamType": "LIVE",
    "customData": {
      "assetKey": "sN_IYUG8STe1ZzhIIE_ksA",
      "ApiKey": "",
      "senderCanSkip": true
    }
  },
  "credentials": "testCredentials"
}

隨選影片

{
  "media": {
    "contentId": "tos",
    "contentUrl": "https://storage.googleapis.com/interactive-media-ads/media/tos.m3u8",
    "streamType": "BUFFERED",
    "customData": {
      "contentSourceId": "2528370",
      "videoId": "tears-of-steel",
      "ApiKey": "",
      "senderCanSkip": true
    }
  },
  "credentials": "testCredentials"
}

系統會將這個自訂載入要求物件傳送給接收端，以測試下方每個步驟

2. 建立基本 CAF 接收器

按照 CAF SDK 基本接收器指南的說明，建立基本的網路接收器。

接收者的程式碼如下所示：

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js">
  </script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    cast.framework.CastReceiverContext.getInstance().start();
  </script>
</body>
</html>

3. 匯入 IMA DAI SDK 並取得播放器管理工具

新增指令碼代碼，將 CAF 適用的 IMA DAI SDK 匯入到網路接收器，緊接在指令碼載入 CAF 之後。CAF DAI SDK 具有常態性，因此無需設定特定版本。接著，在下方的指令碼標記中，將接收端結構定義和玩家管理員儲存為常數，再開始接收端。

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();

    castContext.start();
  </script>
</body>
</html>

4. 初始化 IMA Stream Manager

初始化 CAF DAI SDK 的串流管理員。

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    castContext.start();
  </script>
</body>
</html>

5. 建立載入訊息攔截器

CAF DAI SDK 會使用 CAF 載入訊息攔截器發出串流要求，並將內容網址替換為最終 DAI 串流。訊息攔截器會呼叫 streamManager.requestStream()，以處理廣告插播、要求串流以及取代現有的 contentURL。

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    const getStreamRequest = (request) => null;

    playerManager.setMessageInterceptor(
        cast.framework.messages.MessageType.LOAD, (request) => {
          return streamManager.requestStream(request, getStreamRequest(request))
              .then((request) => {
                this.broadcast('Stream request successful.');
                return Promise.resolve(request);
              })
              .catch((error) => {
                this.broadcast('Stream request failed.');
                return Promise.resolve(request);
              });
        });

    castContext.start();
  </script>
</body>
</html>

6. 建立串流要求

如要完成 CAF DAI 整合，您需要使用傳送端 mediaInfo 物件中所包含的資料來建立串流請求。

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    const getStreamRequest = (request) => {
      const imaRequestData = request.media.customData;
      let streamRequest = null;
      if (imaRequestData.assetKey) {
        // Live stream
        streamRequest = new google.ima.cast.dai.api.LiveStreamRequest();
        streamRequest.assetKey = imaRequestData.assetKey;
      } else if (imaRequestData.contentSourceId) {
        // VOD stream
        streamRequest = new google.ima.cast.dai.api.VODStreamRequest();
        streamRequest.contentSourceId = imaRequestData.contentSourceId;
        streamRequest.videoId = imaRequestData.videoId;
      }
      if (streamRequest && imaRequestData.ApiKey) {
        streamRequest.ApiKey = imaRequestData.ApiKey;
      }
      if (streamRequest && imaRequestData.senderCanSkip) {
        streamRequest.senderCanSkip = imaRequestData.senderCanSkip;
      }
      return streamRequest;
    };

    playerManager.setMessageInterceptor(
        cast.framework.messages.MessageType.LOAD, (request) => {
          return streamManager.requestStream(request, getStreamRequest(request))
              .then((request) => {
                return Promise.resolve(request);
              })
              .catch((error) => {
                this.broadcast('Stream request failed.');
                return Promise.resolve(request);
              });
        });

    castContext.start();
  </script>
</body>
</html>

...大功告成！現在，您可以使用 Google 的 CAF DAI SDK 要求及播放 DAI 串流。如要進一步瞭解更多進階 SDK 功能，請參閱其他指南或下載接收端應用程式範例。