این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

شروع کنید

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

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

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

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

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

پیش نیازها

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

سه فایل خالی:
- index.html
- style.css
- ads.js
پایتون بر روی رایانه شما نصب شده یا یک وب سرور برای آزمایش استفاده کنید

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

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

با استفاده از یک خط فرمان، از دایرکتوری که حاوی فایل index.html شما است، اجرا کنید:
```
  python -m http.server 8000
```
توجه: http.server فقط در پایتون 3.x موجود است.
در یک مرورگر وب، به 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. صفحه و کنترل کننده های پخش کننده ویدیو را ضمیمه کنید

برای تغییر رفتار پخش‌کننده ویدیو با جاوا اسکریپت، کنترل‌کننده‌های رویداد را اضافه کنید که اقدامات زیر را فعال می‌کنند:

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

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

شروع کنید

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

پیش نیازها

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

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

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

4. صفحه و کنترل کننده های پخش کننده ویدیو را ضمیمه کنید

5. ظرف تبلیغات را ایجاد کنید

6. AdsLoader را مقداردهی اولیه کنید و درخواست تبلیغات کنید

7. به رویدادهای AdsLoader گوش دهید

8. AdsManager را راه اندازی کنید

9. AdsManager را پاسخگو کنید

10. به رویدادهای AdsManager گوش دهید

رسیدگی به خطاها

فعال کردن رویدادهای پخش و توقف

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

شروع بازی در تبلیغات غیر خطی