Thiết lập SDK IMA

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 nào tuân thủ VAST và quản lý việc phát quảng cáo trong ứng dụng của bạn. Với SDK phía máy khách IMA, bạn duy trì quyền kiểm soát việc phát video nội dung, trong khi SDK xử lý việc phát quảng cáo. Quảng cáo phát trong một trình phát video riêng biệt nằm ở đầu trình phát video nội dung của ứng dụng.

Hướng dẫn này minh hoạ cách tích hợp SDK IMA vào một ứng dụng trình phát video đơn giản. Nếu bạn muốn xem hoặc làm theo một ví dụ tích hợp mẫu đã hoàn tất, hãy tải ví dụ đơn giản xuống từ GitHub. Nếu bạn quan tâm đến trình phát HTML5 có tích hợp sẵn SDK, hãy xem Trình bổ trợ SDK IMA cho Video.js.

Tổng quan về IMA phía máy khách

Việc triển khai IMA phía máy khách liên quan đến 4 thành phần SDK chính, được minh hoạ trong hướng dẫn này:

  • AdDisplayContainer: Một đối tượng vùng chứa chỉ định vị trí IMA hiển thị các phần tử giao diện người dùng quảng cáo và đo lường khả năng xem, bao gồm cả Chế độ xem đang kích hoạt và Đo lường mở.
  • AdsLoader: Một đối tượng yêu cầu quảng cáo và xử lý các sự kiện từ phản hồi yêu cầu quảng cáo. Bạn chỉ nên tạo bản sao của một trình tải quảng cáo, có thể sử dụng lại trong suốt thời gian hoạt động của ứng dụng.
  • AdsRequest: Một đối tượng xác định yêu cầu quảng cáo. Yêu cầu quảng cáo chỉ định URL cho thẻ quảng cáo VAST, cũng như các tham số bổ sung, chẳng hạn như phương diện quảng cáo.
  • AdsManager: Một đối tượng chứa phản hồi cho yêu cầu quảng cáo, kiểm soát chế độ phát quảng cáo và theo dõi các sự kiện quảng cáo do SDK kích hoạt.

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

Trước khi bắt đầu, bạn cần có:

  • Ba tệp trống:
    • index.html
    • style.css
    • ads.js
  • Python đã cài đặt trên máy tính hoặc máy chủ web để dùng cho hoạt động kiểm thử

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

Vì SDK IMA tải các phần phụ thuộc bằng cùng một giao thức với trang tải SDK, nên bạn cần sử dụng máy chủ web để kiểm thử ứng dụng. Cách đơn giản nhất để khởi động máy chủ phát triển cục bộ là sử dụng máy chủ tích hợp sẵn của Python.

  1. Sử dụng dòng lệnh, từ thư mục chứa tệp index.html, 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ư Apache HTTP Server.

2. Tạo trình phát video đơn giản

Trước tiên, hãy sửa đổi index.html để tạo một phần tử video HTML5 đơn giản, nằm trong một phần tử bao bọc và một nút để kích hoạt phát. Ví dụ sau đây nhập SDK IMA và thiết lập phần tử vùng chứa AdDisplayContainer. Để biết thêm thông tin, hãy xem các bước tương ứng Nhập SDK IMA và Tạo vùng chứa quảng cáo . 

<html>
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <link rel="stylesheet" href="style.css">
  </head>

  <body>
    <div id="mainContainer">
      <div id="content">
        <video id="contentElement">
          <source src="https://storage.googleapis.com/gvabox/media/samples/stock.mp4"></source>
        </video>
      </div>
      <div id="adContainer"></div>
    </div>
    <button id="playButton">Play</button>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

index.html
 
#mainContainer {
  position: relative;
  width: 640px;
  height: 360px;
}

#content {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}

#contentElement {
  width: 640px;
  height: 360px;
  overflow: hidden;
}

#playButton {
  margin-top:10px;
  vertical-align: top;
  width: 350px;
  height: 60px;
  padding: 0;
  font-size: 22px;
  color: white;
  text-align: center;
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
  background: #2c3e50;
  border: 0;
  border-bottom: 2px solid #22303f;
  cursor: pointer;
  -webkit-box-shadow: inset 0 -2px #22303f;
  box-shadow: inset 0 -2px #22303f;
}
style.css
 
let adsManager;
let adsLoader;
let adDisplayContainer;
let isAdPlaying;
let isContentFinished;
let playButton;
let videoContent;
let adContainer;

// On window load, attach an event to the play button click
// that triggers playback of the video element.
window.addEventListener('load', function(event) {
  videoContent = document.getElementById('contentElement');
  adContainer = document.getElementById('adContainer');
  adContainer.addEventListener('click', adContainerClick);
  playButton = document.getElementById('playButton');
  playButton.addEventListener('click', playAds);
  setUpIMA();
});
ads.js

Thêm các thẻ cần thiết để tải tệp style.css và ads.js. Sau đó, hãy sửa đổi styles.css để trình phát video thích ứng với thiết bị di động. Cuối cùng, trong ads.js, hãy khai báo các biến và kích hoạt phát video khi bạn nhấp vào nút phát.

Xin lưu ý rằng đoạn mã ads.js chứa lệnh gọi đến setUpIMA(). Lệnh gọi này được xác định trong phần Khởi chạy AdsLoader và tạo yêu cầu quảng cáo .

3. Nhập SDK IMA

Tiếp theo, hãy thêm khung IMA bằng cách sử dụng thẻ tập lệnh trong index.html, trước thẻ cho ads.js. 

<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
index.html

4. Tạo vùng chứa quảng cáo

Trong hầu hết các trình duyệt, SDK IMA sử dụng một phần tử vùng chứa quảng cáo chuyên dụng để hiển thị cả quảng cáo và các thành phần giao diện người dùng liên quan đến quảng cáo. Bạn phải định cỡ vùng chứa này để phủ lên phần tử video từ góc trên bên trái. Chiều cao và chiều rộng của quảng cáo được đặt trong vùng chứa này do đối tượng adsManager thiết lập, vì vậy, bạn không cần phải đặt các giá trị này theo cách thủ công.

Để triển khai phần tử vùng chứa quảng cáo này, trước tiên, hãy tạo một div mới trong phần tử video-container. Sau đó, hãy cập nhật CSS để định vị phần tử ở góc trên cùng bên trái của video-element. Cuối cùng, hãy thêm hàm createAdDisplayContainer() để tạo đối tượng AdDisplayContainer bằng vùng chứa quảng cáo mới div. 

<div id="adContainer"></div>
index.html
 
#adContainer {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}
style.css
 
/**
 * Sets the 'adContainer' div as the IMA ad display container.
 */
function createAdDisplayContainer() {
  adDisplayContainer = new google.ima.AdDisplayContainer(
      document.getElementById('adContainer'), videoContent);
}
ads.js

5. Khởi chạy AdsLoader và tạo yêu cầu quảng cáo

Để yêu cầu quảng cáo, hãy tạo một thực thể AdsLoader. Hàm khởi tạo AdsLoader lấy đối tượng AdDisplayContainer làm dữ liệu đầu vào và có thể được dùng để xử lý các đối tượng AdsRequest liên kết với một URL thẻ quảng cáo đã chỉ định. Thẻ quảng cáo được sử dụng trong ví dụ này chứa một quảng cáo trước video dài 10 giây. Bạn có thể kiểm tra URL thẻ quảng cáo này hoặc bất kỳ URL thẻ quảng cáo nào bằng cách sử dụng Trình theo dõi bộ video IMA.

Tốt nhất, bạn chỉ nên duy trì một thực thể của AdsLoader cho toàn bộ vòng đời của một trang. Để tạo thêm yêu cầu quảng cáo, hãy tạo một đối tượng AdsRequest mới, nhưng sử dụng lại cùng một AdsLoader. Để biết thêm thông tin, hãy xem Câu hỏi thường gặp về SDK IMA.

Theo dõi và phản hồi các sự kiện lỗi và quảng cáo đã tải bằng AdsLoader.addEventListener. Theo dõi các sự kiện sau:

  • ADS_MANAGER_LOADED
  • AD_ERROR

Để tạo trình nghe onAdsManagerLoaded() và onAdError(), hãy xem ví dụ sau: 

/**
 * Sets up IMA ad display container, ads loader, and makes an ad request.
 */
function setUpIMA() {
  // Create the ad display container.
  createAdDisplayContainer();
  // Create ads loader.
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  // Listen and respond to ads loaded and error events.
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded, false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError, false);

  // An event listener to tell the SDK that our content video
  // is completed so the SDK can play any post-roll ads.
  const contentEndedListener = function() {
    // An ad might have been playing in the content element, in which case the
    // content has not actually ended.
    if (isAdPlaying) return;
    isContentFinished = true;
    adsLoader.contentComplete();
  };
  videoContent.onended = contentEndedListener;

  // Request video ads.
  const adsRequest = new google.ima.AdsRequest();
  adsRequest.adTagUrl = 'https://pubads.g.doubleclick.net/gampad/ads?' +
      'iu=/21775744923/external/single_ad_samples&sz=640x480&' +
      'cust_params=sample_ct%3Dlinear&ciu_szs=300x250%2C728x90&gdfp_req=1&' +
      'output=vast&unviewed_position_start=1&env=vp&impl=s&correlator=';

  // Specify the linear and nonlinear slot sizes. This helps the SDK to
  // select the correct creative if multiple are returned.
  adsRequest.linearAdSlotWidth = 640;
  adsRequest.linearAdSlotHeight = 400;

  adsRequest.nonLinearAdSlotWidth = 640;
  adsRequest.nonLinearAdSlotHeight = 150;

  adsLoader.requestAds(adsRequest);
}
ads.js

6. Phản hồi sự kiện AdsLoader

Khi tải quảng cáo thành công, AdsLoader sẽ phát ra một sự kiện ADS_MANAGER_LOADED. Phân tích cú pháp sự kiện được truyền đến lệnh gọi lại để khởi chạy đối tượng AdsManager. AdsManager tải từng quảng cáo theo định nghĩa của phản hồi đối với URL thẻ quảng cáo.

Đảm bảo bạn xử lý mọi lỗi xảy ra trong quá trình tải. Nếu quảng cáo không tải, hãy đảm bảo rằng quá trình phát nội dung nghe nhìn vẫn tiếp tục mà không có quảng cáo để tránh làm gián đoạn người dùng xem nội dung. 

/**
 * Handles the ad manager loading and sets ad event listeners.
 * @param {!google.ima.AdsManagerLoadedEvent} adsManagerLoadedEvent
 */
function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Get the ads manager.
  const adsRenderingSettings = new google.ima.AdsRenderingSettings();
  adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;
  // videoContent should be set to the content video element.
  adsManager =
      adsManagerLoadedEvent.getAdsManager(videoContent, adsRenderingSettings);

  // Add listeners to the required events.
  adsManager.addEventListener(google.ima.AdErrorEvent.Type.AD_ERROR, onAdError);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested);
  adsManager.addEventListener(
      google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
      onContentResumeRequested);
  adsManager.addEventListener(google.ima.AdEvent.Type.LOADED, onAdLoaded);
}

/**
 * Handles ad errors.
 * @param {!google.ima.AdErrorEvent} adErrorEvent
 */
function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  adsManager.destroy();
}
ads.js

Để biết thêm thông tin chi tiết về trình nghe được đặt trong hàm onAdsManagerLoaded(), hãy xem các tiểu mục sau:

Xử lý lỗi AdsManager

Trình xử lý lỗi được tạo cho AdsLoader cũng có thể đóng vai trò là trình xử lý lỗi cho AdsManager. Xem trình xử lý sự kiện sử dụng lại hàm onAdError(). 

adsManager.addEventListener(google.ima.AdErrorEvent.Type.AD_ERROR, onAdError);
ads.js

Xử lý sự kiện phát và tạm dừng

Khi AdsManager sẵn sàng chèn quảng cáo để hiển thị, lớp này sẽ kích hoạt sự kiện CONTENT_PAUSE_REQUESTED. Xử lý sự kiện này bằng cách kích hoạt chế độ tạm dừng trên trình phát video cơ bản. Tương tự, khi một quảng cáo kết thúc, AdsManager sẽ kích hoạt sự kiện CONTENT_RESUME_REQUESTED. Xử lý sự kiện này bằng cách bắt đầu lại quá trình phát trên video nội dung cơ bản. 

adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested);
adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
    onContentResumeRequested);
ads.js

Để biết định nghĩa về hàm onContentPauseRequested() và onContentResumeRequested(), hãy xem ví dụ sau: 

/**
 * Pauses video content and sets up ad UI.
 */
function onContentPauseRequested() {
  isAdPlaying = true;
  videoContent.pause();
  // This function is where you should setup UI for showing ads (for example,
  // display ad timer countdown, disable seeking and more.)
  // setupUIForAds();
}

/**
 * Resumes video content and removes ad UI.
 */
function onContentResumeRequested() {
  isAdPlaying = false;
  if (!isContentFinished) {
    videoContent.play();
  }
  // This function is where you should ensure that your UI is ready
  // to play content. It is the responsibility of the Publisher to
  // implement this function when necessary.
  // setupUIForContent();
}
ads.js

Xử lý việc phát nội dung trong quảng cáo phi tuyến tính

AdsManager tạm dừng video nội dung khi quảng cáo đã sẵn sàng phát, nhưng hành vi này không tính đến quảng cáo không tuyến tính, trong đó nội dung tiếp tục phát trong khi quảng cáo hiển thị. 

adsManager.addEventListener(google.ima.AdEvent.Type.LOADED, onAdLoaded);
ads.js

Để hỗ trợ quảng cáo không tuyến tính, hãy theo dõi AdsManager để phát ra sự kiện LOADED. Kiểm tra xem quảng cáo có phải là quảng cáo truyền hình truyền thống hay không. Nếu không, hãy tiếp tục phát trên phần tử video.

Để biết định nghĩa của hàm onAdLoaded(), hãy xem ví dụ sau. 

/**
 * Handles ad loaded event to support non-linear ads. Continues content playback
 * if the ad is not linear.
 * @param {!google.ima.AdEvent} adEvent
 */
function onAdLoaded(adEvent) {
  let ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoContent.play();
  }
}
ads.js

7. Kích hoạt tính năng nhấp để tạm dừng trên thiết bị di động

Vì AdContainer phủ lên phần tử video, nên người dùng không thể tương tác trực tiếp với trình phát cơ bản. Điều này có thể gây nhầm lẫn cho người dùng trên thiết bị di động, những người mong muốn có thể nhấn vào trình phát video để tạm dừng phát. Để giải quyết vấn đề này, SDK IMA sẽ chuyển mọi lượt nhấp không được IMA xử lý từ lớp phủ quảng cáo đến phần tử AdContainer, nơi có thể xử lý các lượt nhấp đó. Điều này không áp dụng cho quảng cáo truyền hình trên trình duyệt không phải dành cho thiết bị di động, vì khi nhấp vào quảng cáo, đường liên kết lượt nhấp sẽ mở ra.

Để triển khai tính năng nhấp để tạm dừng, hãy thêm hàm trình xử lý lượt nhấp adContainerClick() được gọi trong trình nghe tải cửa sổ. 

/**
 * Handles clicks on the ad container to support expected play and pause
 * behavior on mobile devices.
 * @param {!Event} event
 */
function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoContent.paused) {
    videoContent.play();
  } else {
    videoContent.pause();
  }
}
ads.js

8. Bắt đầu AdsManager

Để bắt đầu phát quảng cáo, hãy khởi tạo và bắt đầu AdsManager. Để hỗ trợ đầy đủ trình duyệt di động, nơi bạn không thể tự động phát quảng cáo, hãy kích hoạt chế độ phát quảng cáo từ các lượt tương tác của người dùng với trang, chẳng hạn như nhấp vào nút phát. 

/**
 * Loads the video content and initializes IMA ad playback.
 */
function playAds() {
  // Initialize the container. Must be done through a user action on mobile
  // devices.
  videoContent.load();
  adDisplayContainer.initialize();

  try {
    // Initialize the ads manager. This call starts ad playback for VMAP ads.
    adsManager.init(640, 360);
    // Call play to start showing the ad. Single video and overlay ads will
    // start at this time; the call will be ignored for VMAP ads.
    adsManager.start();
  } catch (adError) {
    // An error may be thrown if there was a problem with the VAST response.
    videoContent.play();
  }
}
ads.js

9. Hỗ trợ đổi kích thước trình phát

Để quảng cáo tự động đổi kích thước và khớp với kích thước của trình phát video hoặc để khớp với các thay đổi về hướng màn hình, hãy gọi adsManager.resize() để phản hồi các sự kiện đổi kích thước cửa sổ. 

window.addEventListener('resize', function(event) {
  console.log("window resized");
  if(adsManager) {
    let width = videoContent.clientWidth;
    let height = videoContent.clientHeight;
    adsManager.resize(width, height, google.ima.ViewMode.NORMAL);
  }
});
ads.js

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