Başlama

IMA SDK'ları, multimedya reklamları web sitelerinize ve uygulamalarınıza entegre etmenizi kolaylaştırır. IMA SDK'ları, VAST uyumlu reklam sunucularından reklam isteyebilir ve uygulamalarınızda reklam oynatmayı yönetebilir. IMA istemci tarafı SDK'ları ile içeriklerin video oynatmasının kontrolü sizdeyken SDK reklam oynatma işlemini gerçekleştirir. Reklamlar, uygulamanın içerik video oynatıcısının üst kısmında yer alan ayrı bir video oynatıcıda oynatılır.

Bu kılavuzda, IMA SDK'nın basit bir video oynatıcı uygulamasına nasıl entegre edileceği gösterilmektedir. Örnek bir entegrasyonla görüntülemek veya takip etmek isterseniz GitHub'dan basit örneği indirin. SDK'sı önceden entegre edilmiş bir HTML5 oynatıcıyla ilgileniyorsanız Video.js için IMA SDK Eklentisi'ne göz atın.

IMA istemci tarafına genel bakış

IMA istemci tarafını uygulama, bu kılavuzda gösterilen dört ana SDK bileşeni içerir:

  • AdDisplayContainer: Reklamların oluşturulduğu bir kapsayıcı nesnesi.
  • AdsLoader: Reklam isteğinde bulunan ve reklam isteği yanıtlarından gelen etkinlikleri işleyen bir nesnedir. Uygulamanın kullanım süresi boyunca tekrar kullanılabilecek bir reklam yükleyicisi kullanmanız gerekir.
  • AdsRequest: Reklam isteğini tanımlayan bir nesne. Reklam istekleri, VAST reklam etiketinin URL'sinin yanı sıra reklam boyutları gibi ek parametreleri de belirtir.
  • AdsManager: Reklam isteğine verilen yanıtı içeren, reklam oynatmayı kontrol eden ve SDK tarafından tetiklenen reklam etkinliklerini dinleyen bir nesnedir.

Ön koşullar

Başlamadan önce şunlara ihtiyacınız olacaktır:

  • Üç boş dosya:
    • index.html
    • style.css
    • ads.js
  • Test için kullanılacak bir Python veya bilgisayarınızda yüklü bir web sunucusu

1. Geliştirme sunucusu başlatma

IMA SDK, bağımlılıkları yüklendiği sayfayla aynı protokol aracılığıyla yüklediğinden uygulamanızı test etmek için bir web sunucusu kullanmanız gerekir. Yerel bir geliştirme sunucusu başlatmanın en basit yolu, Python'un yerleşik sunucusunu kullanmaktır.

  1. Directory.html dosyanızı içeren dizinden bir komut satırı kullanarak şu komutu çalıştırın: 
      python -m http.server 8000
  2. Web tarayıcısında http://localhost:8000/ adresine gidin

Apache HTTP Server gibi başka bir web sunucusunu da kullanabilirsiniz.

2. Basit bir video oynatıcı oluşturma

Öncelikle index.html dosyasını, bir sarmalama öğesinde bulunan basit bir HTML5 video öğesi ve oynatmayı tetikleyecek bir düğme oluşturacak şekilde değiştirin. style.css ve ads.js dosyalarını yüklemek için gerekli etiketleri de ekleyin. Ardından, styles.css dosyasını, video oynatıcıyı mobil cihazlara uyumlu hale getirecek şekilde değiştirin. Son olarak, ads.js'de oynat düğmesi tıklandığında video oynatmayı tetikler.

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

Bu adımı tamamladıktan sonra, index.html dosyasını tarayıcınızda (geliştirme sunucunuz aracılığıyla) açtığınızda, video öğesini görebilmeniz ve oynat düğmesini tıkladığınızda video başlaması gerekir.

3. IMA SDK'yı içe aktarma

Daha sonra, index.html dosyasında ads.js etiketinin önüne, bir komut dosyası etiketi kullanarak IMA çerçevesini ekleyin.

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. Sayfa ve video oynatıcı işleyicileri ekle

Video oynatıcının davranışını JavaScript ile değiştirmek için aşağıdaki işlemleri tetikleyen etkinlik işleyiciler ekleyin:

  • Sayfanın yüklenmesi tamamlandığında IMA SDK'yı başlatın.
  • Video oynat düğmesi tıklandığında reklamları yükleyin (zaten yüklenmiş reklamlar yoksa).
  • Tarayıcı penceresi yeniden boyutlandırıldığında sayfayı mobil cihazlara duyarlı hale getirmek için video öğesini ve adsManager boyutlarını güncelleyin
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. Reklam kapsayıcısını oluşturma

Çoğu tarayıcıda, IMA SDK hem reklamları hem de reklamla ilgili kullanıcı arayüzü öğelerini görüntülemek için özel bir reklam kapsayıcı öğesi kullanır. Bu kapsayıcı, video öğesinin sol üst köşeden yerleştirilmesi için boyuta sahip olmalıdır. Bu kapsayıcıya yerleştirilen reklamların yüksekliği ve genişliği adsManager nesnesi tarafından ayarlanır. Dolayısıyla bu değerleri manuel olarak ayarlamanıza gerek yoktur.

Bu reklam kapsayıcı öğesini uygulamak için önce video-container öğesi içinde yeni bir div oluşturun. Ardından, öğeyi video-element öğesinin sol üst köşesine getirmek için CSS'yi güncelleyin. Son olarak, initializeIMA() işlevi içinde, sayfa yüklendiğinde çalışan kapsayıcı için bir değişken tanımlayın.

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'ı başlatma ve reklam isteğinde bulunma

Bir reklam grubu istemek için bir ima.AdsLoader örneği oluşturun. Bu örnek, giriş olarak bir AdDisplayContainer nesnesini alır ve belirtilen bir reklam etiketi URL'si ile ilişkilendirilmiş ima.AdsRequest nesnelerini işlemek için kullanılabilir. Bu örnekte kullanılan reklam etiketi, 10 saniyelik videodan önce gösterilen reklam içermektedir. Bunu veya herhangi bir reklam etiketi URL'sini IMA Video Ürün Paketi Denetleyicisi'ni kullanarak test edebilirsiniz.

En iyi uygulama olarak bir sayfanın tüm yaşam döngüsü boyunca yalnızca bir ima.AdsLoader örneği sağlayın. Ek reklam istekleri yapmak için yeni bir ima.AdsRequest nesnesi oluşturun ancak aynı ima.AdsLoader nesnesini yeniden kullanın. Daha fazla bilgi için IMA SDK ile ilgili SSS bölümüne bakın.

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

Reklamlar başarıyla yüklendiğinde, ima.AdsLoader bir ADS_MANAGER_LOADED etkinliği yayınlar. AdsManager nesnesini başlatmak için geri çağırmaya iletilen etkinliği ayrıştırın. AdsManager, reklamları reklam etiketi URL'sine verilen yanıtın tanımlandığı şekilde tek tek yükler.

Ayrıca, yükleme işlemi sırasında oluşabilecek hataları ele aldığınızdan emin olun. Reklamlar yüklenmezse medya oynatmanın kullanıcı deneyimini etkilememek için reklamsız olarak devam ettiğinden emin olun.

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'ı başlatın

Reklam oynatmaya başlamak için AdsManager uzantısını başlatmanız gerekiyor. Mobil tarayıcıların tam olarak desteklenmesi için bunun bir kullanıcı etkileşimi tarafından tetiklenmesi gerekir.

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'ı duyarlı hale getirme

Reklamların, video oynatıcının boyutuyla eşleşecek şekilde dinamik olarak yeniden boyutlandırılmasını sağlamak için, ekranın boyutu veya yönü değişirse pencere yeniden boyutlandırma etkinliği adsManager.resize() değerini çağırmalıdır.

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

AdsManager, işlenmesi gereken çeşitli etkinlikleri de tetikler. Bu etkinlikler; durum değişikliklerini izlemek, içerik videosunda oynatma ve duraklatma işlemini tetiklemek ve hataları kaydetmek için kullanılır.

Hataları işleme

AdsLoader için oluşturulan hata işleyici, aynı geri çağırma işlevine sahip yeni bir etkinlik işleyici ekleyerek AdsManager için hata işleyici görevi görebilir.

ads.js 
...

function onAdsManagerLoaded(adsManagerLoadedEvent) {
  adsManager = adsManagerLoadedEvent.getAdsManager(
      videoElement);

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

...

Oynatma ve duraklatma etkinliklerini tetikleme

AdsManager, gösterilmek üzere reklam eklemeye hazır olduğunda CONTENT_PAUSE_REQUESTED etkinliğini tetikler. Temel video oynatıcıda bir duraklatma tetikleyerek bu etkinliği yönetin. Benzer şekilde, bir reklam tamamlandığında AdsManager, CONTENT_RESUME_REQUESTED etkinliğini tetikler. Temel içerik videosunda oynatmayı yeniden başlatarak bu etkinliği yönetin.

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

Mobil cihazlarda tıkla ve duraklat özelliğini tetikleme

AdContainer, video öğesinin üzerine geldiğinden kullanıcılar alttaki oynatıcıyla doğrudan etkileşime geçemez. Bu durum, oynatmayı duraklatmak için video oynatıcıya dokunabilmeyi bekleyen mobil cihaz kullanıcıları için kafa karışıklığı yaratabilir. IMA SDK, bu sorunu gidermek için IMA SDK tarafından işlenmeyen tıklamaları reklam yer paylaşımından AdContainer öğesine iletir. Burada bu öğeler işlenebilir. Reklam tıklandığında tıklama bağlantısı açılacağından, bu durum mobil olmayan tarayıcılardaki doğrusal reklamlar için geçerli değildir.

Tıkla ve duraklat özelliğini uygulamak için AdContainer öğesine bir tıklama işleyici ekleyin ve temel videoda oynatma veya duraklatma etkinliklerini tetikleyin.

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

...

Doğrusal olmayan reklamlarda oynatmayı tetikleme

AdsManager, bir reklam oynatılmaya hazır olduğunda içerik videosunu duraklatır. Ancak reklam görüntülenirken içeriğin oynatılmaya devam etmesi gereken doğrusal olmayan reklamlar bu davranış için geçerli değildir. Doğrusal olmayan reklamları desteklemek için AdsManager öğesinin LOADED etkinliğini yayınlamasını dinleyin. Ardından, reklamın doğrusal olup olmadığını kontrol edin. Doğrusal değilse video öğesinde oynatmaya devam edin.

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

İşte bu kadar. Şu anda IMA SDK ile reklam istiyor ve gösteriyorsunuz. Daha gelişmiş SDK özellikleri hakkında bilgi edinmek için diğer kılavuzları veya GitHub'daki örnekleri inceleyin.