Başlama

IMA SDK'ları, multimedya reklamlarını web sitelerinize ve uygulamalarınıza entegre etmenizi kolaylaştırır. IMA SDK'ları herhangi birinden reklam iste VAST uyumlu reklam sunucusu oluşturup uygulamalarınızda reklam oynatmayı yönetin. IMA istemci taraflı SDK'larla SDK, reklam oynatmayı işlerken içerik videosunun oynatılmasını siz kontrol edersiniz. Reklamlar: uygulamanın içerik video oynatıcısının üzerine yerleştirilmiş ayrı bir video oynatıcı.

Bu kılavuzda, IMA SDK'nın basit bir video oynatıcı uygulamasına nasıl entegre edileceği gösterilmektedir. Şunu tamamlanmış bir örnek entegrasyonu görüntülemek veya izlemek istiyorsanız simple example'ı ziyaret edin. Eğer SDK önceden entegre edilmiş bir HTML5 oynatıcı kullanmak isterseniz Video.js için IMA SDK Eklentisi.

IMA istemci tarafına genel bakış

IMA istemci tarafını uygulamak için aşağıdaki dört ana SDK bileşenini içerir: kılavuz:

  • AdDisplayContainer: Reklamların oluşturulduğu kapsayıcı nesne.
  • AdsLoader: Reklam isteyen ve reklam isteği yanıtlarından gelen etkinlikleri işleyen nesne. Yalnızca uygulamanın ömrü boyunca yeniden kullanılabilecek bir reklam yükleyicisi örneklendirir.
  • AdsRequest: Reklam isteğini tanımlayan bir nesne. Reklam istekleri, VAST reklam etiketi URL'sinin yanı sıra ek parametrelere (reklam boyutları gibi) sahip olabilir.
  • AdsManager: Reklam isteğinin yanıtını içeren, reklam oynatmayı kontrol eden ve reklamı dinleyen bir nesne etkinliklerdir.

Ö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, bağımlılıkları 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 başlatmanın en kolay yolu Python'un yerleşik sunucusunu kullanmaktır.

  1. Aşağıdaki dosyayı içeren dizinden, bir komut satırı kullanarak index.html dosyanızın çalıştırıldığı:
      python -m http.server 8000
    
    .
  2. Web tarayıcısında http://localhost:8000/ adresine gidin

Ayrıca, Apache HTTP Server.

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

Öncelikle index.html dosyasını sarmalama içinde yer alan basit bir HTML5 video öğesi oluşturmak için değiştirin öğesi ve oynatmayı tetiklemek için bir düğme. Ayrıca style.css ve ads.js dosyalarını kapsar. Ardından, video oynatıcıyı oluşturmak için styles.css dosyasını değiştirin. mobil cihazlar için duyarlı hale getirilmiştir. Son olarak, ads.js'de, oynatma sırasında düğmesi tıklanır.

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ı açtığınızda (geliştirme sunucu) video öğesini görebilirsiniz. Video öğesini tıkladığınızda video başlar. oynat düğmesi.

3. IMA SDK'yı içe aktarma

Ardından, index.html dosyasında komut dosyası etiketi kullanarak IMA çerçevesini 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. Sayfa ve video oynatıcı işleyicileri ekle

Video oynatıcının davranışını JavaScript ile değiştirmek için şu işlemleri yapabilirsiniz:

  • Sayfanın yüklenmesi bittiğinde IMA SDK'yı başlatın.
  • Video oynat düğmesi tıklandığında, reklamları yükleyin (önceden yüklenmiş reklamlar yoksa).
  • Tarayıcı penceresi yeniden boyutlandırıldığında video öğesini güncelleyin ve adsManager sayfayı mobil cihazlara uyumlu hale getirmek için boyutlar
ziyaret edin. ziyaret edin. 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 reklamları görüntülemek için özel bir reklam kapsayıcı öğesi kullanır. reklamla ilgili kullanıcı arayüzü öğeleri. Bu kapsayıcı, tıklayın. Bu kapsayıcıya yerleştirilen reklamların yüksekliği ve genişliği adsManager nesnesi olduğundan bu değerleri manuel olarak ayarlamanız gerekmez.

Bu reklam kapsayıcı öğesini uygulamak için öncediv video-container öğesi. Ardından, öğeyi sol üste yerleştirmek için CSS'yi güncelleyin video-element köşesindeki kartı tıklayın. Son olarak, Sayfa yüklendiğinde çalışan initializeIMA() işlevi.

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

Reklam grubu istemek için bir ima.AdsLoader örneği oluşturun. Bu örnek giriş olarak bir AdDisplayContainer nesnesini alır ve Belirtilen reklam etiketi URL'siyle ilişkilendirilmiş ima.AdsRequest nesne. Kullanılan reklam etiketi bu örnek, videodan önce 10 saniyelik bir reklam içerir. Bunu veya herhangi bir reklam etiketi URL'sini IMA Video Ürün Paketi Denetleyicisi.

En iyi uygulama olarak, tüm cihaz için ima.AdsLoader öğesinin yalnızca bir örneğini koruyun yaşam döngüsü boyunca tüm süreci takip eder. Daha fazla reklam isteğinde bulunmak için yeni bir ima.AdsRequest oluşturun ancak aynı ima.AdsLoader öğesini yeniden kullanın. Daha fazla bilgi için IMA SDK ile ilgili SSS.

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 dinleyin

Reklamlar başarıyla yüklendiğinde, ima.AdsLoader bir ADS_MANAGER_LOADED etkinliği. AdsManager nesne algılandı. AdsManager, reklama verilen yanıtın tanımladığı her bir reklamı yükler etiket URL'si.

Ayrıca, yükleme işlemi sırasında oluşabilecek hataları da ele aldığınızdan emin olun. Reklamlar ne zaman medya oynatmanın reklamlar olmadan devam ettiğinden emin olmak için en iyi uygulamaları paylaşacağız.

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 uygulamayı tam olarak desteklemek için bu işlem bir 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 boyutuyla uyumlu olacak şekilde dinamik olarak yeniden boyutlandırılmasını boyut veya yön değiştiğinde, pencere yeniden boyutlandırma etkinliği adsManager.resize() öğesini ç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, ele alınması gereken çeşitli etkinlikleri de tetikler. Bu etkinlikler kullanılır durum değişikliklerini izlemek, içerik videosunu oynatma ve duraklatmayı tetikleme ve hataları kaydetme.

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.

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ülenecek bir reklam eklemeye hazır olduğunda CONTENT_PAUSE_REQUESTED etkinliği. Bu etkinliği, temel video oynatıcısı. Benzer şekilde, bir reklam tamamlandığında AdsManager, CONTENT_RESUME_REQUESTED etkinliği. Bu etkinliği, şurada oynatmayı yeniden başlatarak gerçekleştirebilirsiniz: temel içerik videosudur.

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 yerleştirildiğinden, kullanıcılar doğrudan etkileşimde bulunamazlar ana oyuncuları seçin. Bu durum, mobil cihazda bir şeye dokunmayı bekleyen kullanıcıların kafasını karıştırabilir. video oynatıcıyı kullanın. IMA SDK, bu sorunu gidermek için reklam yer paylaşımından AdContainer öğesine IMA tarafından işlenir. Burada ele alınır. Bu, mobil olmayan tarayıcılardaki doğrusal reklamlar için geçerli değildir, çünkü reklam tıklandığında tıklama bağlantısı.

Tıkla ve duraklatmayı uygulamak için AdContainer öğesine bir tıklama işleyici ekleyin ve oynatmayı tetikleyin temel videodaki etkinlikleri duraklatabilirsiniz.

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

Reklam oynatılmaya hazır olduğunda AdsManager, içerik videosunu duraklatır ancak bu davranışı, doğrusal olmayan reklamları dikkate almaz. Bu tür reklamlar gösterilirken içeriğin oynatılmaya devam etmesi reklam gösterildiğini unutmayın. Doğrusal olmayan reklamları desteklemek için AdsManager simgesinin LOADED etkinliği. Ardından, reklamın doğrusal olup olmadığını kontrol edin. Doğrusal değilse video öğesi.

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 istiyor ve görüntülüyorsunuz. Daha fazla bilgi edinmek için özellikleri hakkında daha fazla bilgi edinmek için diğer kılavuzları veya GitHub'daki örnekler.