Bắt đầu

SDK IMA giúp bạn dễ dàng tích hợp quảng cáo đa phương tiện vào các 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 của IMA, bạn duy trì quyền kiểm soát việc phát video nội dung, còn SDK xử lý việc phát quảng cáo. Quảng cáo sẽ 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 quy trình tích hợp mẫu 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 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 sau:

  • AdDisplayContainer: Đối tượng vùng chứa nơi quảng cáo được hiển thị.
  • AdsLoader: Đối tượng yêu cầu quảng cáo và xử lý sự kiện từ phản hồi yêu cầu quảng cáo. Bạn chỉ nên tạo thực thể cho 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: Đố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 thông số bổ sung, chẳng hạn như kích thước quảng cáo.
  • AdsManager: Đố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à 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 sẽ cần có:

  • Ba tệp trống:
    • index.html
    • style.css
    • ads.js
  • Đã cài đặt Python trên máy tính hoặc một máy chủ web để dùng cho việc 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 thông qua cùng một giao thức với trang tải các phần phụ thuộc, nên bạn cần sử dụng một máy chủ web để kiểm tra ứ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 sẵn của Python.

  1. Sử dụng một dòng lệnh trong thư mục chứa tệp chạy index.html của bạn:
      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ể dùng bất kỳ máy chủ web nào khác, chẳng hạn như Máy chủ Apache HTTP.

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ử xuống dòng và một nút để kích hoạt chế độ phát. Ngoài ra, hãy thêm các thẻ cần thiết để tải các tệp style.cssads.js. Sau đó, 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 kích hoạt chế độ phát video khi nhấp vào nút phát.

index.html

<!doctype html>
<html lang="en">
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
    <link rel="stylesheet" href="style.css">
  </head>
  <body>
    <div id="page-content">
      <div id="video-container">
        <video id="video-element">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
          <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="ads.js"></script>
  </body>
</html>

style.css
#page-content {
  position: relative;
  /* this element's width controls the effective height */
  /* of the video container's padding-bottom */
  max-width: 640px;
  margin: 10px auto;
}

#video-container {
  position: relative;
  /* forces the container to match a 16x9 aspect ratio */
  /* replace with 75% for a 4:3 aspect ratio, if needed */
  padding-bottom: 56.25%;
}

#video-element {
  /* forces the contents to fill the container */
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
}
ads.js
var videoElement;

// On window load, attach an event to the play button click
// that triggers playback on the video element
window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

Sau khi hoàn tất bước này, khi mở index.html trong trình duyệt (thông qua máy chủ phát triển), bạn có thể thấy phần tử video và video sẽ bắt đầu khi bạn nhấp vào nút phát.

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.

index.html
...

        </video>
      </div>
      <button id="play-button">Play</button>
    </div>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

4. Đính kèm trình xử lý của trang và trình phát video

Để sửa đổi hành vi của trình phát video bằng JavaScript, hãy thêm trình xử lý sự kiện kích hoạt các thao tác sau:

  • Khi trang tải xong, hãy khởi chạy SDK IMA.
  • Khi người dùng nhấp vào nút phát video, hãy tải quảng cáo (trừ phi đã có quảng cáo được tải).
  • Khi cửa sổ trình duyệt được đổi kích thước, hãy cập nhật phần tử video và các phương diện adsManager để giúp trang thích ứng với thiết bị di động
ads.js
var videoElement;
// Define a variable to track whether there are ads loaded and initially set it to false
var adsLoaded = false;

window.addEventListener('load', function(event) {
  videoElement = document.getElementById('video-element');
  initializeIMA();
  videoElement.addEventListener('play', function(event) {
    loadAds(event);
  });
  var playButton = document.getElementById('play-button');
  playButton.addEventListener('click', function(event) {
    videoElement.play();
  });
});

window.addEventListener('resize', function(event) {
  console.log("window resized");
});

function initializeIMA() {
  console.log("initializing IMA");
}

function loadAds(event) {
  // Prevent this function from running on if there are already ads loaded
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // Prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");
}

5. 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 phần tử vùng chứa quảng cáo chuyên dụng để hiển thị cả quảng cáo và 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 định kích thước để 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 đặt trong vùng chứa này do đối tượng adsManager thiết lập, nên bạn không cần đặt 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 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 xác định một biến cho vùng chứa trong hàm initializeIMA() chạy khi trang được tải.

index.html
...

  <div id="video-container">
    <video id="video-element" controls>
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.mp4">
      <source src="https://storage.googleapis.com/interactive-media-ads/media/android.webm">
    </video>
    <div id="ad-container"></div>
  </div>

...
style.css
...

#ad-container {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
}
ads.js
var videoElement;
var adsLoaded = false;
var adContainer;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
}

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

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

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

ads.js
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

  // Let the AdsLoader know when the video has ended
  videoElement.addEventListener('ended', function() {
    adsLoader.contentComplete();
  });

  var 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 = videoElement.clientWidth;
  adsRequest.linearAdSlotHeight = videoElement.clientHeight;
  adsRequest.nonLinearAdSlotWidth = videoElement.clientWidth;
  adsRequest.nonLinearAdSlotHeight = videoElement.clientHeight / 3;

  // Pass the request to the adsLoader to request ads
  adsLoader.requestAds(adsRequest);
}

7. Theo dõi các sự kiện AdsLoader

Khi quảng cáo được tải thành công, ima.AdsLoader sẽ tạo 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 động đối tượng AdsManager. AdsManager tải từng quảng cáo riêng lẻ như được xác định bằng nội dung phản hồi cho URL thẻ quảng cáo.

Ngoài ra, hãy nhớ xử lý mọi lỗi có thể xảy ra trong quá trình tải. Nếu quảng cáo không tải, hãy đảm bảo việc tiếp tục phát nội dung nghe nhìn mà không có quảng cáo để không ảnh hưởng đến trải nghiệm người dùng.

ads.js
var videoElement;
var adsLoaded = false;
var adContainer;
var adDisplayContainer;
var adsLoader;
var adsManager;

...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded,
      false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR,
      onAdError,
      false);

...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Instantiate the AdsManager from the adsLoader response and pass it the video element
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);
}

function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  if(adsManager) {
    adsManager.destroy();
  }
}

8. Khởi động AdsManager

Để bắt đầu phát quảng cáo, bạn cần bật AdsManager. Để hỗ trợ đầy đủ cho các trình duyệt dành cho thiết bị di động, thao tác này phải được kích hoạt khi người dùng tương tác.

ads.js
...

function loadAds(event) {
  // prevent this function from running on every play event
  if(adsLoaded) {
    return;
  }
  adsLoaded = true;

  // prevent triggering immediate playback when ads are loading
  event.preventDefault();

  console.log("loading ads");

  // Initialize the container. Must be done via a user action on mobile devices.
  videoElement.load();
  adDisplayContainer.initialize();

  var width = videoElement.clientWidth;
  var height = videoElement.clientHeight;
  try {
    adsManager.init(width, height, google.ima.ViewMode.NORMAL);
    adsManager.start();
  } catch (adError) {
    // Play the video without ads, if an error occurs
    console.log("AdsManager could not be started");
    videoElement.play();
  }
}

...

9. Tạo tính năng thích ứng cho AdsManager

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

ads.js
...

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

...

10. Theo dõi các sự kiện AdsManager

AdsManager cũng kích hoạt một số sự kiện cần phải được xử lý. Các sự kiện này được dùng để theo dõi các thay đổi về trạng thái, kích hoạt tính năng phát và tạm dừng trên video nội dung cũng như đăng ký lỗi.

Xử lý lỗi

Trình xử lý lỗi được tạo cho AdsLoader có thể hoạt động như trình xử lý lỗi cho AdsManager bằng cách thêm một trình xử lý sự kiện mới có cùng hàm callback.

ads.js
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

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

...

Kích hoạt 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ị, thao tác này sẽ kích hoạt sự kiện CONTENT_PAUSE_REQUESTED. Hãy xử lý sự kiện này bằng cách kích hoạt một thời điểm tạm dừng trên trình phát video cơ bản. Tương tự, khi một quảng cáo hoàn tất, AdsManager sẽ kích hoạt sự kiện CONTENT_RESUME_REQUESTED. Hãy xử lý sự kiện này bằng cách bắt đầu phát lại trên video nội dung cơ bản.

ads.js
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  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);
}

...

function onContentPauseRequested() {
  videoElement.pause();
}

function onContentResumeRequested() {
  videoElement.play();
}

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

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 và họ 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 do IMA xử lý từ lớp phủ quảng cáo sang phần tử AdContainer, tại đó chúng có thể được xử lý. Điều này không áp dụng cho quảng cáo tuyến tính trên các trình duyệt không dành cho thiết bị di động, vì thao tác nhấp vào quảng cáo sẽ mở đường liên kết nhấp.

Để triển khai tính năng nhấp để tạm dừng, hãy thêm một trình xử lý lượt nhấp vào AdContainer và kích hoạt các sự kiện phát hoặc tạm dừng trên video cơ bản.

ads.js
...

function initializeIMA() {
  console.log("initializing IMA");
  adContainer = document.getElementById('ad-container');
  adContainer.addEventListener('click', adContainerClick);
  adDisplayContainer = new google.ima.AdDisplayContainer(adContainer, videoElement);
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);

...

function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoElement.paused) {
    videoElement.play();
  } else {
    videoElement.pause();
  }
}

...

Kích hoạt phát trên quảng cáo phi tuyến tính

AdsManager sẽ tạm dừng video nội dung khi một 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, nơi nội dung sẽ tiếp tục phát trong khi quảng cáo hiển thị. Để hỗ trợ quảng cáo phi tuyến tính, hãy theo dõi AdsManager để phát ra sự kiện LOADED. Sau đó, hãy kiểm tra xem quảng cáo đó có phải là 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.

ads.js
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

  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);
}

...

function onAdLoaded(adEvent) {
  var ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoElement.play();
  }
}

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 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 mẫu trên GitHub.