เริ่มใช้งาน

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 จะโหลดทรัพยากร Dependency ผ่านโปรโตคอลเดียวกับหน้าที่โหลด คุณต้องใช้สําหรับทดสอบแอป วิธีเริ่มต้นเซิร์ฟเวอร์การพัฒนาในเครื่องที่ง่ายที่สุดคือการใช้เซิร์ฟเวอร์ในตัวของ Python

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

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

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 แท็กโฆษณาอื่นๆ โดยใช้เครื่องมือตรวจสอบ Video Suite ของ IMA

แนวทางปฏิบัติแนะนำคือให้คง 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 แยกวิเคราะห์เหตุการณ์ที่ส่งไปยัง Callback เพื่อเริ่มต้นออบเจ็กต์ 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 พร้อมที่จะแทรกโฆษณาเพื่อแสดง ระบบจะเรียกเหตุการณ์ 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