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

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

Kapsül yayınlama DAI

Bu kılavuzda, oynatma için hls.js'ye dayanan bir video oynatıcıyla HTML5 için IMA DAI SDK'yı kullanarak canlı veya VOD içeriklerinde DAI Kapsül Yayınlama akışının nasıl oynatılacağı gösterilmektedir. Hem HLS.js hem de Safari oynatma desteğiyle 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ınlamaya genel bakış

IMA DAI SDK'sını kullanarak kapsül yayınlama özelliğini uygulama işlemi iki ana bileşenden oluşur. Bu bileşenler bu kılavuzda açıklanmaktadır:

  • PodStreamRequest / PodVodStreamRequest: Google'ın reklam sunucularına yönelik bir yayın isteğini tanımlayan nesne. İsteklerde Ağ Kodu belirtilir ve PodStreamRequest ayrıca Özel Öğenin Anahtarı ile isteğe bağlı bir API anahtarı gerektirir. Her ikisi de diğer isteğe bağlı parametreleri içerir.

  • StreamManager: İzleme ping'lerini tetikleme ve yayın içi etkinlikleri yayıncıya yönlendirme gibi video akışı ile IMA DAI SDK arasındaki iletişimi 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, 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 bir geliştirme sunucusu başlatmanın hızlı bir yolu, Python'un yerleşik sunucusunu kullanmaktır.

  1. Bir komut satırı 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.

    Ayrıca Apache HTTP Server gibi barındırılan diğer geliştirme ortamlarını veya web sunucularını da kullanabilirsiniz.

Video oynatıcı oluşturma

İlk olarak, HTML5 video öğesi ve reklam kullanıcı arayüzü öğelerinde kullanılacak bir div oluşturmak için dai.html dosyasını değiştirin. Ayrıca dai.css ve dai.js dosyalarını yüklemek ve hls.js video oynatıcıyı içe aktarmak için gerekli etiketleri 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şkenleri ve sayfa yüklendiğinde çalışacak bir initPlayer() işlevini tanımlayın.

Akış isteği sabitleri şunlardır:

  • BACKUP_STREAM: Reklam işleme sırasında ölümcül bir hatayla karşılaşılması durumunda oynatılacak yedek akışın URL'si.

  • STREAM_URL: Yalnızca canlı yayınlar için kullanılır. Manifest düzenleyiciniz veya kapsül yayınlama kullanan üçüncü taraf iş ortağınız tarafından sağlanan video akışı URL'si. İstek göndermeden önce IMA DAI SDK tarafından sağlanan akış kimliğini girmenizi gerektirmelidir. Bu durumda, yayın URL'si bir yer tutucu ([[STREAMID]]) içerir. Bu yer tutucu, istekte bulunmadan ö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'taki Pod Serving 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'dan 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="adUi"></div>
</body>
</html>

dai.css

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

#adUi {
  cursor: pointer;
}

dai.js

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

// Stream Config.
const STREAM_URL = "";
const NETWORK_CODE = "";
const CUSTOM_ASSET_KEY = "";
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 içinde 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şlatın ve canlı yayın veya VOD akışı isteğinde bulunun

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

Bir dizi reklam istemek için ima.dai.api.StreamManager oluşturun. Bu, DAI yayınlarını istemek ve yönetmekten sorumludur. Oluşturucu, bir video öğesi alır ve sonuçta elde edilen örnek, reklam etkileşimlerini işlemek için bir reklam kullanıcı arayüzü öğesi alır.

Ardından, Pod Serving 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() işlevini ç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 dizi reklam istemek için ima.dai.api.StreamManager oluşturun. Bu, DAI yayınlarını istemek ve yönetmekten sorumludur. Oluşturucu, bir video öğesi alır ve sonuçta elde edilen örnek, reklam etkileşimlerini işlemek için bir reklam kullanıcı arayüzü öğesi alır.

Ardından, Pod Serving VOD akışını 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() işlevini ç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);
}

Yayın etkinliklerini işleme

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

Ardından, önemli video etkinlikleri için etkinlik dinleyicilerini uygulayın. Bu örnekte, STREAM_INITIALIZED, ERROR, AD_BREAK_STARTED ve AD_BREAK_ENDED etkinlikleri onStreamEvent() işlevi çağrılarak işlenir. Bu işlev, akış yükleme ve hataların yanı sıra reklam oynatılırken oynatıcı kontrollerinin devre dışı bırakılmasını da yönetir. Bu, SDK tarafından gereklidir. Yayın 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 etkinlik dinleyicilerini uygulayın. Bu örnekte, STREAM_INITIALIZED, LOADED, ERROR, AD_BREAK_STARTED ve AD_BREAK_ENDED etkinlikleri onStreamEvent() işlevi çağrılarak işlenir. Bu işlev, akış yükleme ve hataların yanı sıra reklam oynatılırken oynatıcı kontrollerinin devre dışı bırakılmasını da yönetir. Bu, SDK tarafından gereklidir.

Ayrıca, VOD Pod Serving akışları için StreamManager.loadStreamMetadata() etkinliğine yanıt olarak STREAM_INITIALIZED çağrısı yapılması gerekir. Ayrıca video teknolojisi iş ortağınızdan (VTP) bir yayın URL'si istemeniz gerekir. loadStreamMetadata() çağrısı başarılı olduğunda bir LOADED etkinliği tetiklenir. Bu etkinlikte, akışı yüklemek ve oynatmak için akış URL'nizle bir loadStream() işlevini ç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 için meta verilerle ilgili etkinlik işleyicileri uygularsınız. Yayın içi meta veri etkinliklerini dinleme, akış biçimine (HLS veya DASH), akış türüne (canlı veya VOD akışı), oynatıcı türünüze ve kullanılan DAI arka ucu türüne bağlı olarak değişebilir. 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ı 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ü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ı kullanıyorsanız canlı veya VOD yayınları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üklendikten ve 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ınlarla Shaka Player (DASH akış 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 akışları içeren Shaka Player (DASH akışları biçimi)

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

Kullanıcının, SDK reklam araları sırasında duraklatıldığında 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';
  }
}

IMA DAI öğelerini temizleme

IMA DAI SDK ile bir PodServing akışında reklam isteme ve görüntüleme işlemlerini başarıyla tamamladığınızda, PodServing oturumu tamamlandıktan sonra tüm kaynakları temizlemenizi öneririz. Akış oynatmayı durdurmak, tüm reklam izlemeyi durdurmak ve yüklenen tüm akış öğelerini serbest bırakmak için StreamManager.destroy() işlevini çağırın.

Daha gelişmiş SDK özellikleri hakkında bilgi edinmek için diğer kılavuzlara veya GitHub'daki örneklere göz atın.