IMA SDK را تنظیم کنید

پلتفرم مورد نظر را انتخاب کنید: HTML5 اندروید iOS tvOS

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

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

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

پیاده‌سازی IMA سمت کلاینت شامل چهار جزء اصلی SDK است که در این راهنما نشان داده شده‌اند:

  • AdDisplayContainer : یک شیء کانتینر که مشخص می‌کند IMA عناصر رابط کاربری تبلیغات را کجا رندر می‌کند و قابلیت مشاهده، از جمله نمای فعال و اندازه‌گیری باز را اندازه‌گیری می‌کند.
  • AdsLoader : شیء‌ای که تبلیغات را درخواست می‌کند و رویدادهای پاسخ به درخواست تبلیغات را مدیریت می‌کند. شما فقط باید یک بارگذار تبلیغات را نمونه‌سازی کنید که می‌تواند در طول عمر برنامه بارها مورد استفاده قرار گیرد.
  • AdsRequest : شیء‌ای که یک درخواست تبلیغات را تعریف می‌کند. درخواست‌های تبلیغات، URL مربوط به تگ تبلیغ VAST و همچنین پارامترهای اضافی مانند ابعاد تبلیغ را مشخص می‌کنند.
  • AdsManager : شیء‌ای که شامل پاسخ به درخواست تبلیغات است، پخش تبلیغات را کنترل می‌کند و به رویدادهای تبلیغاتی که توسط SDK ایجاد می‌شوند، گوش می‌دهد.

پیش‌نیازها

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

  • سه فایل خالی:
    • فهرست.html
    • استایل.css
    • تبلیغات.js
  • پایتون نصب شده روی رایانه شما، یا یک وب سرور برای استفاده جهت آزمایش

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

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

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

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

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

ابتدا، فایل index.html را تغییر دهید تا یک عنصر ویدیوی HTML5 ساده، شامل یک عنصر پوششی، و یک دکمه برای شروع پخش ایجاد شود. مثال زیر IMA SDK را وارد می‌کند و عنصر کانتینر AdDisplayContainer را تنظیم می‌کند. برای جزئیات بیشتر، به ترتیب به مراحل Import the IMA SDK و Create the ad container مراجعه کنید. 

<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() است که در بخش Initialize the AdsLoader and make an ads request تعریف شده است.

۳. IMA SDK را وارد کنید

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

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

۴. ایجاد بخش تبلیغات

در اکثر مرورگرها، IMA SDK از یک عنصر محفظه تبلیغات اختصاصی برای نمایش تبلیغات و عناصر رابط کاربری مرتبط با تبلیغات استفاده می‌کند. این محفظه باید به گونه‌ای طراحی شود که عنصر ویدیو را از گوشه بالا سمت چپ بپوشاند. ارتفاع و عرض تبلیغات قرار داده شده در این محفظه توسط شیء 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

۵. AdsLoader را راه‌اندازی اولیه کنید و یک درخواست تبلیغات ارسال کنید

برای درخواست تبلیغات، یک نمونه AdsLoader ایجاد کنید. سازنده AdsLoader یک شیء AdDisplayContainer به عنوان ورودی دریافت می‌کند و می‌تواند برای پردازش اشیاء AdsRequest مرتبط با یک URL تگ تبلیغ مشخص شده استفاده شود. تگ تبلیغ استفاده شده در این مثال شامل یک تبلیغ 10 ثانیه‌ای قبل از پخش است. می‌توانید این یا هر URL تگ تبلیغ را با استفاده از IMA Video Suite Inspector آزمایش کنید.

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

با استفاده از 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, 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&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

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

وقتی AdsLoader با موفقیت تبلیغات را بارگذاری می‌کند، رویداد ADS_MANAGER_LOADED را منتشر می‌کند. رویداد ارسالی به تابع فراخوانی را تجزیه کنید تا شیء 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

برای جزئیات بیشتر در مورد شنونده‌های تنظیم‌شده در تابع 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

۷. فعال کردن قابلیت کلیک برای مکث در دستگاه‌های تلفن همراه

از آنجایی که AdContainer عنصر ویدیو را پوشش می‌دهد، کاربران نمی‌توانند مستقیماً با پخش‌کننده‌ی زیرین تعامل داشته باشند. این می‌تواند کاربران دستگاه‌های تلفن همراه را که انتظار دارند بتوانند برای مکث پخش، روی پخش‌کننده‌ی ویدیو ضربه بزنند، گیج کند. برای رفع این مشکل، IMA SDK هر کلیکی را که توسط 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();
  }
}
ads.js

۸. مدیریت تبلیغات (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

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

برای اینکه تبلیغات به صورت پویا تغییر اندازه دهند و با اندازه پخش‌کننده ویدیو مطابقت داشته باشند، یا با تغییرات جهت صفحه نمایش مطابقت داشته باشند، در پاسخ به رویدادهای تغییر اندازه پنجره، تابع 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 مراجعه کنید.