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 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ó SDK tích hợp sẵn, 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 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 thông qua 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. Ngoài ra, hãy thêm các thẻ cần thiết để tải các 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 các thiết bị di động. Cuối cùng, trong ads.js, hãy kích hoạt chế độ phát video khi người dùng 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 sẽ 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ý 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 quảng cáo đã được tải).
  • Khi cửa sổ trình duyệt đổi kích thước, hãy cập nhật phần tử video và kích thước adsManager để 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 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 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 thực thể ima.AdsLoader. Thực thể này 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 ima.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 kiểm tra bộ video IMA.

Tốt nhất là bạn chỉ duy trì một thực thể của ima.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 ima.AdsRequest mới, nhưng sử dụng lại cùng một ima.AdsLoader. Để biết thêm thông tin, hãy xem 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 tải thành công, ima.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 các 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.

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 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 để không ảnh hưởng đến trải nghiệm của 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. Bắt đầu AdsManager

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

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 AdsManager thích ứng

Để đả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 của AdsManager

AdsManager cũng kích hoạt một số sự kiện cần đượ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 chế độ 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ể đóng vai trò là 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 gọi lại.

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ị, 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.

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 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 muốn 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 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 chế độ phát trên 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 sẽ tiếp tục phát trong khi quảng cáo hiển thị. Để 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. Sau đó, hãy 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.

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 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.