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 uyumlu herhangi bir reklam sunucusundan reklam isteyebilir ve uygulamalarınızda reklam oynatmayı yönetebilir. IMA DAI SDK'ları sayesinde uygulamalar, reklam ve içerik videosu (VOD veya canlı içerik) için akış isteğinde bulunur. SDK, daha sonra birleştirilmiş bir video akışı döndürür. Böylece, uygulamanız içinde reklam ve içerik videosu arasında geçişi yönetmeniz gerekmez.

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

DAI yayınlayan kapsül

Bu kılavuzda, oynatma için hls.js kullanan bir video oynatıcıyla HTML5 için IMA DAI SDK'sı kullanılarak canlı veya VOD içerikler için DAI Kapsül Yayınlama akışının nasıl oynatılacağı gösterilmektedir. Hem HLS.js hem de Safari'de Oynatma desteğiyle birlikte tamamlanmış bir örnek entegrasyon görüntülemek veya takip etmek isterseniz HLS kapsül yayınlama örneğini inceleyin. DASH.js desteği için DASH kapsülü sunma örneğine bakın. Bu örnek uygulamaları HTML5 DAI GitHub sürüm sayfasından indirebilirsiniz.

DAI Kapsül Yayınlamaya genel bakış

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

  • PodStreamRequest / PodVodStreamRequest: Google'ın reklamcılık sunucularına akış isteğini tanımlayan bir nesnedir. İstekler bir Ağ Kodu belirtir ve PodStreamRequest için de bir Özel Öğe Anahtarı ve isteğe bağlı bir API anahtarı 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 (izleme ping'lerini etkinleştirme ve akış etkinliklerini yayıncıya iletme gibi) işleyen bir nesnedir.

Ön koşullar

Başlamadan önce şunlara ihtiyacınız vardır:

  • Üç boş dosya:

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

  • Test amacıyla kullanmak üzere bilgisayarınızda yüklü Python veya bir web sunucusu ya da başka bir barındırılan geliştirme ortamı

Geliştirme ortamı yapılandırma

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 sunucusu başlatmanın en basit yolu Python'un yerleşik sunucusunu kullanmaktır.

  1. index.html dosyanızı içeren dizinden bir komut satırı kullanarak:

    python -m http.server 8000

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

    Apache HTTP Server gibi barındırılan diğer herhangi bir geliştirme ortamını veya web sunucusunu da kullanabilirsiniz.

Basit bir video oynatıcı oluşturma

Öncelikle, dai.html dosyasını değiştirerek basit bir HTML5 video öğesi ve Reklam kullanıcı arayüzü öğeleri için kullanılacak bir div öğesi oluşturun. 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 öğesini değiştirin. Son olarak, dai.js'de akış isteği bilgilerini içerecek 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 sürecinin önemli bir hatayla karşılaşması durumunda oynatılacak yedek akışın URL'si.

  • STREAM_URL: Yalnızca canlı yayınlar için kullanılır. Kapsül yayınlama kullanan üçüncü taraf iş ortağı veya manifest düzenleyiciniz tarafından sağlanan video akışı URL'si. İstekte bulunmadan önce IMA DAI SDK'sı tarafından sağlanan akış kimliğini eklemeniz gerekir. Bu durumda, akış URL'sinde bir yer tutucu ([[STREAMID]]) bulunur. Bu yer tutucu, istekte bulunmadan önce akış 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 sunma etkinliğinizi tanımlayan özel öğe anahtarı. Bu, manifest düzenleyiciniz veya üçüncü taraf kapsül sunma 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 akış kimliği almak için gerekebilecek 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

Daha sonra, dai.html dosyasındaki bir komut dosyası etiketini kullanarak DAI çerçevesini, dai.js etiketinin önüne 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şlatın ve canlı veya VOD akış isteğinde bulunun

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 sonuçta ortaya çıkan örnek, reklam etkileşimlerini işlemek için bir reklam kullanıcı arayüzü öğesi alır.

Ardından, kapsül yayını olan canlı yayını istemek için bir işlev tanımlayın. Bu işlev önce bir PodStreamRequest oluşturur, bunu 2. adımda sağlanan streamRequest parametreleriyle yapılandırır ve ardından bu istek nesnesiyle streamManager.requestStream() yöntemini ç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 sonuçta ortaya çıkan örnek, reklam etkileşimlerini işlemek için bir reklam kullanıcı arayüzü öğesi alır.

Ardından, VOD akışı yayınlayan kapsülü istemek için bir işlev tanımlayın. Bu işlev önce bir PodVodStreamRequest oluşturur, bunu 2. adımda sağlanan streamRequest parametreleriyle yapılandırır ve ardından bu istek nesnesiyle streamManager.requestStream() yöntemini ç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 yönetme

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

Ardından, önemli video etkinlikleri için etkinlik işleyiciler uygulayın. Bu örnek STREAM_INITIALIZED, ERROR, AD_BREAK_STARTED ve AD_BREAK_ENDED etkinliklerini bir onStreamEvent() işlevi çağırarak işliyor. Bu işlev, akış yüklemeyi ve hataları ele almanın yanı sıra bir reklam oynatılırken oynatıcı kontrollerini devre dışı bırakır. Bu da SDK'nın gerektirdiği şekilde yapılır. Akış yüklendiğinde, video oynatıcı yüklenir ve sağlanan URL'yi bir loadStream() işlevi kullanarak 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 etkinlik işleyiciler uygulayın. Bu örnek STREAM_INITIALIZED, LOADED, ERROR, AD_BREAK_STARTED ve AD_BREAK_ENDED etkinliklerini bir onStreamEvent() işlevi çağırarak işliyor. Bu işlev, SDK'nın zorunlu kıldığı reklam oynatılırken oynatıcı kontrollerini devre dışı bırakmanın yanı sıra akış yüklemesini ve hatalarını da yönetir.

Ayrıca VOD kapsül yayınlama akışları, STREAM_INITIALIZED etkinliğine yanıt olarak StreamManager.loadStreamMetadata() çağrısını gerektirir. Ayrıca, video teknolojisi iş ortağınızdan (VTP) bir canlı oynatma URL'si istemeniz gerekir. loadStreamMetadata() çağrısı başarılı olduğunda bir LOADED etkinliği tetiklenir. Burada akışı yükleyip oynatmak için akış 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);
}

Yayın meta verilerini işleme

Bu adımda, reklam etkinlikleri gerçekleştiğinde SDK'yı bilgilendirmek amacıyla meta veriler için etkinlik işleyicileri uygulayacaksınız. Yayın içi meta veri etkinliklerinin dinlenmesi, akış biçimi (HLS veya DASH), yayın türüne (Canlı veya VOD akış), oynatıcı türünüze ve kullanılan DAI arka ucunun türüne bağlı olarak değişiklik gösterebilir. Daha fazla bilgi için Zamanlanmış Meta Veriler kılavuzumuza bakın.

HLS akış biçimi (Canlı ve VOD akışları, HLS.js oynatıcı)

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

Her şey yüklendikten ve 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ış biçimi, Canlı ve VOD akış türü)

DASH.js oynatıcısı kullanıyorsanız Canlı veya VOD akışlarında ID3 meta verilerini dinlemek için farklı dizeler kullanmanız gerekir:

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

ID3 meta verilerini StreamManager.processMetadata() ile SDK'ya iletin.

Her şey yüklenip hazır olduğunda 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ınlarla Shaka Player (DASH akış biçimi)

Canlı yayın oynatma için Shaka oynatıcı 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 akışlarıyla Shaka Player (DASH akış biçimi)

VOD akış oynatma için Shaka oynatıcı kullanıyorsanız meta veri etkinliklerini dinlemek için 'timelineregionenter' dizesini kullanın. Ardından, StreamManager.processMetadata() çağrınızda 'urn:google:dai:2018' dizesiyle 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);
       }
}

Oynatıcı etkinliklerini yönetin

SDK reklam araları sırasında durakladığında kullanıcının oynatmayı devam ettirmesine olanak tanımak için video öğesinin pause ve start etkinliklerine etkinlik işleyiciler 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ı ile kapsül yayınlama akışında reklamlar istiyor ve gösteriyorsunuz. Daha gelişmiş SDK özellikleri hakkında bilgi edinmek için diğer kılavuzlara veya GitHub'daki örnekleri inceleyin.