หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

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

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

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

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

ใช้บรรทัดคำสั่งจากไดเรกทอรีที่มีไฟล์ index.html แล้วเรียกใช้คำสั่งต่อไปนี้
```
  python -m http.server 8000
```
หมายเหตุ: http.server พร้อมใช้งานใน Python 3.x เท่านั้น
ในเว็บเบราว์เซอร์ ให้ไปที่ 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

ในเบราว์เซอร์ส่วนใหญ่ 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ไว้เพียง 1 อินสแตนซ์ตลอดอายุการใช้งานของหน้าเว็บ หากต้องการส่งคําขอโฆษณาเพิ่มเติม ให้สร้างออบเจ็กต์ AdsRequest ใหม่ แต่ใช้ AdsLoader เดิมซ้ำ ดูข้อมูลเพิ่มเติมได้ที่คำถามที่พบบ่อยเกี่ยวกับ IMA SDK

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

ADS_MANAGER_LOADED
AD_ERROR

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

/**
 * 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&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 = 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

ดูรายละเอียดเพิ่มเติมเกี่ยวกับ Listeners ที่ตั้งค่าไว้ในฟังก์ชัน 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() click handler ที่เรียกใช้ ใน Listener ของ on window load

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