IMA SDK'sını ayarlama

IMA SDK'ları, multimedya reklamları web sitelerinize ve uygulamalarınıza entegre etmeyi kolaylaştırır. IMA SDK'ları, herhangi bir VAST uyumlu reklam sunucusundan reklam isteğinde bulunabilir ve uygulamalarınızda reklam oynatmayı yönetebilir. IMA istemci tarafı SDK'ları ile SDK reklam oynatmayı yönetirken içerik video oynatmayı kontrol etmeye devam edersiniz. 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 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 eklentisi'ne göz atın.

IMA istemci tarafına genel bakış

IMA istemci tarafı uygulaması dört ana SDK bileşenini içerir. Bu bileşenler bu kılavuzda gösterilmektedir:

  • AdDisplayContainer: IMA'nın reklam kullanıcı arayüzü öğelerini oluşturduğu ve Aktif Görüntüleme ile Open Measurement dahil olmak üzere görüntülenebilirliği ölçtüğü yeri belirten bir kapsayıcı nesne.
  • AdsLoader: Reklam isteyen ve reklam isteği yanıtlarındaki etkinlikleri işleyen bir nesne. Yalnızca bir reklam yükleyici oluşturmanız gerekir. Bu yükleyici, uygulamanın kullanım ömrü boyunca yeniden kullanılabilir.
  • AdsRequest: Reklam isteğini tanımlayan bir nesne. Reklam isteklerinde VAST reklam etiketinin URL'si ve reklam boyutları gibi ek parametreler belirtilir.
  • 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, bağımlılıkları yüklendiği sayfayla aynı protokolü kullanarak yüklediğinden uygulamanızı test etmek için bir web sunucusu kullanmanız gerekir. Yerel geliştirme sunucusunu başlatmanın en basit yolu Python'ın yerleşik sunucusunu kullanmaktır.

  1. Komut satırını kullanarak, index.html dosyanızı içeren dizinden şunu ç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 bir video oynatıcı oluşturma

Öncelikle, index.html dosyasını değiştirerek sarmalama öğesi içinde yer alan basit bir HTML5 video öğesi ve oynatmayı tetikleyecek bir düğme oluşturun. Aşağıdaki örnekte IMA SDK içe aktarılıyor ve AdDisplayContainer kapsayıcı öğesi ayarlanıyor. Daha fazla bilgi için sırasıyla IMA SDK'sını içe aktarma ve Reklam kapsayıcısı oluşturma adımlarını inceleyin. 

<html>
  <head>
    <title>IMA HTML5 Simple Demo</title>
    <link rel="stylesheet" href="style.css">
  </head>

  <body>
    <div id="mainContainer">
      <div id="content">
        <video id="contentElement">
          <source src="https://storage.googleapis.com/gvabox/media/samples/stock.mp4"></source>
        </video>
      </div>
      <div id="adContainer"></div>
    </div>
    <button id="playButton">Play</button>
    <script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
    <script src="ads.js"></script>
  </body>
</html>

index.html
 
#mainContainer {
  position: relative;
  width: 640px;
  height: 360px;
}

#content {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}

#contentElement {
  width: 640px;
  height: 360px;
  overflow: hidden;
}

#playButton {
  margin-top:10px;
  vertical-align: top;
  width: 350px;
  height: 60px;
  padding: 0;
  font-size: 22px;
  color: white;
  text-align: center;
  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.25);
  background: #2c3e50;
  border: 0;
  border-bottom: 2px solid #22303f;
  cursor: pointer;
  -webkit-box-shadow: inset 0 -2px #22303f;
  box-shadow: inset 0 -2px #22303f;
}
style.css
 
let adsManager;
let adsLoader;
let adDisplayContainer;
let isAdPlaying;
let isContentFinished;
let playButton;
let videoContent;
let adContainer;

// On window load, attach an event to the play button click
// that triggers playback of the video element.
window.addEventListener('load', function(event) {
  videoContent = document.getElementById('contentElement');
  adContainer = document.getElementById('adContainer');
  adContainer.addEventListener('click', adContainerClick);
  playButton = document.getElementById('playButton');
  playButton.addEventListener('click', playAds);
  setUpIMA();
});
ads.js

style.css ve ads.js dosyalarını yüklemek için gerekli etiketleri 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 değişkenlerinizi bildirin ve oynat düğmesini tıkladığınızda video oynatmayı tetikleyin.

ads.js kod snippet'inin, setUpIMA() için bir çağrı içerdiğini unutmayın. Bu çağrı, Initialize the AdsLoader and make an ads request bölümünde tanımlanır.

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. 

<script src="//imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
index.html

4. Reklam kapsayıcısını oluşturma

IMA SDK, ç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 kaplayacak ş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 ayarlanır. Bu nedenle, bu değerleri manuel olarak ayarlamanız gerekmez.

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, yeni reklam kapsayıcısını kullanarak createAdDisplayContainer() işlevini ekleyerek AdDisplayContainer nesnesini oluşturun div. 

<div id="adContainer"></div>
index.html
 
#adContainer {
  position: absolute;
  top: 0;
  left: 0;
  width: 640px;
  height: 360px;
}
style.css
 
/**
 * Sets the 'adContainer' div as the IMA ad display container.
 */
function createAdDisplayContainer() {
  adDisplayContainer = new google.ima.AdDisplayContainer(
      document.getElementById('adContainer'), videoContent);
}
ads.js

5. AdsLoader'ı başlatma ve reklam isteğinde bulunma

Reklam isteğinde bulunmak için bir AdsLoader örneği oluşturun. AdsLoader oluşturucusu, giriş olarak bir AdDisplayContainer nesnesi alır ve belirtilen bir reklam etiketi URL'siyle ilişkili 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 herhangi bir reklam etiketi URL'sini IMA Video Ürün Paketi Denetleyicisi'ni kullanarak test edebilirsiniz.

En iyi uygulama olarak, bir sayfanın yaşam döngüsü boyunca yalnızca bir AdsLoader örneği bulundurun. Ek reklam istekleri göndermek için yeni bir AdsRequest nesnesi oluşturun ancak aynı AdsLoader değerini yeniden kullanın. Daha fazla bilgi için IMA SDK hakkında SSS bölümüne bakın.

AdsLoader.addEventListener kullanarak yüklenen reklamları ve hata etkinliklerini dinleyip yanıtlayın. Aşağıdaki etkinlikleri dinleyin:

  • ADS_MANAGER_LOADED
  • AD_ERROR

onAdsManagerLoaded() ve onAdError() dinleyicilerini oluşturmak için aşağıdaki örneğe bakın: 

/**
 * Sets up IMA ad display container, ads loader, and makes an ad request.
 */
function setUpIMA() {
  // Create the ad display container.
  createAdDisplayContainer();
  // Create ads loader.
  adsLoader = new google.ima.AdsLoader(adDisplayContainer);
  // Listen and respond to ads loaded and error events.
  adsLoader.addEventListener(
      google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
      onAdsManagerLoaded, false);
  adsLoader.addEventListener(
      google.ima.AdErrorEvent.Type.AD_ERROR, onAdError, false);

  // An event listener to tell the SDK that our content video
  // is completed so the SDK can play any post-roll ads.
  const contentEndedListener = function() {
    // An ad might have been playing in the content element, in which case the
    // content has not actually ended.
    if (isAdPlaying) return;
    isContentFinished = true;
    adsLoader.contentComplete();
  };
  videoContent.onended = contentEndedListener;

  // Request video ads.
  const 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&correlator=';

  // Specify the linear and nonlinear slot sizes. This helps the SDK to
  // select the correct creative if multiple are returned.
  adsRequest.linearAdSlotWidth = 640;
  adsRequest.linearAdSlotHeight = 400;

  adsRequest.nonLinearAdSlotWidth = 640;
  adsRequest.nonLinearAdSlotHeight = 150;

  adsLoader.requestAds(adsRequest);
}
ads.js

6. AdsLoader etkinliklerine yanıt verme

AdsLoader reklamları başarıyla yüklediğinde bir ADS_MANAGER_LOADED etkinliği yayar. AdsManager nesnesini başlatmak için geri aramaya iletilen etkinliği ayrıştırın. AdsManager, reklam etiketi URL'sine verilen yanıtta tanımlandığı şekilde tek tek reklamları yükler.

Yükleme işlemi sırasında oluşan hataları giderdiğinizden emin olun. Reklamlar yüklenmiyorsa kullanıcının içeriği görüntülemesini engellememek için medya oynatmanın reklamsız devam ettiğinden emin olun. 

/**
 * Handles the ad manager loading and sets ad event listeners.
 * @param {!google.ima.AdsManagerLoadedEvent} adsManagerLoadedEvent
 */
function onAdsManagerLoaded(adsManagerLoadedEvent) {
  // Get the ads manager.
  const adsRenderingSettings = new google.ima.AdsRenderingSettings();
  adsRenderingSettings.restoreCustomPlaybackStateOnAdBreakComplete = true;
  // videoContent should be set to the content video element.
  adsManager =
      adsManagerLoadedEvent.getAdsManager(videoContent, adsRenderingSettings);

  // Add listeners to the required events.
  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);
}

/**
 * Handles ad errors.
 * @param {!google.ima.AdErrorEvent} adErrorEvent
 */
function onAdError(adErrorEvent) {
  // Handle the error logging.
  console.log(adErrorEvent.getError());
  adsManager.destroy();
}
ads.js

onAdsManagerLoaded() işlevinde ayarlanan dinleyiciler hakkında daha fazla bilgi için aşağıdaki alt bölümlere bakın:

AdsManager hatalarını giderme

AdsLoader için oluşturulan hata işleyici, AdsManager için de hata işleyici olarak kullanılabilir. onAdError() işlevini yeniden kullanan etkinlik işleyicisini inceleyin. 

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

Oynatma ve duraklatma etkinliklerini işleme

AdsManager, görüntülü reklam eklemeye hazır olduğunda CONTENT_PAUSE_REQUESTED etkinliğini tetikler. Temel video oynatıcıda duraklatma tetikleyerek bu etkinliği işleyin. Benzer şekilde, bir reklam tamamlandığında AdsManager, CONTENT_RESUME_REQUESTED etkinliğini tetikler. Bu etkinliği, temel içerik videosunda oynatmayı yeniden başlatarak ele alın. 

adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED, onContentPauseRequested);
adsManager.addEventListener(
    google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
    onContentResumeRequested);
ads.js

onContentPauseRequested() ve onContentResumeRequested() işlevlerinin tanımları için aşağıdaki örneğe bakın: 

/**
 * Pauses video content and sets up ad UI.
 */
function onContentPauseRequested() {
  isAdPlaying = true;
  videoContent.pause();
  // This function is where you should setup UI for showing ads (for example,
  // display ad timer countdown, disable seeking and more.)
  // setupUIForAds();
}

/**
 * Resumes video content and removes ad UI.
 */
function onContentResumeRequested() {
  isAdPlaying = false;
  if (!isContentFinished) {
    videoContent.play();
  }
  // This function is where you should ensure that your UI is ready
  // to play content. It is the responsibility of the Publisher to
  // implement this function when necessary.
  // setupUIForContent();
}
ads.js

Doğrusal olmayan reklamlar sırasında içerik oynatmayı yönetme

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 ettiği doğrusal olmayan reklamlar için geçerli değildir. 

adsManager.addEventListener(google.ima.AdEvent.Type.LOADED, onAdLoaded);
ads.js

Doğrusal olmayan reklamları desteklemek için AdsManager öğesinin LOADED etkinliğini yayınlamasını bekleyin. Reklamın doğrusal olup olmadığını kontrol edin. Doğrusal değilse video öğesinde oynatmaya devam edin.

onAdLoaded() işlevinin tanımı için aşağıdaki örneğe bakın. 

/**
 * Handles ad loaded event to support non-linear ads. Continues content playback
 * if the ad is not linear.
 * @param {!google.ima.AdEvent} adEvent
 */
function onAdLoaded(adEvent) {
  let ad = adEvent.getAd();
  if (!ad.isLinear()) {
    videoContent.play();
  }
}
ads.js

7. Mobil cihazlarda tıklayarak duraklatma özelliğini tetikleme

AdContainer, video öğesinin üzerinde yer aldığından kullanıcılar alttaki oynatıcıyla doğrudan etkileşimde bulunamaz. Bu durum, mobil cihazlarda oynatmayı duraklatmak için video oynatıcıya dokunmayı bekleyen kullanıcıların kafasını karıştırabilir. IMA SDK, bu sorunu çözmek için reklam yer paylaşımından IMA tarafından işlenmeyen tüm tıklamaları, işlenebilecekleri AdContainer öğesine iletir. Bu durum, reklamı tıklamanın tıklama bağlantısını açtığı için mobil olmayan tarayıcılardaki doğrusal reklamlar için geçerli değildir.

Tıklayarak duraklatma özelliğini uygulamak için pencere yükleme işleyicisine adContainerClick() adlı tıklama işleyici işlevini ekleyin. 

/**
 * Handles clicks on the ad container to support expected play and pause
 * behavior on mobile devices.
 * @param {!Event} event
 */
function adContainerClick(event) {
  console.log("ad container clicked");
  if(videoContent.paused) {
    videoContent.play();
  } else {
    videoContent.pause();
  }
}
ads.js

8. AdsManager'ı başlatma

Reklam oynatmayı başlatmak için AdsManager başlatın. Reklamları otomatik olarak oynatamadığınız mobil tarayıcıları tam olarak desteklemek için reklam oynatmayı, kullanıcının sayfayla etkileşimlerinden (ör. oynatma düğmesini tıklama) tetikleyin. 

/**
 * Loads the video content and initializes IMA ad playback.
 */
function playAds() {
  // Initialize the container. Must be done through a user action on mobile
  // devices.
  videoContent.load();
  adDisplayContainer.initialize();

  try {
    // Initialize the ads manager. This call starts ad playback for VMAP ads.
    adsManager.init(640, 360);
    // Call play to start showing the ad. Single video and overlay ads will
    // start at this time; the call will be ignored for VMAP ads.
    adsManager.start();
  } catch (adError) {
    // An error may be thrown if there was a problem with the VAST response.
    videoContent.play();
  }
}
ads.js

9. Oynatıcının yeniden boyutlandırılmasına izin verme

Reklamların boyutunun dinamik olarak değiştirilip video oynatıcının boyutuna veya ekran yönündeki değişikliklere uygun hale getirilmesi için pencere yeniden boyutlandırma etkinliklerine yanıt olarak adsManager.resize() işlevini çağırın. 

window.addEventListener('resize', function(event) {
  console.log("window resized");
  if(adsManager) {
    let width = videoContent.clientWidth;
    let height = videoContent.clientHeight;
    adsManager.resize(width, height, google.ima.ViewMode.NORMAL);
  }
});
ads.js

İşte bu kadar. Artık IMA SDK ile reklam isteğinde bulunup reklam görüntüleyebilirsiniz. Daha gelişmiş SDK özellikleri hakkında bilgi edinmek için diğer kılavuzlara veya GitHub'daki örneklere göz atın.