Başlayın

IMA SDK'ları, multimedya reklamlarını web sitelerinize ve uygulamalarınıza entegre etmenizi kolaylaştırır. IMA SDK'ları VAST ile uyumlu herhangi bir reklam sunucusundan reklam isteyebilir ve uygulamalarınızda reklam oynatmayı yönetebilir. IMA istemci tarafı SDK'larında, video oynatma işlevi içeriğin kontrolündeyken SDK reklam oynatmayı işler. Reklamlar, uygulamanın içerik video oynatıcısının üstüne yerleştirilmiş 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. Tamamlanmış bir örnek entegrasyonu görüntülemek veya bunu takip etmek istiyorsanız 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ı uygulamak için bu kılavuzda gösterildiği gibi dört ana SDK bileşeni bulunur:

  • AdDisplayContainer: Reklamların oluşturulacağı kapsayıcı nesne.
  • AdsLoader: Reklam isteğinde bulunan ve reklam isteği yanıtlarındaki etkinlikleri işleyen bir nesne. Uygulamanın kullanım ömrü boyunca yeniden kullanılabilecek tek bir reklam yükleyicisi belirlemeniz 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 işleyen bir nesne.

Ön koşullar

Başlamadan önce aşağıdakilere ihtiyacınız olacaktır:

  • Üç boş dosya:
    • dizin.html
    • stil.css
    • ads.js
  • Bilgisayarınızda yüklü olan Python veya test için kullanılacak bir web sunucusu

1. Geliştirme sunucusu başlatma

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

  1. Bir komut satırı kullanarak index.html dosyanızı içeren dizinden: 
      python -m http.server 8000
  2. Web tarayıcısında http://localhost:8000/ adresine gidin

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

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

İlk olarak, index.html'yi sarmalama öğesinde bulunan basit bir HTML5 video öğesi, ardından oynatmayı tetikleyen bir düğme oluşturun. Ayrıca, style.css ve ads.js dosyalarını yüklemek için gerekli etiketleri de ekleyin. Ardından, styles.css dosyasını değiştirerek video oynatıcıyı mobil cihazlara duyarlı hale getirin. Son olarak, ads.js'de oynat düğmesine tıklandığında video oynatmayı tetikleyin.

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, tarayıcınızda index.html sayfasını (geliştirme sunucunuz üzerinden) açtığınızda video öğesini görebilmeniz gerekir ve oynat düğmesini tıkladığınızda video başlamalıdır.

3. IMA SDK'yı içe aktarın

Ardından, ads.js dizininin önüne index.html komut dosyası etiketini 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 bittiğinde IMA SDK'yı başlatın.
  • Video oynatma düğmesi tıklandığında (yüklenmiş reklamlar yoksa) reklamları yükleyin.
  • Tarayıcı penceresi yeniden boyutlandırıldığında video öğesini ve adsManager boyutlarını güncelleyerek sayfayı mobil cihazlara uyumlu hale getirin
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 reklamlarla ilgili kullanıcı arayüzü öğelerini görüntülemek için özel bir reklam kapsayıcı öğesi kullanır. Video kapsayıcı, video öğesinin sol üst köşesinden yer paylaşımlı olarak yerleştirilmelidir. Bu kapsayıcıya yerleştirilen reklamların yüksekliği ve genişliği adsManager nesnesi tarafından ayarlanır. Bu nedenle, bu değerleri manuel olarak ayarlamanıza gerek yoktur.

Bu reklam kapsayıcısı öğesini uygulamak için önce video-container öğesinde yeni bir div oluşturun. Ardından, öğeyi video-element öğesinin sol üst köşesine yerleştirmek için CSS'yi güncelleyin. Son olarak, sayfa yüklendiğinde çalışan initializeIMA() işlevi içinde 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'ı ilk kullanıma hazırlayın ve bir reklam isteğinde bulunun

Reklam grubu istemek için ima.AdsLoader örneği oluşturun. Bu örnek, AdDisplayContainer nesnesini giriş olarak alır ve belirtilen reklam etiketi URL'siyle ilişkili ima.AdsRequest nesnesini işlemek için kullanılabilir. Bu örnekte kullanılan reklam etiketi, 10 saniyelik bir videodan önce gösterilen reklam içerir. 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 öğesini yeniden kullanın. Daha fazla bilgi için IMA SDK 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 dinleme

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, reklam etiketi URL'sine verilen yanıtta tanımlandığı şekilde reklamları tek tek yükler.

Buna ek olarak, yükleme işlemi sırasında oluşabilecek hataları ele aldığınızdan emin olun. Reklamlar yüklenmezse kullanıcı deneyimine engel olmamak için medya oynatmanın 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 oynatmayı başlatmak için AdsManager başlatın. Mobil tarayıcıların tam olarak desteklenebilmesi için kullanıcı etkileşimi tarafından tetiklenmelidir.

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 getirin

Reklamların video oynatıcının boyutuna uygun olacak şekilde dinamik olarak yeniden boyutlandırılmasını sağlamak için ekran boyutu veya yönü değişirse pencere yeniden boyutlandırma etkinliği adsManager.resize() özelliğini ç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 dinleyin

AdsManager, işlenmesi gereken birkaç etkinliği de tetikler. Bu etkinlikler durum değişikliklerini izlemek, içerik videosunda oynatmayı ve duraklatmayı 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 işlevi 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örüntülü reklam eklemek için 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, 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ıklama için duraklatmayı tetikleme

AdContainer video öğesini kapsadığından kullanıcılar temel oynatıcıyla doğrudan etkileşimde bulunamaz. Bu durum, oynatmayı duraklatmak için video oynatıcıya dokunmayı bekleyen kullanıcıların kafasını karıştırabilir. IMA SDK, bu sorunu gidermek için reklam yer paylaşımından IMA öğesinin işlenmediği tıklamaları, işlenebilecekleri AdContainer öğesine aktarır. Bu, mobil cihazlarda olmayan reklamlar için geçerli değildir çünkü reklamı tıklamak, tıklama bağlantısını açar.

Duraklatmayı uygulamak için AdContainer özelliğine bir tıklama işleyici ekleyin ve alttaki 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 bu davranış, reklam gösterilirken içeriğin oynatılmaya devam etmesi gereken doğrusal olmayan reklamları hesaba katmaz. Doğrusal olmayan reklamları desteklemek için AdsManager etkinliğini dinletin. Ardından, reklamın doğrusal olup olmadığını kontrol edin. Doğru 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 isteğinde bulunuyor ve reklamları görüntülüyorsunuz. Daha gelişmiş SDK özellikleri hakkında bilgi edinmek için diğer kılavuzlara veya GitHub'daki örneklere bakın.