IMA DAI SDK'sını kullanmaya 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 DAI SDK'ları ile uygulamalar, reklam ve içerik videosu (VOD veya canlı içerik) için bir yayın isteği gönderir. Ardından SDK, birleştirilmiş bir video akışı döndürür. Böylece uygulamanızda reklam ve içerik videosu arasında geçiş yapmanıza gerek kalmaz.

İlgilendiğiniz DAI çözümünü seçin

Kapsül Yayınlama DAI

Bu kılavuzda, oynatma için hls.js'yi kullanan bir video oynatıcıyla HTML5 için IMA DAI SDK'sı kullanılarak canlı veya seç-izle içerik için DAI kapsül yayınlama akışının nasıl oynatılacağı gösterilmektedir. Hem HLS.js hem de Safari oynatma desteğine sahip tamamlanmış bir örnek entegrasyonu görüntülemek veya takip etmek için HLS kapsül yayınlama örneğine bakın. DASH.js desteği için DASH Kapsül Yayınlama örneğine bakın. Bu örnek uygulamaları HTML5 DAI GitHub sürüm sayfasından indirebilirsiniz.

DAI Kapsül Yayınlama'ya genel bakış

IMA DAI SDK'sını kullanarak kapsül yayınlama özelliğini uygulamak, bu kılavuzda gösterilen iki ana bileşenden oluşur:

  • PodStreamRequest / PodVodStreamRequest: Google'ın reklam sunucularına bir akış isteği tanımlayan bir nesne. İstekler bir ağ kodu belirtir ve PodStreamRequest için özel öğe anahtarı ve isteğe bağlı bir API anahtarı da gerekir. Her ikisi de diğer isteğe bağlı parametreleri içerir.

  • StreamManager: Video akışı ile IMA DAI SDK'sı arasındaki iletişimi (ör. izleme ping'lerini gönderme ve yayın akışı etkinliklerini yayıncıya yönlendirme) yöneten bir nesne.

Ön koşullar

Başlamadan önce aşağıdakilere ihtiyacınız vardır:

  • Üç boş dosya:

    • dai.html
    • dai.css
    • dai.js

  • Bilgisayarınızda yüklü Python veya test için kullanılacak bir web sunucusu ya da barındırılan başka bir geliştirme ortamı

Geliştirme ortamı yapılandırma

SDK, yüklendikleri sayfayla aynı protokolü kullanarak bağımlılıkları yüklediğinden, uygulamanızı test etmek için bir web sunucusu kullanmanız gerekir. Yerel bir geliştirme sunucusunu hızlı bir şekilde başlatmanın yolu, Python'un yerleşik sunucusunu kullanmaktır.

  1. Komut satırını kullanarak index.html dosyanızı içeren dizinde şunları çalıştırın:

    python -m http.server 8000

  2. Web tarayıcısında http://localhost:8000/

    Apache HTTP Server gibi barındırılan başka bir geliştirme ortamı veya web sunucusu da kullanabilirsiniz.

Video oynatıcı oluşturma

Öncelikle, dai.html dosyasını değiştirerek bir HTML5 video öğesi ve reklam kullanıcı arayüzü öğeleri için kullanılacak bir div oluşturun. Ayrıca, dai.css ve dai.js dosyalarını yüklemek ve hls.js video oynatıcısını içe aktarmak için gerekli etiketleri de ekleyin.

Ardından, sayfa öğelerinin boyutunu ve konumunu belirtmek için dai.css dosyasını değiştirin. Son olarak, dai.js dosyasında, akış isteği bilgilerini tutacak değişkenler ve sayfa yüklendiğinde çalışacak bir initPlayer() işlevi tanımlayın.

Akış isteği sabitleri aşağıdaki gibidir:

  • BACKUP_STREAM: Reklam işleminin önemli bir hatayla karşılaşması durumunda oynatılacak yedek yayının URL'si.

  • STREAM_URL: Yalnızca canlı yayınlar için kullanılır. Manifest düzenleyiciniz veya kapsül yayınlamayı kullanan üçüncü taraf iş ortağınız tarafından sağlanan video akışı URL'si. İstekte bulunmadan önce IMA DAI SDK'sı tarafından sağlanan akış kimliğini girmeniz gerekir. Bu durumda, yayın URL'sinde bir yer tutucu ([[STREAMID]]) bulunur. Bu yer tutucu, istek gönderilmeden önce yayın kimliğiyle değiştirilir.

  • NETWORK_CODE: Ad Manager 360 hesabınızın ağ kodu.

  • CUSTOM_ASSET_KEY: Yalnızca canlı yayınlar için kullanılır. Ad Manager 360'ta kapsül yayınlama etkinliğinizi tanımlayan özel öğe anahtarı. Bu, manifest düzenleyiciniz veya üçüncü taraf kapsül yayınlama iş ortağınız tarafından oluşturulabilir.

  • API_KEY: Yalnızca canlı yayınlar için kullanılır. IMA DAI SDK'sından bir akış kimliği almak için gerekli olabilecek isteğe bağlı bir API anahtarı.

dai.html

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css" type="text/css">
</head>
<body onLoad="initPlayer()">
  <h2>IMA DAI SDK Demo (HLS.JS)</h2>
    <video id="video"></video>
    <div id="ad-ui"></div>
</body>
</html>

dai.css

#video,
#ad-ui {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#ad-ui {
  cursor: pointer;
}

dai.js

var BACKUP_STREAM =
    'https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8'

// Stream Config.
const STREAM_URL = "https://encodersim.sandbox.google.com/masterPlaylist/...&stream_id=[[STREAMID]]";
const NETWORK_CODE = "51636543";
const CUSTOM_ASSET_KEY = "google-sample";
const API_KEY = "";

var hls = new Hls(); // hls.js video player
var videoElement;
var adUiElement;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
}

IMA DAI SDK'sını yükleme

Ardından, dai.html dosyasında dai.js etiketinden önce bir komut dosyası etiketi kullanarak DAI çerçevesini ekleyin.

dai.html

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css" type="text/css">
</head>
...

StreamManager'ı başlatma ve canlı veya VOD yayın isteği gönderme

Canlı yayın kapsülü yayınlama

Bir reklam grubu istemek için DAI akışlarını istemekten ve yönetmekten sorumlu olan bir ima.dai.api.StreamManager oluşturun. Oluşturucu bir video öğesi alır ve oluşturulan örnek, reklam etkileşimlerini işlemek için bir reklam kullanıcı arayüzü öğesi alır.

Ardından, Pod sunma canlı yayınını isteyecek bir işlev tanımlayın. Bu işlev önce bir PodStreamRequest oluşturur, 2. adımda sağlanan streamRequest parametreleriyle yapılandırır ve ardından bu istek nesnesini kullanarak streamManager.requestStream()'ı çağırır.

dai.js

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement)

  requestLivePodStream(NETWORK_CODE, CUSTOM_ASSET_KEY, API_KEY);
}

function requestLivePodStream(networkCode, customAssetKey, apiKey) {
  // clear HLS.js instance, if in use
  if (hls) {
    hls.destroy();
  }

  // Generate a Pod Serving live Stream Request
  const streamRequest = new google.ima.dai.api.PodStreamRequest();
  streamRequest.networkCode = networkCode;
  streamRequest.customAssetKey = customAssetKey;
  streamRequest.apiKey = apiKey;
  streamRequest.format = 'hls';
  streamManager.requestStream(streamRequest);
}

VOD Kapsülü Yayınlama

Bir reklam grubu istemek için DAI akışlarını istemekten ve yönetmekten sorumlu olan bir ima.dai.api.StreamManager oluşturun. Oluşturucu bir video öğesi alır ve oluşturulan örnek, reklam etkileşimlerini işlemek için bir reklam kullanıcı arayüzü öğesi alır.

Ardından, Pod Serving VOD akışını isteyecek bir işlev tanımlayın. Bu işlev önce bir PodVodStreamRequest oluşturur, 2. adımda sağlanan streamRequest parametreleriyle yapılandırır ve ardından bu istek nesnesini kullanarak streamManager.requestStream()'ı çağırır.

dai.js

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement)

  requestVodPodStream(NETWORK_CODE);
}

function requestVodPodStream(networkCode) {
  // clear HLS.js instance, if in use
  if (hls) {
    hls.destroy();
  }

  // Generate a Pod Serving VOD Stream Request
  const streamRequest = new google.ima.dai.api.PodVodStreamRequest();
  streamRequest.networkCode = networkCode;
  streamRequest.format = 'hls';
  streamManager.requestStream(streamRequest);
}

Akış etkinliklerini işleme

Canlı yayın kapsülü yayınlama

Ardından, önemli video etkinlikleri için olay dinleyicileri uygulayın. Bu örnekte, onStreamEvent() işlevi çağrılarak STREAM_INITIALIZED, ERROR, AD_BREAK_STARTED ve AD_BREAK_ENDED etkinlikleri ele alınmaktadır. Bu işlev, oynatma akışı yükleme ve hataları ele almanın yanı sıra SDK tarafından zorunlu kılınan, reklam oynatılırken oynatıcı kontrollerini devre dışı bırakma işlemlerini de gerçekleştirir. Akış yüklendiğinde video oynatıcı, loadStream() işlevini kullanarak sağlanan URL'yi yükler ve oynatır.

dai.js

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  
  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
    google.ima.dai.api.StreamEvent.Type.ERROR,
    google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
    google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED],
    onStreamEvent,
    false);
...
function onStreamEvent(e) {
  switch (e.type) {
    case google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED:
      console.log('Stream initialized');
      loadStream(e.getStreamData().streamId);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadStream('');
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
      console.log('Ad Break Started');
      isAdBreak = true;
      videoElement.controls = false;
      adUiElement.style.display = 'block';
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      isAdBreak = false;
      videoElement.controls = true;
      adUiElement.style.display = 'none';
      break;
    default:
      break;
  }
}

function loadStream(streamID) {
  var url;
  if(streamID) {
    url = STREAM_URL.replace('[[STREAMID]]', streamID);
  } else {
    console.log('Stream Initialization Failed');
    url = BACKUP_STREAM;
  }
  console.log('Loading:' + url);
  hls.loadSource(url);
  hls.attachMedia(videoElement);
}

VOD Kapsülü Yayınlama

Ardından, önemli video etkinlikleri için olay dinleyicileri uygulayın. Bu örnekte, onStreamEvent() işlevi çağrılarak STREAM_INITIALIZED, LOADED, ERROR, AD_BREAK_STARTED ve AD_BREAK_ENDED etkinlikleri ele alınmaktadır. Bu işlev, yayın yükleme ve hataları ele almanın yanı sıra SDK tarafından zorunlu kılınan, reklam oynatılırken oynatıcı kontrollerini devre dışı bırakma işlemlerini de gerçekleştirir.

Ayrıca, VOD kapsülü yayınlama akışları için STREAM_INITIALIZED etkinliğine yanıt olarak StreamManager.loadStreamMetadata() çağrısı yapılması gerekir. Video teknolojisi iş ortağından (VTP) da bir yayın URL'si istemeniz gerekir. loadStreamMetadata() çağrısı başarılı olduğunda bir LOADED etkinliği tetiklenir. Bu durumda, yayını yüklemek ve oynatmak için yayın URL'nizle bir loadStream() işlevi çağırmanız gerekir.

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  
  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
    google.ima.dai.api.StreamEvent.Type.ERROR,
    google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
    google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED],
    onStreamEvent,
    false);
...
function onStreamEvent(e) {
  switch (e.type) {
    case google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED:
      const streamId = e.getStreamData().streamId;
      // 'vtpInterface' is a place holder for your own video technology
      //  partner (VTP) API calls.
      vtpInterface.requestStreamURL({
        'streamId': streamId,
      })
      .then( (vtpStreamUrl) => {
        streamUrl = vtpStreamUrl;
        streamManager.loadStreamMetadata();
      }, (error) => {
        // Handle the error.
      });
      break;
    case google.ima.dai.api.StreamEvent.Type.LOADED:
      loadStream(streamUrl);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadStream();
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
      console.log('Ad Break Started');
      isAdBreak = true;
      videoElement.controls = false;
      adUiElement.style.display = 'block';
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      isAdBreak = false;
      videoElement.controls = true;
      adUiElement.style.display = 'none';
      break;
    default:
      break;
  }
}

function loadStream(url) {
  if(url) {
    console.log('Loading:' + url);
    hls.loadSource(url);
  } else {
    console.log('Stream Initialization Failed');
    hls.loadSource(BACKUP_STREAM);
  }
  hls.attachMedia(videoElement);
}

Akış meta verilerini işleme

Bu adımda, reklam etkinlikleri gerçekleştiğinde SDK'yı bilgilendirmek için meta veriler için etkinlik işleyicileri uygularsınız. Yayın içi meta veri etkinliklerini dinleme, yayın biçimine (HLS veya DASH), yayın türüne (canlı veya VOD yayın), oynatıcı türüne ve kullanılan DAI arka uç türüne bağlı olarak değişiklik gösterebilir. Daha fazla bilgi için zamanlanmış meta veri kılavuzumuza bakın.

HLS akış biçimi (canlı ve seç-izle yayınlar, HLS.js oynatıcı)

HLS.js oynatıcı kullanıyorsanız ID3 meta verilerini almak için HLS.js FRAG_PARSING_METADATA etkinliğini dinleyin ve StreamManager.processMetadata() ile SDK'ya iletin.

Her şey yüklenip hazır olduktan sonra videoyu otomatik olarak oynatmak için oynatmayı tetiklemek üzere HLS.js MANIFEST_PARSED etkinliğini dinleyin.

function loadStream(streamID) {
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  
  // Timed metadata is passed HLS stream events to the streamManager.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, parseID3Events);
  hls.on(Hls.Events.MANIFEST_PARSED, startPlayback);
}

function parseID3Events(event, data) {
  if (streamManager && data) {
    // For each ID3 tag in the metadata, pass in the type - ID3, the
    // tag data (a byte array), and the presentation timestamp (PTS).
    data.samples.forEach((sample) => {
      streamManager.processMetadata('ID3', sample.data, sample.pts);
    });
  }
}

function startPlayback() {
  console.log('Video Play');
  videoElement.play();
}

DASH.js (DASH akışları biçimi, Canlı ve VOD akış türü)

DASH.js oynatıcı kullanıyorsanız canlı veya seç-izle yayınların ID3 meta verilerini dinlemek için farklı dizeler kullanmanız gerekir:

  • Canlı yayınlar: 'https://developer.apple.com/streaming/emsg-id3'
  • Seç-izle video akışları: 'urn:google:dai:2018'

ID3 meta verilerini StreamManager.processMetadata() ile SDK'ya aktarın.

Her şey yüklenip hazır olduktan sonra video kontrollerini otomatik olarak göstermek için DASH.js MANIFEST_LOADED etkinliğini dinleyin.

const googleLiveSchema = 'https://developer.apple.com/streaming/emsg-id3';
const googleVodSchema = 'urn:google:dai:2018';
dashPlayer.on(googleLiveSchema, processMetadata);
dashPlayer.on(googleVodSchema, processMetadata);
dashPlayer.on(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);

function processMetadata(metadataEvent) {
  const messageData = metadataEvent.event.messageData;
  const timestamp = metadataEvent.event.calculatedPresentationTime;

  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with dash.js.
  streamManager.processMetadata('ID3', messageData, timestamp);
}

function loadlistener() {
  showControls();

  // This listener must be removed, otherwise it triggers as addional
  // manifests are loaded. The manifest is loaded once for the content,
  // but additional manifests are loaded for upcoming ad breaks.
  dashPlayer.off(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);
}

Canlı yayın içeren Shaka Player (DASH yayın biçimi)

Canlı yayın oynatma için Shaka Player'ı kullanıyorsanız meta veri etkinliklerini dinlemek için 'emsg' dizesini kullanın. Ardından, StreamManager.onTimedMetadata() çağrınızda etkinlik mesajı verilerini kullanın.

shakaPlayer.addEventListener('emsg', (event) => onEmsgEvent(event));

function onEmsgEvent(metadataEvent) {
  // Use StreamManager.onTimedMetadata() if your video player provides
  // processed metadata, as with Shaka player livestreams.
  streamManager.onTimedMetadata({'TXXX': metadataEvent.detail.messageData});
}

VOD yayınları (DASH yayınları biçimi) içeren Shaka Player

Seç-izle akışı oynatmak için Shaka Player kullanıyorsanız meta veri etkinliklerini dinlemek için 'timelineregionenter' dizesini kullanın. Ardından, 'urn:google:dai:2018' dizesiyle StreamManager.processMetadata() çağrınızdaki etkinlik mesajı verilerini kullanın.

shakaPlayer.addEventListener('timelineregionenter', (event) => onTimelineEvent(event));

function onTimelineEvent(metadataEvent) {
  const detail = metadataEvent.detail;
  if ( detail.eventElement.attributes &&
       detail.eventElement.attributes['messageData'] &&
       detail.eventElement.attributes['messageData'].value ) {
        const mediaId = detail.eventElement.attributes['messageData'].value;
        const pts = detail.startTime;
        // Use StreamManager.processMetadata() if your video player provides raw
        // ID3 tags, as with Shaka player VOD streams.
        streamManager.processMetadata('urn:google:dai:2018', mediaId, pts);
       }
}

Oyuncu etkinliklerini işleme

SDK reklam araları sırasında duraklatıldığında kullanıcının oynatmaya devam etmesine izin vermek için video öğesinin pause ve start etkinliklerine etkinlik işleyicileri ekleyin.

function loadStream(streamUrl) {
  ...
  
  videoElement.addEventListener('pause', onStreamPause);
  videoElement.addEventListener('play', onStreamPlay);
}

function onStreamPause() {
  console.log('paused');
  if (isAdBreak) {
    videoElement.controls = true;
    adUiElement.style.display = 'none';
  }
}

function onStreamPlay() {
  console.log('played');
  if (isAdBreak) {
    videoElement.controls = false;
    adUiElement.style.display = 'block';
  }
}

İşte bu kadar. Artık HTML5 için IMA DAI SDK'sını kullanarak bir kapsül yayınlama akışında 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.