راه‌اندازی کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی

انتخاب پلاتفرم: HTML5 Android iOS tvOS

کیت‌های توسعه نرم‌افزار IMA ادغام آگهی‌های چندرسانه‌ای را در وب‌سایت‌ها و برنامه‌هایتان آسان می‌کند. کیت‌های توسعه نرم‌افزار IMA می‌توانند از هر سرور آگهی سازگار با VAST درخواست آگهی کنند و بازپخش آگهی را در برنامه‌هایتان مدیریت کنند. با کیت‌های توسعه نرم‌افزار سمت کارخواه IMA، کنترل بازپخش ویدیو محتوا را حفظ می‌کنید، درحالی‌که کیت توسعه نرم‌افزار بازپخش آگهی را مدیریت می‌کند. آگهی‌ها در پخش‌کننده ویدیو جداگانه‌ای که روی پخش‌کننده ویدیو محتوای برنامه قرار دارد پخش می‌شوند.

این راهنما نشان می‌دهد که چگونه IMA SDK را در یک برنامه پخش‌کننده ویدیو ساده ادغام کنید. اگر می‌خواهید یکپارچه‌سازی نمونه تکمیل‌شده را مشاهده کنید یا با آن همراه شوید، نمونه ساده را از GitHub بارگیری کنید. اگر به پخش‌کننده HTML5 با کیت توسعه نرم‌افزار ازپیش ادغام‌شده علاقه دارید، افزونه IMA SDK برای Video.js را بررسی کنید.

نمای کلی سمت کارخواه IMA

پیاده‌سازی سمت کارخواه IMA شامل چهار عنصر اصلی کیت توسعه نرم‌افزار است که در این راهنما نشان داده شده است:

  • AdDisplayContainer: شیء نگهدارنده‌ای که مشخص می‌کند IMA عناصر میانای کاربر آگهی را کجا ارائه دهد و قابلیت مشاهده را اندازه‌گیری کند، ازجمله Active View و Open Measurement.
  • ‫ AdsLoader: شیئی که آگهی‌ها را درخواست می‌کند و رویدادها را از پاسخ‌های درخواست آگهی مدیریت می‌کند. باید فقط یک بارگذارنده آگهی را نمونه‌سازی کنید که بتواند درطول عمر برنامه دوباره استفاده شود.
  • AdsRequest: شیئی که درخواست آگهی را تعریف می‌کند. درخواست‌های آگهی نشانی وب برچسب آگهی VAST و همچنین پارامترهای اضافی، مانند ابعاد آگهی را مشخص می‌کنند.
  • AdsManager: شیئی که حاوی پاسخ به درخواست آگهی است، بازپخش آگهی را کنترل می‌کند، و به رویدادهای آگهی که توسط کیت توسعه نرم‌افزار راه‌اندازی شده‌اند گوش می‌دهد.

پیش‌نیازها

قبل‌از شروع، به موارد زیر نیاز دارید:

  • سه فایل خالی:
    • index.html
    • style.css
    • ads.js
  • ‫Python در رایانه‌تان نصب شده باشد، یا سرور وبی برای استفاده در آزمایش داشته باشید

۱. راه‌اندازی سرور توسعه

ازآنجایی‌که IMA SDK وابستگی‌ها را بااستفاده از همان پروتکل صفحه‌ای که از آن بارگیری شده است بارگیری می‌کند، باید از یک سرور وب برای آزمایش برنامه‌تان استفاده کنید. ساده‌ترین راه برای راه‌اندازی یک سرور توسعه محلی استفاده از سرور داخلی Python است.

  1. بااستفاده از خط فرمان، از دایرکتوری که فایل index.html شما را دربرمی‌گیرد، این دستور را اجرا کنید: 
      python -m http.server 8000
  2. در مرورگر وب، به http://localhost:8000/ بروید

همچنین می‌توانید از هر سرور وب دیگری، مانند Apache HTTP Server استفاده کنید.

۲. ایجاد یک پخش‌کننده ویدیو ساده

ابتدا، index.html را تغییر دهید تا عنصر ویدیو HTML5 ساده‌ای ایجاد کنید که در عنصر پیچیده شده است و دکمه‌ای برای راه‌اندازی بازپخش ایجاد کنید. مثال زیر IMA SDK را وارد می‌کند و عنصر محتوی AdDisplayContainer را راه‌اندازی می‌کند. برای جزئیات بیشتر، مراحل وارد کردن «کیت توسعه نرم‌افزار IMA» و ایجاد ظرف آگهی را به‌ترتیب ببینید. 

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

#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;
}
 
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();
});

برچسب‌های لازم را برای بار کردن فایل‌های style.css و ads.js اضافه کنید. سپس، styles.css را اصلاح کنید تا پخش‌کننده ویدیو برای دستگاه‌های همراه واکنش‌گرا شود. درنهایت، در ads.js، متغیرهایتان را اعلام کنید و بازپخش ویدیو را هنگام کلیک کردن روی دکمه پخش راه‌اندازی کنید.

توجه داشته باشید که تکه‌کد ads.js حاوی فراخوانی برای setUpIMA() است که در بخش «مقداردهی اولیه AdsLoader و درخواست آگهی» تعریف شده است.

۳. وارد کردن کیت توسعه نرم‌افزار IMA

سپس، چارچوب IMA را بااستفاده از برچسب نوشتاری در index.html، قبل‌از برچسب ads.js اضافه کنید. 

<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>

۴. ساختن محتوی آگهی

در اکثر مرورگرها، «کیت توسعه نرم‌افزار IMA» از عنصر ظرف آگهی اختصاصی برای نمایش آگهی‌ها و عناصر رابط کاربری مربوط به آگهی استفاده می‌کند. اندازه این محتوی باید به‌گونه‌ای باشد که عنصر ویدیو را از گوشه بالا سمت چپ رونهاد کند. ارتفاع و عرض آگهی‌های قرارگرفته در این محفظه توسط شیء adsManager تنظیم می‌شود، بنابراین نیازی نیست این مقادیر را به‌صورت دستی تنظیم کنید.

برای پیاده‌سازی این عنصر محتوی آگهی، ابتدا div جدیدی را در عنصر video-container ایجاد کنید. سپس «سی‌اس‌اس» را به‌روز کنید تا عنصر را در گوشه بالا سمت چپ video-element قرار دهد. درنهایت، تابع createAdDisplayContainer() را اضافه کنید تا شیء AdDisplayContainer بااستفاده از محفظه آگهی جدید div ایجاد شود. 

<div id="adContainer"></div>
 
#adContainer {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}
 
/**
 * Sets the 'adContainer' div as the IMA ad display container.
 */
function createAdDisplayContainer() {
  adDisplayContainer = new google.ima.AdDisplayContainer(
      document.getElementById('adContainer'), videoContent);
}

۵. ‫AdsLoader را مقداردهی اولیه کنید و درخواست آگهی کنید

برای درخواست آگهی، نمونه‌ای از AdsLoader ایجاد کنید. سازنده AdsLoader شیء AdDisplayContainer را به‌عنوان ورودی می‌گیرد و می‌تواند برای پردازش AdsRequest اشیای مرتبط با نشانی وب برچسب آگهی مشخص‌شده استفاده شود. برچسب آگهی استفاده‌شده در این مثال حاوی آگهی پیش‌پخش ۱۰ ثانیه‌ای است. می‌توانید این نشانی وب برچسب آگهی یا هر نشانی وب دیگری را بااستفاده از بازرس مجموعه ویدیو IMA آزمایش کنید.

به‌عنوان روالی مطلوب، فقط یک نمونه از AdsLoader را برای کل چرخه حیات صفحه حفظ کنید. برای درخواست‌های آگهی بیشتر، AdsRequest جدیدی بسازید، اما از همان AdsLoader استفاده مجدد کنید. برای اطلاعات بیشتر، به پرسشگان کیت توسعه نرم‌افزار IMA مراجعه کنید.

بااستفاده از AdsLoader.addEventListener، به رویدادهای خطا و آگهی‌های بارشده گوش دهید و پاسخ دهید. به رویدادهای زیر گوش دهید:

  • ADS_MANAGER_LOADED
  • AD_ERROR

برای ایجاد شنوندگان 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);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError);

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

‫۶. پاسخ دادن به رویدادهای AdsLoader

وقتی AdsLoader آگهی‌ها را با موفقیت بار می‌کند، رویداد ADS_MANAGER_LOADED را منتشر می‌کند. رویداد ارسال‌شده به برگشت‌تماس را تجزیه کنید تا شیء AdsManager را مقداردهی اولیه کنید. AdsManager آگهی‌های تکی را همان‌طور که در پاسخ به نشانی وب برچسب آگهی تعریف شده است بار می‌کند.

مطمئن شوید که هر خطایی که درطول فرایند بار کردن رخ می‌دهد را مدیریت می‌کنید. اگر آگهی‌ها بار نمی‌شوند، مطمئن شوید که بازپخش رسانه بدون آگهی ادامه می‌یابد تا تداخلی در مشاهده محتوا توسط کاربر ایجاد نشود. 

/**
 * 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();
}

برای جزئیات بیشتر درباره شنوندگان تنظیم‌شده در تابع onAdsManagerLoaded()، زیربخش‌های زیر را ببینید:

مدیریت AdsManager خطا

مدیر خطای ایجادشده برای AdsLoader می‌تواند به‌عنوان مدیر خطا برای AdsManager نیز عمل کند. ببینید که مدیریت‌کننده رویداد چگونه از تابع onAdError() استفاده مجدد می‌کند. 

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

مدیریت رویدادهای پخش و مکث

وقتی 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);

برای تعریف‌های تابع‌های 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();
}

مدیریت پخش محتوا درطول آگهی‌های غیرخطی

‫AdsManager وقتی آگهی آماده پخش است، ویدیو محتوا را موقتاً متوقف می‌کند، اما این رفتار آگهی‌های غیرخطی را درنظر نمی‌گیرد، که در آن محتوا همچنان پخش می‌شود درحالی‌که آگهی نمایش داده می‌شود. 

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

برای پشتیبانی از آگهی‌های غیرخطی، به 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();
  }
}

‫۷. راه‌اندازی کلیک برای توقف موقت در دستگاه‌های همراه

ازآنجاکه AdContainer روی عنصر ویدیو قرار می‌گیرد، کاربران نمی‌توانند مستقیماً با پخش‌کننده زیرین تعامل داشته باشند. این می‌تواند کاربران دستگاه‌های همراه را که انتظار دارند بتوانند با تک‌ضرب زدن روی پخش‌کننده ویدیو، بازپخش را موقتاً متوقف کنند، گیج کند. برای رفع این مشکل، «کیت توسعه نرم‌افزار IMA» هر کلیکی را که توسط IMA از رونهاد آگهی به عنصر AdContainer منتقل می‌شود، مدیریت می‌کند. این موضوع برای آگهی‌های خطی در مرورگرهای غیرتلفن همراه اعمال نمی‌شود، زیرا کلیک کردن روی آگهی، پیوند کلیک مستقیم را باز می‌کند.

برای پیاده‌سازی کلیک برای مکث، تابع مدیریت‌کننده کلیک adContainerClick() را که در شنونده بار پنجره نامیده می‌شود اضافه کنید. 

/**
 * 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();
  }
}

‫۸. شروع 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();
  }
}

‫۹. پشتیبانی از تغییر اندازه پخش‌کننده

برای اینکه آگهی‌ها به‌طور پویا تغییر اندازه دهند و با اندازه پخش‌کننده ویدیو مطابقت داشته باشند، یا با تغییرات جهت صفحه مطابقت داشته باشند، 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);
  }
});

فقط همین! اکنون با «کیت توسعه نرم‌افزار IMA» آگهی درخواست و نمایش می‌دهید. برای آشنایی با ویژگی‌های پیشرفته‌تر SDK، به راهنماهای دیگر یا نمونه‌های موجود در GitHub مراجعه کنید.