Başlama

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 tarafı SDK'larıyla, SDK reklam oynatmayı yönetirken içerik videosunun oynatılmasını kontrol edebilirsiniz. Reklamlar, uygulamanın içerik video oynatıcı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 takip etmek istiyorsanız 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 eklentisine göz atın.

IMA istemci tarafına genel bakış

IMA'yı istemci tarafında uygulamak, bu kılavuzda gösterilen dört ana SDK bileşenini içerir:

  • AdDisplayContainer: IMA'nın reklam kullanıcı arayüzü öğelerini nerede oluşturduğunu ve Aktif Görüntüleme ile Open Measurement dahil olmak üzere görüntülenebilirliği ölçtüğünü belirten bir kapsayıcı nesnesi.
  • AdsLoader: Reklam isteyen ve reklam isteği yanıtlarından gelen etkinlikleri işleyen bir nesne. Yalnızca bir reklam yükleyicisi oluşturmanız gerekir. Bu reklam yükleyici, uygulamanın ömrü boyunca yeniden kullanılabilir.
  • 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:
    • index.html
    • style.css
    • ads.js
  • Bilgisayarınızda yüklü Python veya test için kullanılacak bir web sunucusu

1. Geliştirme sunucusu başlatma

IMA SDK'sı, yüklendikleri sayfayla aynı protokol üzerinden bağımlılıkları yüklediği için 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. Komut satırını kullanarak index.html dosyanızı içeren dizinde şu komutu çalıştırın: 
      python -m http.server 8000
  2. Web tarayıcısında http://localhost:8000/

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

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

Öncelikle, index.html dosyasını değiştirerek bir sarmalayıcı öğe içinde basit bir HTML5 video öğesi ve oynatmayı tetikleyecek bir düğme oluşturun. Ayrıca style.css ve ads.js dosyalarını yüklemek için gerekli etiketleri de ekleyin. Ardından, video oynatıcının mobil cihazlara duyarlı olması için styles.css dosyasını değiştirin. Son olarak, ads.js dosyasında oynatma 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 index.html dosyasını (geliştirme sunucunuz üzerinden) açtığınızda video öğesini görebilir ve oynat düğmesini tıkladığınızda videoyu başlatabilirsiniz.

3. IMA SDK'sını içe aktarma

Ardından, index.html dosyasında ads.js etiketinden önce 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 ekleme

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

  • Sayfa yüklendiğinde IMA SDK'yı başlatın.
  • Video oynatma düğmesi tıklandığında reklamları yükleyin (zaten yüklü reklam 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

IMA SDK'sı, çoğu tarayıcıda 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 öğesini sol üst köşeden örtecek şekilde boyutlandırılmalıdır. Bu kapsayıcıya yerleştirilen reklamların yüksekliği ve genişliği adsManager nesnesi tarafından belirlenir. 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ştirecek şekilde 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'ı başlatın ve reklam isteği gönderin

Bir reklam grubu istemek için ima.AdsLoader örneği oluşturun. Bu örnek, giriş olarak bir AdDisplayContainer nesnesi alır ve belirli bir reklam etiketi URL'siyle ilişkili ima.AdsRequest nesnelerini işlemek için kullanılabilir. Bu örnekte kullanılan reklam etiketi, 10 saniyelik bir videodan önce gösterilen reklam içerir. Bu veya başka bir reklam etiketi URL'sini IMA Video Suite Inspector'ı kullanarak test edebilirsiniz.

En iyi uygulama olarak, bir sayfanın yaşam döngüsünün tamamı için yalnızca bir ima.AdsLoader örneği bulundurun. Ek reklam istekleri göndermek 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ünü inceleyin.

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 arama işlevine iletilen etkinliği ayrıştırın. AdsManager, reklam etiketi URL'sine verilen yanıtta tanımlandığı şekilde reklamları tek tek yükler.

Ayrıca, yükleme işlemi sırasında oluşabilecek hataları giderdiğinizden emin olun. Reklamlar yüklenmezse kullanıcı deneyimini etkilememek için medya oynatmanın reklam olmadan devam etmesini sağlayın.

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'yi başlatmanız gerekir. Mobil tarayıcıların tam olarak desteklenebilmesi için bu işlemin kullanıcı etkileşimiyle başlatılması 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 boyutu veya yönü değişirse pencere yeniden boyutlandırma etkinliği adsManager.resize() çağrısını yapmalı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, ele alınması gereken çeşitli etkinlikler de tetikler. Bu etkinlikler, durum değişikliklerini izlemek, içerik videosunda oynatma ve duraklatma işlemlerini 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 olarak kullanılabilir.

ads.js 
...

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

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

...

Oynat ve duraklat etkinliklerini tetikleme

AdsManager, görüntülenecek bir reklam eklemeye hazır olduğunda CONTENT_PAUSE_REQUESTED etkinliğini tetikler. Temel video oynatıcıda duraklatma işlemi 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 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ıklayarak duraklatma özelliğini tetikleme

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

Tıklayarak duraklatma ö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 oynatma işlemini 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 için geçerli değildir. Doğrusal olmayan reklamları desteklemek için AdsManager etkinliğinin LOADED etkinliğini yayınlamasını dinleyin. Ardından, reklamın doğrusal olup olmadığını kontrol edin. Doğrusal değilse video öğesinde oynatmayı 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. Artık 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ılavuzları veya GitHub'daki örnekleri inceleyin.