Thiết lập SDK IMA cho DAI

SDK IMA giúp bạn dễ dàng tích hợp quảng cáo đa phương tiện vào trang web và ứng dụng của mình. SDK IMA có thể yêu cầu quảng cáo từ bất kỳ máy chủ quảng cáo tuân thủ VAST nào và quản lý việc phát quảng cáo trong ứng dụng của bạn. Với SDK DAI của IMA, các ứng dụng sẽ đưa ra yêu cầu về luồng cho quảng cáo và video nội dung – có thể là nội dung VOD hoặc nội dung trực tiếp. Sau đó, SDK sẽ trả về một luồng video kết hợp, nhờ đó bạn không phải quản lý việc chuyển đổi giữa quảng cáo và video nội dung trong ứng dụng của mình.

Chọn giải pháp DAI mà bạn quan tâm

DAI trọn gói

Hướng dẫn này minh hoạ cách tích hợp SDK DAI của IMA vào một ứng dụng trình phát video. Nếu bạn muốn xem hoặc làm theo một mẫu tích hợp hoàn chỉnh, hãy tải ví dụ đơn giản xuống từ GitHub.

Tổng quan về DAI của IMA

Việc triển khai SDK IMA DAI bao gồm 2 thành phần chính như minh hoạ trong hướng dẫn này:

  • StreamRequest – VODStreamRequest hoặc LiveStreamRequest: Một đối tượng xác định yêu cầu phát trực tuyến. Yêu cầu phát trực tuyến có thể là yêu cầu phát video theo yêu cầu hoặc phát trực tiếp. Yêu cầu phát trực tiếp chỉ định một khoá thành phần, trong khi yêu cầu VOD chỉ định một mã CMS và mã video. Cả hai loại yêu cầu đều có thể bao gồm một khoá API (không bắt buộc) cần thiết để truy cập vào các luồng truyền phát được chỉ định và mã mạng Google Ad Manager để SDK IMA xử lý mã nhận dạng quảng cáo như được chỉ định trong phần cài đặt Google Ad Manager.
  • StreamManager: Một đối tượng xử lý các luồng chèn quảng cáo động và các lượt tương tác với phần phụ trợ DAI. Trình quản lý luồng phát cũng xử lý các ping theo dõi và chuyển tiếp các sự kiện luồng phát và quảng cáo đến nhà xuất bản.

Điều kiện tiên quyết

  • Ba tệp trống
    • dai.html
    • dai.css
    • dai.js
  • Python được cài đặt trên máy tính của bạn hoặc một máy chủ web để sử dụng cho mục đích kiểm thử

Khởi động máy chủ phát triển

Vì IMA DAI SDK tải các phần phụ thuộc bằng giao thức giống như trang mà SDK được tải, nên bạn cần sử dụng một máy chủ web để kiểm thử ứng dụng. Một cách nhanh chóng để khởi động máy chủ phát triển cục bộ là sử dụng máy chủ tích hợp của Python.

  1. Sử dụng dòng lệnh, từ thư mục chứa tệp index.html của bạn, hãy chạy:

    python -m http.server 8000

  2. Trong trình duyệt web, hãy chuyển đến http://localhost:8000/

    Bạn cũng có thể sử dụng bất kỳ máy chủ web nào khác, chẳng hạn như Máy chủ HTTP Apache.

Tạo trình phát video

Trước tiên, hãy sửa đổi dai.html để tạo một phần tử video HTML5 và một div để dùng cho lượt nhấp qua. Ví dụ sau đây nhập IMA DAI SDK. Để biết thêm thông tin chi tiết, hãy xem phần Nhập SDK DAI IMA.

Ngoài ra, hãy thêm các thẻ cần thiết để tải tệp dai.css và dai.js, cũng như nhập trình phát video hls.js. Sau đó, hãy sửa đổi dai.css để chỉ định kích thước và vị trí của các phần tử trên trang. Cuối cùng, trong dai.js, hãy xác định các biến để lưu giữ thông tin yêu cầu phát trực tiếp, một hàm initPlayer() để chạy khi trang tải và thiết lập nút phát để yêu cầu phát trực tiếp khi nhấp vào.

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css">
</head>
<body onLoad="initPlayer()">
  <h2>IMA SDK DAI Demo (HLS.JS)</h2>
  <video id="video"></video>
  <div id="adUi"></div>
  <button id="play-button">Play</button>
</body>
</html>


dai.html
 
#video,
#adUi {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#adUi {
  cursor: pointer;
}

#play-button {
  position: absolute;
  top: 400px;
  left: 15px;
}

dai.css
 
// This stream will be played if ad-enabled playback fails.
const BACKUP_STREAM =
    'http://storage.googleapis.com/testtopbox-public/video_content/bbb/' +
    'master.m3u8';

// Live stream asset key.
// const TEST_ASSET_KEY = 'c-rArva4ShKVIAkNfy6HUQ';

// VOD content source and video IDs.
const TEST_CONTENT_SOURCE_ID = '2548831';
const TEST_VIDEO_ID = 'tears-of-steel';

// Ad Manager network code.
const NETWORK_CODE = '21775744923';
const API_KEY = null;

// StreamManager which will be used to request ad-enabled streams.
let streamManager;

// hls.js video player
const hls = new Hls();

// Video element
let videoElement;

// Ad UI element
let adUiElement;

// The play/resume button
let playButton;

// Whether the stream is currently in an ad break.
let adBreak = false;

/**
 * Initializes the video player.
 */
function initPlayer() {
  videoElement = document.getElementById('video');
  playButton = document.getElementById('play-button');
  adUiElement = document.getElementById('adUi');
  createStreamManager();
  listenForMetadata();

  // Show the video controls when the video is paused during an ad break,
  // and hide them when ad playback resumes.
  videoElement.addEventListener('pause', () => {
    if (adBreak) {
      showVideoControls();
    }
  });
  videoElement.addEventListener('play', () => {
    if (adBreak) {
      hideVideoControls();
    }
  });

  playButton.addEventListener('click', () => {
    console.log('initiatePlayback');
    requestStream();
    // Hide this play button after the first click to request the stream.
    playButton.style.display = 'none';
  });
}
dai.js

Để tiếp tục phát trong thời gian tạm dừng quảng cáo, hãy thiết lập trình nghe sự kiện cho các sự kiện pause và start của phần tử video để hiện và ẩn các chế độ điều khiển trình phát.

/**
 * Hides the video controls.
 */
function hideVideoControls() {
  videoElement.controls = false;
  adUiElement.style.display = 'block';
}

/**
 * Shows the video controls.
 */
function showVideoControls() {
  videoElement.controls = true;
  adUiElement.style.display = 'none';
}
dai.js

Tải SDK DAI của IMA

Tiếp theo, hãy thêm khung IMA bằng thẻ tập lệnh trong dai.html, trước thẻ cho dai.js.

<script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
dai.html

Khởi chạy StreamManager

Để yêu cầu một nhóm quảng cáo, hãy tạo một ima.dai.api.StreamManager. Lớp này chịu trách nhiệm yêu cầu và quản lý các luồng DAI. Hàm khởi tạo này lấy một phần tử video và một phần tử giao diện người dùng quảng cáo để xử lý các lượt nhấp vào quảng cáo.

/**
 * Create the StreamManager and listen to stream events.
 */
function createStreamManager() {
  streamManager =
      new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.LOADED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.ERROR, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED, onStreamEvent);
}
dai.js

Đưa ra yêu cầu phát trực tuyến

Xác định các hàm để yêu cầu luồng. Ví dụ này bao gồm các hàm cho cả VOD và sự kiện phát trực tiếp, tạo ra các thực thể của lớp VODStreamRequest và lớp LiveStreamRequest. Sau khi bạn có phiên bản streamRequest, hãy gọi phương thức streamManager.requestStream() bằng phiên bản yêu cầu truyền phát.

/**
 * Makes a stream request and plays the stream.
 */
function requestStream() {
  requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, NETWORK_CODE, API_KEY);
  // Uncomment line below and comment one above to request a LIVE stream.
  // requestLiveStream(TEST_ASSET_KEY, NETWORK_CODE, API_KEY);
}

/**
 * Requests a Live stream with ads.
 * @param {string} assetKey
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestLiveStream(assetKey, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

/**
 * Requests a VOD stream with ads.
 * @param {string} cmsId
 * @param {string} videoId
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestVODStream(cmsId, videoId, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}
dai.js

Cả hai phương thức yêu cầu truyền phát trực tiếp đều sử dụng một khoá API không bắt buộc. Nếu đang sử dụng luồng được bảo vệ, bạn cần tạo khoá xác thực DAI. Để biết thêm thông tin, hãy xem phần Xác thực yêu cầu luồng video chèn quảng cáo động (DAI). Không có luồng nào trong ví dụ này được bảo vệ bằng khoá xác thực DAI, vì vậy apiKey không được dùng.

Phân tích cú pháp siêu dữ liệu luồng

Bạn cũng cần thêm một trình xử lý để theo dõi các sự kiện siêu dữ liệu có dấu thời gian và chuyển tiếp các sự kiện đến lớp StreamManager để IMA phát ra các sự kiện quảng cáo trong thời gian tạm dừng quảng cáo:

/**
 * Set up metadata listeners to pass metadata to the StreamManager.
 */
function listenForMetadata() {
  // Timed metadata is handled differently by different video players, and the
  // IMA SDK provides two ways to pass in metadata,
  // StreamManager.processMetadata() and StreamManager.onTimedMetadata().
  //
  // Use StreamManager.onTimedMetadata() if your video player parses
  // the metadata itself.
  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with hls.js.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
    if (streamManager && data) {
      // For each ID3 tag in our metadata, we pass in the type - ID3, the
      // tag data (a byte array), and the presentation timestamp (PTS).
      data.samples.forEach(function(sample) {
        streamManager.processMetadata('ID3', sample.data, sample.pts);
      });
    }
  });
}
dai.js

Hướng dẫn này sử dụng trình phát hls.js để phát trực tuyến, nhưng việc triển khai siêu dữ liệu của bạn sẽ phụ thuộc vào loại trình phát mà bạn sử dụng.

Xử lý sự kiện luồng

Triển khai trình nghe sự kiện cho các sự kiện video chính. Ví dụ này xử lý các sự kiện LOADED, ERROR, AD_BREAK_STARTED và AD_BREAK_ENDED bằng cách gọi một hàm onStreamEvent(). Hàm này xử lý việc tải luồng phát, lỗi luồng phát và vô hiệu hoá các nút điều khiển trình phát trong quá trình phát quảng cáo (điều mà SDK IMA yêu cầu).

/**
 * Responds to a stream event.
 * @param {!google.ima.dai.api.StreamEvent} e
 */
function onStreamEvent(e) {
  switch (e.type) {
    case google.ima.dai.api.StreamEvent.Type.LOADED:
      console.log('Stream loaded');
      loadUrl(e.getStreamData().url);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadUrl(BACKUP_STREAM);
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
      console.log('Ad Break Started');
      adBreak = true;
      hideVideoControls();
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      adBreak = false;
      showVideoControls();
      break;
    default:
      break;
  }
}

/**
 * Loads and plays a Url.
 * @param {string} url
 */
function loadUrl(url) {
  console.log('Loading:' + url);
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  hls.on(Hls.Events.MANIFEST_PARSED, function() {
    console.log('Video Play');
    videoElement.play();
  });
}
dai.js

Khi luồng được tải, trình phát video sẽ tải và phát URL đã cung cấp bằng cách sử dụng hàm loadUrl().

Vậy là xong! Giờ đây, bạn đang yêu cầu và hiển thị quảng cáo bằng SDK IMA DAI. Để tìm hiểu về các tính năng nâng cao khác của SDK, hãy xem các hướng dẫn khác hoặc các mẫu trên GitHub.