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

เริ่มต้น

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

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

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

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

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

สิ่งที่ต้องดำเนินการก่อน

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

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

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

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

ใช้บรรทัดคําสั่งจากไดเรกทอรีที่มีไฟล์ index.html ต่อไปนี้
```
  python -m http.server 8000
```
หมายเหตุ: http.server ใช้ได้เฉพาะใน Python 3.x
ในเว็บเบราว์เซอร์ ให้ไปที่ http://localhost:8000/

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

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

ในเบราว์เซอร์ส่วนใหญ่ 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 แท็กโฆษณาได้โดยใช้เครื่องมือตรวจสอบชุดวิดีโอ IMA

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

เริ่มต้น

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

สิ่งที่ต้องดำเนินการก่อน

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

2. สร้างโปรแกรมเล่นวิดีโอแบบง่าย

3. นําเข้า IMA SDK

4. แนบเครื่องจัดการหน้าเว็บและโปรแกรมเล่นวิดีโอ

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

6. เริ่มต้น AdsLoader และส่งคําขอโฆษณา

7. ฟังเหตุการณ์ AdsLoader

8. เริ่มต้น AdsManager

9. ทําให้ AdsManager ปรับเปลี่ยนตามพื้นที่โฆษณา

10. ฟังเหตุการณ์ AdsManager

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

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

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

การเรียกการเล่นในโฆษณาที่ไม่ใช่เชิงเส้น