Başlayın

IMA SDK'ları, multimedya reklamları 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 taraflı SDK'larla, içerikte video oynatmayı kontrol ederken SDK, reklam oynatmayı işler. Reklamlar, uygulamanın içerik video oynatıcısının üst kısmına 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 için GitHub'dan basit örneği indirin. SDK'nın önceden entegre edildiği 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österilen dört ana SDK bileşeni bulunur:

  • AdDisplayContainer: Reklamların oluşturulduğu kapsayıcı.
  • AdsLoader: Reklam isteğinde bulunan ve reklam isteği yanıtlarındaki etkinlikleri işleyen bir nesne. Uygulamanın kullanım süresi boyunca kullanılabilecek tek bir reklam yükleyicisi çağırmanız gerekir.
  • AdsRequest: Reklam isteğini tanımlayan bir nesne. Reklam istekleri, VAST reklam etiketinin URL'sini ve reklam boyutları gibi ek parametreleri belirtir.
  • AdsManager: Reklam isteğine verilen yanıtı içeren, reklam oynatmayı kontrol eden ve SDK tarafından tetiklenen reklam etkinliklerini dinleyen 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 bir web sunucusunda test etme

1. Geliştirme sunucusu başlatma

IMA SDK, yüklendiği sayfayla aynı protokol aracılığıyla bağımlılıkları 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 ç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 sunucusu da kullanabilirsiniz.

2. Basit video oynatıcı oluşturma

İlk olarak index.html dosyasını, sarmalama öğesinde yer alan basit bir HTML5 video öğesi ve oynatmayı tetiklemek üzere bir düğme oluşturmak için değiştirin. Ayrıca, style.css ve ads.js dosyalarını yüklemek için gerekli etiketleri ekleyin. Ardından, video oynatıcıyı mobil cihazlar için uyumlu hale getirmek amacıyla styles.css dosyasını değiştirin. Son olarak, ads.js'de oynat düğmesi 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 (geliştirme sunucunuz aracılığıyla) index.html'yi açtığınızda video öğesini görebilmeniz gerekir ve oynat düğmesini tıkladığınızda video başlar.

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

Ardından, IMA dizinini index.html'de bir komut dosyası etiketi kullanarak ads.js etiketinin önüne 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 ekleme

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 oynatma düğmesi tıklandığında, reklamları yükleyin (yüklenen reklamlar olmadıkça).
  • Tarayıcı penceresi yeniden boyutlandırıldığında video öğesini ve adsManager boyutlarını güncelleyerek sayfayı mobil cihazlar için 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. Bu kapsayıcı, video öğesinin sol üst köşesinden yer paylaşımlı olarak boyutlandırılması gerekir. 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ı öğ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 yerleştirmek 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'ı ilk kullanıma hazırlayın ve bir reklam isteğinde bulunun

Bir reklam grubu isteğinde bulunmak için bir 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 Suite Inspector'ı kullanarak test edebilirsiniz.

En iyi uygulama olarak, bir sayfanın tüm yaşam döngüsü için yalnızca bir ima.AdsLoader örneği bulundurun. 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 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 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 aktarılan etkinliği ayrıştırın. AdsManager, reklam etiketi URL'sine verilen yanıtta tanımlandığı şekilde her bir reklamı yükler.

Ayrıca, yükleme işlemi sırasında ortaya çıkabilecek hataları da ele aldığınızdan emin olun. Reklamlar yüklenmiyorsa kullanıcı deneyimini etkilememek için reklam olmadan medya oynatmanın 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şlatma

Reklam oynatmaya başlamak için AdsManager işlemini başlatmanız gerekir. Mobil tarayıcıların tam olarak desteklenmesi için bu işlem kullanıcı etkileşimiyle 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 getirme

Reklamların video oynatıcının boyutuna uyacak ş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ğinin adsManager.resize() işlevi çağrılması gerekir.

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şleviyle yeni bir etkinlik işleyici ekleyerek AdsManager için hata işleyici olarak kullanılabilir.

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 bir reklam eklemeye hazır olduğunda CONTENT_PAUSE_REQUESTED etkinliğini tetikler. Temel video oynatıcıda bir duraklatma tetikleyerek bu etkinliği işleyin. Benzer şekilde, bir reklam tamamlandığında AdsManager, CONTENT_RESUME_REQUESTED etkinliğini tetikler. Temel içerik videosunda oynatmayı yeniden başlatarak bu etkinliği ele alın.

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 öğesini yer paylaşımı için kullandığından kullanıcılar temel oynatıcıyla doğrudan etkileşime giremez. Bu durum, oynatmayı duraklatmak için mobil cihazdan video oynatıcıya dokunmak isteyen kullanıcıların kafasını karıştırabilir. IMA SDK, bu sorunu gidermek için reklam yer paylaşımından IMA tarafından işlenmeyen hiçbir tıklamayı işlenemeyecek AdContainer öğesine aktarır. Reklamın tıklanmasının tıklama bağlantısı açılması, 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 ana videoda oynatma veya etkinlikleri duraklatın.

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, 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ı dikkate almaz. 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. Değişmezse video öğesinde oynatma işlemini devam ettirin.

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 bunları görüntülüyorsunuz. Daha gelişmiş SDK özellikleri hakkında bilgi edinmek için diğer kılavuzları veya GitHub'daki örnekleri inceleyin.