เริ่มต้น

IMA SDK ช่วยให้การผสานรวมโฆษณามัลติมีเดียลงในเว็บไซต์และแอปเป็นเรื่องง่าย IMA SDK สามารถขอโฆษณาจากเซิร์ฟเวอร์โฆษณาที่ สอดคล้องกับ VAST ใดๆ ก็ได้และจัดการการเล่นโฆษณาในแอปของคุณ เมื่อใช้ SDK ฝั่งไคลเอ็นต์ของ IMA คุณจะเป็นผู้ควบคุมการเล่นวิดีโอเนื้อหา ส่วน SDK จะจัดการการเล่นโฆษณา โฆษณาจะเล่นในโปรแกรมเล่นวิดีโอแยกต่างหากซึ่งอยู่ที่ด้านบนของโปรแกรมเล่นวิดีโอเนื้อหาของแอป

คู่มือนี้แสดงวิธีผสานรวม IMA SDK เข้ากับแอปโปรแกรมเล่นวิดีโอแบบง่าย หากคุณต้องการดูหรือทำตามตัวอย่างการผสานรวมที่สมบูรณ์ ให้ดาวน์โหลดตัวอย่างง่ายๆ จาก GitHub หากคุณสนใจโปรแกรมเล่น HTML5 ที่ผสานรวม SDK ไว้ล่วงหน้าแล้ว โปรดดูปลั๊กอิน IMA SDK สำหรับวิดีโอ.js

ภาพรวมฝั่งไคลเอ็นต์ของ IMA

การใช้งาน IMA ฝั่งไคลเอ็นต์นั้นเกี่ยวข้องกับองค์ประกอบ SDK หลัก 4 อย่างดังที่แสดงในคู่มือนี้

  • AdDisplayContainer: คอนเทนเนอร์ออบเจ็กต์ที่แสดงโฆษณา
  • AdsLoader: ออบเจ็กต์ที่ขอโฆษณาและจัดการเหตุการณ์จากการตอบกลับคำขอโฆษณา คุณควรเตรียมตัวโหลดโฆษณาไว้เพียงตัวเดียว ซึ่งสามารถนำมาใช้ซ้ำได้ตลอดอายุของแอปพลิเคชัน
  • AdsRequest: ออบเจ็กต์ที่กำหนดคำขอโฆษณา คำขอโฆษณาจะระบุ URL สำหรับแท็กโฆษณา VAST รวมถึงพารามิเตอร์เพิ่มเติม เช่น มิติข้อมูลโฆษณา
  • AdsManager: ออบเจ็กต์ที่มีการตอบกลับคำขอโฆษณา ควบคุมการเล่นโฆษณา และรอฟังเหตุการณ์โฆษณาที่ SDK เริ่มทำงาน

ข้อกำหนดเบื้องต้น

ก่อนเริ่มต้น คุณต้องมีสิ่งต่อไปนี้

  • ไฟล์เปล่า 3 ไฟล์ ได้แก่
    • index.html
    • style.css
    • ads.js
  • Python ที่ติดตั้งในคอมพิวเตอร์หรือเว็บเซิร์ฟเวอร์ที่จะใช้ในการทดสอบ

1. เริ่มต้นเซิร์ฟเวอร์การพัฒนา

เนื่องจาก IMA SDK โหลดทรัพยากร Dependency ผ่านโปรโตคอลเดียวกับหน้าเว็บที่โหลด คุณต้องใช้เว็บเซิร์ฟเวอร์ในการทดสอบแอป วิธีที่ง่ายที่สุดในการเริ่มต้นเซิร์ฟเวอร์การพัฒนาภายในคือการใช้เซิร์ฟเวอร์ในตัวของ Python

  1. การใช้บรรทัดคำสั่งจากไดเรกทอรีที่มีไฟล์ index.html ที่เรียกใช้
      python -m http.server 8000
    
  2. ในเว็บเบราว์เซอร์ ให้ไปที่ http://localhost:8000/

คุณยังใช้เว็บเซิร์ฟเวอร์อื่น เช่น เซิร์ฟเวอร์ Apache HTTP ได้ด้วย

2. สร้างโปรแกรมเล่นวิดีโอง่ายๆ

ก่อนอื่นให้แก้ไข index.html เพื่อสร้างองค์ประกอบวิดีโอ HTML5 แบบง่ายที่มีอยู่ในองค์ประกอบการตัดข้อความและปุ่มสำหรับเล่น และเพิ่มแท็กที่จําเป็นเพื่อโหลดไฟล์ style.css และ ads.js ด้วย จากนั้นแก้ไข styles.css เพื่อให้โปรแกรมเล่นวิดีโอตอบสนองต่ออุปกรณ์เคลื่อนที่ สุดท้าย ใน ads.js ให้ทริกเกอร์การเล่นวิดีโอเมื่อมีการคลิกปุ่มเล่น

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

หลังจากทำขั้นตอนนี้เสร็จแล้ว เมื่อเปิด index.html ในเบราว์เซอร์ (ผ่านเซิร์ฟเวอร์การพัฒนา) คุณควรจะเห็นองค์ประกอบวิดีโอและควรเริ่มเล่นวิดีโอเมื่อคลิกปุ่มเล่น

3. นำเข้า IMA SDK

จากนั้นเพิ่มเฟรมเวิร์ก IMA โดยใช้แท็กสคริปต์ใน index.html ก่อนแท็กของ 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. แนบหน้าและเครื่องจัดการโปรแกรมเล่นวิดีโอ

หากต้องการแก้ไขลักษณะการทำงานของโปรแกรมเล่นวิดีโอที่มี JavaScript ให้เพิ่มเครื่องจัดการเหตุการณ์ที่ทริกเกอร์การดำเนินการต่อไปนี้

  • เมื่อโหลดหน้าเว็บเสร็จแล้ว ให้เริ่มต้น IMA SDK
  • เมื่อมีการคลิกปุ่มเล่นวิดีโอ ให้โหลดโฆษณา (เว้นแต่มีการโหลดโฆษณาไว้แล้ว)
  • เมื่อปรับขนาดหน้าต่างเบราว์เซอร์ ให้อัปเดตองค์ประกอบวิดีโอและขนาด adsManager เพื่อทำให้หน้าเว็บปรับเปลี่ยนตามอุปกรณ์สำหรับอุปกรณ์เคลื่อนที่
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. สร้างคอนเทนเนอร์โฆษณา

ในเบราว์เซอร์ส่วนใหญ่ IMA SDK ใช้องค์ประกอบคอนเทนเนอร์โฆษณาโดยเฉพาะเพื่อแสดงทั้งโฆษณาและองค์ประกอบ UI ที่เกี่ยวข้องกับโฆษณา คอนเทนเนอร์นี้ต้องมีขนาดเพื่อวางซ้อนองค์ประกอบวิดีโอจากมุมซ้ายบน ความสูงและความกว้างของโฆษณาที่วางในคอนเทนเนอร์นี้กำหนดโดยออบเจ็กต์ adsManager คุณจึงไม่ต้องตั้งค่าเหล่านี้ด้วยตนเอง

หากต้องการใช้องค์ประกอบคอนเทนเนอร์โฆษณานี้ ให้สร้าง div ใหม่ภายในองค์ประกอบ video-container ก่อน จากนั้นอัปเดต CSS ให้วางองค์ประกอบที่มุมบนซ้ายของ video-element สุดท้าย ให้กำหนดตัวแปรสำหรับคอนเทนเนอร์ภายในฟังก์ชัน initializeIMA() ที่ทำงานเมื่อหน้าเว็บโหลด

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. เริ่มต้น AdsLoader และสร้างคำขอโฆษณา

หากต้องการขอชุดโฆษณา ให้สร้างอินสแตนซ์ ima.AdsLoader อินสแตนซ์นี้รับออบเจ็กต์ AdDisplayContainer เป็นอินพุต และสามารถใช้ในการประมวลผลออบเจ็กต์ ima.AdsRequest ที่เชื่อมโยงกับ URL แท็กโฆษณาที่ระบุ แท็กโฆษณาที่ใช้ในตัวอย่างนี้มีโฆษณาตอนต้นความยาว 10 วินาที คุณสามารถทดสอบ URL ของแท็กโฆษณานี้หรือ URL ของแท็กโฆษณาได้โดยใช้ IMA Video Suite Inspector

แนวทางปฏิบัติแนะนำคือให้คง ima.AdsLoader ไว้เพียง 1 อินสแตนซ์ตลอดอายุการใช้งานหน้าเว็บ หากต้องการส่งคำขอโฆษณาเพิ่มเติม ให้สร้างออบเจ็กต์ ima.AdsRequest ใหม่ แต่ใช้ ima.AdsLoader เดิมซ้ำ ดูข้อมูลเพิ่มเติมได้ในคำถามที่พบบ่อยเกี่ยวกับ IMA SDK

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. ฟังเหตุการณ์ AdsLoader

เมื่อโฆษณาโหลดเรียบร้อยแล้ว ima.AdsLoader จะปล่อยเหตุการณ์ ADS_MANAGER_LOADED แยกวิเคราะห์เหตุการณ์ที่ส่งไปยังโค้ดเรียกกลับเพื่อเริ่มต้นออบเจ็กต์ AdsManager AdsManager จะโหลดโฆษณาแต่ละรายการตามที่กำหนดโดยการตอบกลับ URL แท็กโฆษณา

นอกจากนี้ โปรดจัดการข้อผิดพลาดที่อาจเกิดขึ้นระหว่างกระบวนการโหลดด้วย หากโฆษณาไม่โหลด ให้ตรวจสอบว่าการเล่นสื่อดำเนินต่อไปโดยไม่มีโฆษณา เพื่อไม่ให้รบกวนประสบการณ์ของผู้ใช้

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. เริ่มต้น AdsManager

หากต้องการเริ่มเล่นโฆษณา คุณต้องเริ่มเล่น AdsManager ควรทริกเกอร์โดยการโต้ตอบของผู้ใช้เพื่อรองรับเบราว์เซอร์ในอุปกรณ์เคลื่อนที่อย่างเต็มรูปแบบ

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. ทำให้ AdsManager ปรับเปลี่ยนตามอุปกรณ์

หากหน้าจอเปลี่ยนขนาดหรือการวางแนว เหตุการณ์การปรับขนาดหน้าต่างจะต้องเรียกใช้ 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. ฟังเหตุการณ์ของ AdsManager

นอกจากนี้ AdsManager ยังเริ่มการทำงานของหลายเหตุการณ์ที่ต้องจัดการด้วย เหตุการณ์เหล่านี้ใช้เพื่อติดตามการเปลี่ยนแปลงสถานะ ทริกเกอร์การเล่นและหยุดชั่วคราวในวิดีโอเนื้อหา และบันทึกข้อผิดพลาด

การจัดการข้อผิดพลาด

ตัวแฮนเดิลข้อผิดพลาดที่สร้างขึ้นสำหรับ AdsLoader ทำหน้าที่เป็นตัวแฮนเดิลข้อผิดพลาดสำหรับ AdsManager ได้ด้วยการเพิ่มเครื่องจัดการเหตุการณ์ใหม่ที่มีฟังก์ชันเรียกกลับเดียวกัน

ads.js
...

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

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

...

การทริกเกอร์เหตุการณ์เล่นและหยุดชั่วคราว

เมื่อ AdsManager พร้อมแทรกโฆษณาสําหรับ Display เหตุการณ์ CONTENT_PAUSE_REQUESTED จะเริ่มทํางาน โปรดจัดการเหตุการณ์นี้ด้วยการทริกเกอร์การหยุดชั่วคราวในโปรแกรมเล่นวิดีโอที่เกี่ยวข้อง ในทำนองเดียวกัน เมื่อโฆษณาเสร็จสมบูรณ์ เหตุการณ์ AdsManager จะทำให้เหตุการณ์ CONTENT_RESUME_REQUESTED เริ่มทำงาน โปรดจัดการเหตุการณ์นี้โดยการเริ่มเล่นวิดีโอในเนื้อหาที่เกี่ยวข้องอีกครั้ง

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

การทริกเกอร์การคลิกเพื่อหยุดชั่วคราวบนอุปกรณ์เคลื่อนที่

เนื่องจาก AdContainer ซ้อนทับองค์ประกอบวิดีโอ ผู้ใช้จึงโต้ตอบกับโปรแกรมเล่นที่อยู่เบื้องหลังโดยตรงไม่ได้ ซึ่งอาจทำให้ผู้ใช้อุปกรณ์เคลื่อนที่สับสนว่าจะต้องแตะโปรแกรมเล่นวิดีโอเพื่อหยุดเล่นชั่วคราว ในการแก้ปัญหานี้ IMA SDK จะส่งคลิกที่ IMA ไม่ได้จัดการจากการวางซ้อนโฆษณาไปยังองค์ประกอบ AdContainer ซึ่งสามารถจัดการได้ แต่ไม่ได้ใช้กับโฆษณาเชิงเส้นในเบราว์เซอร์ที่ไม่ใช่อุปกรณ์เคลื่อนที่ เนื่องจากการคลิกโฆษณาจะเปิด ลิงก์การคลิกผ่าน

หากต้องการใช้การคลิกเพื่อหยุดชั่วคราว ให้เพิ่มเครื่องจัดการการคลิกลงใน AdContainer และเรียกใช้การเล่นหรือหยุดเหตุการณ์ชั่วคราวในวิดีโอต้นฉบับ

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

...

การทริกเกอร์ให้เล่นโฆษณาที่ปรากฏร่วมกับวิดีโอ

AdsManager จะหยุดวิดีโอเนื้อหาไว้ชั่วคราวเมื่อโฆษณาพร้อมเล่น แต่ลักษณะการทำงานนี้ไม่ได้รวมถึงโฆษณาที่ไม่ใช่เชิงเส้น ซึ่งเนื้อหาควรเล่นต่อไปขณะแสดงโฆษณา หากต้องการรองรับโฆษณาที่ไม่ใช่เชิงเส้น ให้รอฟัง AdsManager เพื่อปล่อยเหตุการณ์ LOADED จากนั้น ให้ตรวจสอบว่าโฆษณาเป็นแบบเชิงเส้นหรือไม่ หากไม่ใช่ ให้เล่นต่อในองค์ประกอบวิดีโอ

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

เท่านี้ก็เรียบร้อย คุณกำลังขอและแสดงโฆษณาด้วย IMA SDK หากต้องการดูข้อมูลเกี่ยวกับฟีเจอร์ SDK ขั้นสูงเพิ่มเติม โปรดดูคำแนะนำอื่นๆ หรือตัวอย่างใน GitHub