เริ่มเลย

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

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

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

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

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

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

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

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

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

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

  1. ใช้บรรทัดคำสั่งจากไดเรกทอรีที่มี ไฟล์ดัชนี.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

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

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