ตั้งค่า IMA SDK

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

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

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

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

  • AdDisplayContainer: ออบเจ็กต์คอนเทนเนอร์ที่ระบุตําแหน่งที่ IMA แสดงผลองค์ประกอบ UI ของโฆษณาและวัดการมองเห็นโฆษณา รวมถึงมุมมองแอ็กทีฟและ Open Measurement
  • AdsLoader: ออบเจ็กต์ที่ขอโฆษณาและจัดการเหตุการณ์จากการตอบกลับคำขอโฆษณา คุณควรสร้างอินสแตนซ์ของ AdLoader เพียงรายการเดียว ซึ่งสามารถนำกลับมาใช้ใหม่ได้ตลอดอายุการใช้งานของแอปพลิเคชัน
  • 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 อย่างง่ายซึ่งอยู่ในองค์ประกอบ ที่ห่อหุ้ม และปุ่มเพื่อทริกเกอร์การเล่น ตัวอย่างต่อไปนี้นำเข้า 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>

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

เพิ่มแท็กที่จำเป็นเพื่อโหลดไฟล์ 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>
index.html

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

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

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

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

แนวทางปฏิบัติแนะนำคือให้คงอินสแตนซ์ของ 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);
}
ads.js

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

เมื่อ AdsLoader โหลดโฆษณาสำเร็จ ระบบจะปล่อยเหตุการณ์ ADS_MANAGER_LOADED แยกวิเคราะห์เหตุการณ์ที่ส่งไปยัง Callback เพื่อเริ่มต้นออบเจ็กต์ 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();
}
ads.js

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

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

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

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

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

เมื่อ 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);
ads.js

ดูคำจำกัดความของฟังก์ชัน 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();
}
ads.js

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

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

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

หากต้องการรองรับโฆษณาแบบไม่เชิงเส้น ให้รอ 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();
  }
}
ads.js

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

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

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);
  }
});
ads.js

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