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 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 phía máy khách IMA, bạn vẫn có 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 phía trên 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 IMA SDK 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 mẫu tích hợp hoàn chỉnh, hãy tải ví dụ đơn giản xuống từ GitHub. Nếu bạn quan tâm đến một trình phát HTML5 có SDK được tích hợp sẵn, hãy xem Trình bổ trợ SDK IMA cho Video.js.

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

Việc triển khai phía máy khách IMA bao gồm 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í mà IMA hiển thị các phần tử giao diện người dùng của 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 một trình tải quảng cáo và có thể sử dụng lại trình tải này 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. Các yêu cầu về quảng cáo chỉ định URL cho thẻ quảng cáo VAST, cũng như các thông số bổ sung, chẳng hạn như kích thước 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 việc phát quảng cáo và lắng nghe 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ó những thông tin sau:

  • Ba tệp trống:
    • index.html
    • style.css
    • ads.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ử

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

Vì IMA SDK tải các phần phụ thuộc bằng cách sử dụng cùng một giao thức với 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 của mình. Cách đơn giản nhất để khởi động một 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, hãy chạy: 
      python -m http.server 8000
  2. Trong trình duyệt web, hãy truy cập vào 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.

2. Tạo một 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 quá trình phát. Ví dụ sau đây nhập IMA SDK và thiết lập phần tử vùng chứa AdDisplayContainer. Để biết thêm thông tin chi tiết, hãy xem các bước Nhập SDK IMA và Tạo vùng chứa quảng cáo tương ứng. 

<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 chế độ 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 một lệnh gọi đến setUpIMA(), được xác định trong phần Khởi chạy AdsLoader và đưa ra yêu cầu quảng cáo .

3. Nhập IMA SDK

Tiếp theo, hãy thêm khung IMA bằ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 đều 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 phần tử giao diện người dùng liên quan đến quảng cáo. Vùng chứa này phải có kích thước phù hợp để phủ lên phần tử video từ góc trên cùng 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 đặt, nên 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 để đặt 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à đưa ra 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 một đối tượng AdDisplayContainer làm đầu vào và có thể dùng để xử lý các đối tượng AdsRequest được liên kết với một URL thẻ quảng cáo cụ thể. Thẻ quảng cáo được dùng trong ví dụ này có 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 Trình kiểm tra bộ video IMA.

Tốt nhất, bạn chỉ nên duy trì một phiên bản AdsLoader cho toàn bộ vòng đời của một trang. Để đưa ra các yêu cầu quảng cáo khác, 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 cách sử dụ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&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 các sự kiện AdsLoader

Khi AdsLoader tải quảng cáo thành công, sự kiện này sẽ phát ra 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 động đối tượng AdsManager. AdsManager tải từng quảng cáo riêng lẻ 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 ảnh hưởng đến việc 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ề các trình nghe được đặt trong hàm onAdsManagerLoaded(), hãy xem các mục con 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ý các sự kiện phát và tạm dừng

Khi AdsManager đã sẵn sàng chèn một quảng cáo để hiển thị, nó 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 lệnh tạm dừng trên trình phát video cơ bản. Tương tự, khi quảng cáo hoàn tất, AdsManager sẽ kích hoạt sự kiện CONTENT_RESUME_REQUESTED. Xử lý sự kiện này bằng cách khởi động 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ề các 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ý quá trình phát nội dung trong quảng cáo phi tuyến tính

AdsManager sẽ 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 phi 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 phi tuyến tính, hãy theo dõi AdsManager để phát sự kiện LOADED. Kiểm tra xem quảng cáo có phải là quảng cáo tuyến tính 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 về 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 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, IMA SDK sẽ chuyển mọi lượt nhấp không được IMA xử lý từ lớp phủ quảng cáo sang phần tử AdContainer để có thể xử lý các lượt nhấp đó. Quy tắc này không áp dụng cho quảng cáo dạng video trong luồng phát trên các trình duyệt không phải trình duyệt di động, vì việc nhấp vào quảng cáo sẽ mở đường liên kết lượt nhấp.

Để 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. Khởi động AdsManager

Để bắt đầu phát quảng cáo, hãy khởi chạy và bắt đầu AdsManager. Để hỗ trợ đầy đủ các 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ợ thay đổ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! Giờ đây, bạn đang yêu cầu và hiển thị quảng cáo bằng SDK IMA. Để 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.