開始使用

本指南說明如何使用 IMA CAF DAI SDK 播放動態廣告插播串流。如要查看或完成範例整合功能，請下載範例。

使用本指南前，請務必熟悉 Chromecast 應用程式架構的 Web 接收器通訊協定。本指南假設您熟悉 CAF 接收器概念 (例如訊息攔截器和 mediaInformation 物件) 的基本知識，以及熟悉使用 Cast 指令和控制工具來模擬 CAF 寄件者的方法。

如要使用 IMA DAI，您必須擁有 Ad Manager 360 帳戶。如果您有 Ad Manager 帳戶，請與客戶經理聯絡以瞭解詳情。如要進一步瞭解如何註冊 Ad Manager，請前往 Ad Manager 說明中心。

CAF 動態廣告插播總覽

使用 IMA CAF DAI SDK 導入動態廣告插播時，您需要有兩個主要元件；本指南將詳細說明：

  • StreamRequest：定義向 Google 廣告伺服器串流的請求。StreamRequests 有兩種主要差異：
    • LiveStreamRequest：指定素材資源金鑰、選用的 API 金鑰，以及其他選用參數。
    • VODStreamRequest：指定內容來源 ID、影片 ID、選用的 API 金鑰，以及其他自選參數。
  • StreamManager：能夠處理影片串流與 IMA DAI SDK 之間的物件，例如啟用連線偵測 (ping) 的連線偵測 (ping) 和將串流事件轉送至發布商。

必要條件

開始操作前，您必須符合以下條件：

1. 設定寄件者的 MediaInfo 物件

首先，請設定寄件者應用程式的 MediaInfo 物件，包含下列欄位：

contentId 此媒體項目的專屬 ID
contentUrl 如果 DAI StreamRequest 因任何原因失敗，載入的備用串流網址
streamType 如果是直播，這個值應設為「已上線」。如果是 VOD 串流，這個值應設為「BUFFERED」
customData assetKey 僅限直播。找出要載入的直播活動
contentSourceId 僅限 VOD 串流。識別內含要求的串流的媒體動態饋給。
videoId 僅限 VOD 串流。識別指定的媒體動態饋給中要求的串流。
ApiKey 選擇性 API 金鑰，用來從 IMA DAI SDK 擷取串流網址。
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 之後，新增指令碼代碼，將 CAF 的 IMA DAI SDK 匯入網路接收器。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 動態廣告插播的整合作業，您必須使用寄件者的 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 功能，請參閱其他指南或下載範例接收器應用程式。