ตั้งค่า IMA SDK

เลือกแพลตฟอร์ม: HTML5 Android iOS tvOS

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

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

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

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

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

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

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

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

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

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

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

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

2. สร้างวิดีโอเพลเยอร์อย่างง่าย

ขั้นแรก ให้แก้ไข index.html เพื่อสร้างองค์ประกอบวิดีโอ HTML5 อย่างง่ายซึ่งอยู่ในองค์ประกอบ Wrapper และปุ่มเพื่อทริกเกอร์การเล่น ตัวอย่างต่อไปนี้จะนำเข้า IMA SDK และตั้งค่า องค์ประกอบคอนเทนเนอร์ AdDisplayContainer ดูรายละเอียดเพิ่มเติมได้ในขั้นตอนการนำเข้า IMA SDK และสร้างคอนเทนเนอร์โฆษณาตามลำดับ 

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

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

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

โปรดทราบว่าข้อมูลโค้ด ads.js มีการเรียกใช้ setUpIMA() ซึ่งกำหนดไว้ในส่วน เริ่มต้นใช้งาน AdsLoader และส่งคำขอโฆษณา

3. นำเข้า IMA SDK

จากนั้นเพิ่มเฟรมเวิร์ก IMA โดยใช้แท็กสคริปต์ใน index.html ก่อนแท็กสำหรับ ads.js 

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

4. สร้างคอนเทนเนอร์โฆษณา

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

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

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

5. เริ่มต้นใช้งาน AdsLoader และส่งคำขอโฆษณา

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

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

รอและตอบสนองต่อเหตุการณ์โฆษณาที่โหลดและข้อผิดพลาดโดยใช้ AdsLoader.addEventListener รอเหตุการณ์ต่อไปนี้

  • ADS_MANAGER_LOADED
  • AD_ERROR

หากต้องการสร้าง Listener onAdsManagerLoaded() และ onAdError() โปรดดูตัวอย่างต่อไปนี้ 

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

6. ตอบสนองต่อเหตุการณ์ AdsLoader

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

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

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

ดูรายละเอียดเพิ่มเติมเกี่ยวกับ Listener ที่ตั้งค่าไว้ในฟังก์ชัน onAdsManagerLoaded() ได้ในส่วนย่อยต่อไปนี้

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

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

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

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

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

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

ดูคำจำกัดความของฟังก์ชัน onContentPauseRequested() และ onContentResumeRequested() ได้ในตัวอย่างต่อไปนี้ 

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

จัดการการเล่นเนื้อหาระหว่างโฆษณาที่ปรากฏร่วมกับเนื้อหา

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

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

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

ดูคำจำกัดความของฟังก์ชัน onAdLoaded() ได้ในตัวอย่างต่อไปนี้ 

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

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

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

หากต้องการติดตั้งใช้งานการคลิกเพื่อหยุดชั่วคราว ให้เพิ่มฟังก์ชันตัวแฮนเดิลการคลิก adContainerClick() ที่เรียกใช้ ใน Listener การโหลดหน้าต่าง 

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

8. เริ่ม AdsManager

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

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

9. รองรับการปรับขนาดเพลเยอร์

หากต้องการให้โฆษณาปรับขนาดแบบไดนามิกและให้ตรงกับขนาดของวิดีโอเพลเยอร์ หรือให้ตรงกับการเปลี่ยนแปลงการวางแนวหน้าจอ ให้เรียกใช้ adsManager.resize() เพื่อตอบสนองต่อเหตุการณ์การปรับขนาดหน้าต่าง 

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

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