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ı, 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 edersiniz. 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ü kullanarak 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. Aşağıdaki örnekte IMA SDK'sı içe aktarılır ve AdDisplayContainer kapsayıcı öğesi ayarlanır. Daha fazla bilgi için sırasıyla IMA SDK'sını içe aktarma ve Reklam kapsayıcısını oluşturma adımlarına bakın. 

<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 tanımlayın ve oynat düğmesini tıkladığınızda video oynatmayı tetikleyin.

ads.js kod snippet'inde, AdsLoader'ı başlatın ve reklam isteği gönderin bölümünde tanımlanan setUpIMA() çağrısının bulunduğunu unutmayın.

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

<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şlatın ve reklam isteği gönderin

Reklam isteğinde bulunmak için bir AdsLoader örneği oluşturun. AdsLoader yapıcısı, giriş olarak bir AdDisplayContainer nesnesi alır ve belirli 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 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ü boyunca yalnızca bir AdsLoader örneği bulundurun. Ek reklam istekleri göndermek için yeni bir AdsRequest nesnesi oluşturun ancak aynı AdsLoader öğesini yeniden kullanın. Daha fazla bilgi için IMA SDK SSS bölümünü inceleyin.

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&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 = 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 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.

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

/**
 * 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ı işleme

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şleyiciye bakın. 

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

Oynat ve duraklat etkinliklerini işleme

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 yönetin. 

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, 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 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 LOADED etkinliğini yayınlamak üzere AdsManager etkinliğini dinleyin. Reklamın doğrusal olup olmadığını kontrol edin. Doğrusal değilse video öğesinde oynatmayı devam ettirin.

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 ü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ıkla ve duraklat ö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şlatın

Reklam oynatmayı başlatmak için AdsManager'ü başlatın. Reklamları otomatik olarak oynatamadığınız mobil tarayıcılarda tam destek sağlamak için oynatma düğmesini tıklama gibi sayfayla kullanıcı etkileşimlerinden reklam oynatmayı 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ı boyutunu değiştirmeyi destekleme

Reklamların dinamik olarak yeniden boyutlandırılıp video oynatıcının boyutuyla eşleşmesi veya ekran yönünde yapılan değişikliklerle eşleşmesi 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 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.