IMA DAI SDK'sını kullanmaya başlama

IMA SDK'ları, multimedya reklamlarını 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ıyla uygulamalar, reklam ve içerik videosu (VOD veya canlı içerik) için akış isteğinde bulunur. Daha sonra SDK, uygulamanızın içinde reklam ve içerik videosu arasında geçişi yönetmek zorunda kalmamanız için birleştirilmiş video akışı döndürür.

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

Kapsül yayınlama DAI

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çerikte 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 isterseniz HLS kapsül sunma ö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ınlama işlemini uygulama, bu kılavuzda gösterilen iki ana bileşen içerir:

  • PodStreamRequest / PodVodStreamRequest: Google'ın reklamcılık sunucularına yapılan akış isteğini tanımlayan bir nesne. İstekler bir Ağ Kodu belirtir. PodStreamRequest ayrıca bir Özel Öğe Anahtarı ve bir isteğe bağlı API anahtarı gerektirir. Her ikisi de isteğe bağlı başka parametreler içerir.

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

Ön koşullar

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

  • Üç boş dosya:

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

  • Test için kullanmak üzere bilgisayarınızda yüklü Python veya 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 geliştirme sunucusu başlatmanın hızlı bir yolu, Python'un yerleşik sunucusunu kullanmaktır.

  1. index.html dosya çalıştırmanı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 diğer barındırılan geliştirme ortamlarını veya web sunucularını 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. 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 ekleyin.

Ardından, sayfa öğelerinin boyutunu ve konumunu belirtmek için dai.css dosyasını değiştirin. Son olarak, dai.js'de, akış isteği bilgilerini saklayacak değişkenleri ve sayfa yüklendiğinde çalıştırılacak bir initPlayer() işlevini 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. Manifest düzenleyiciniz veya kapsül sunmayı kullanan üçüncü taraf iş ortağı 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 akış URL'si, istekte bulunmadan önce akış kimliğiyle değiştirilen bir yer tutucu ([[STREAMID]]) içerir.

  • 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 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 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'de bir komut dosyası etiketi kullanarak dai.js etiketinin önüne 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ı veya VOD yayın isteğinde bulunma

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

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

Ardından, canlı yayın sunan kapsülü istemek için bir işlev tanımlayın. Bu işlev önce bir PodStreamRequest oluşturur, 2. adımda sağlanan StreamRequest parametreleriyle yapılandırılır ve daha sonra bu istek nesnesiyle streamManager.requestStream() öğesini ç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ı istemek ve yönetmekten sorumlu olan bir ima.dai.api.StreamManager oluşturun. Oluşturucu bir video öğesi alır ve sonuç olarak elde edilen örnek, reklam etkileşimlerini işlemek için bir reklam kullanıcı arayüzü öğesi alır.

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

Daha sonra, büyük video etkinlikleri için etkinlik işleyiciler uygulayın. Bu örnekte, onStreamEvent() işlevi çağırarak STREAM_INITIALIZED, ERROR, AD_BREAK_STARTED ve AD_BREAK_ENDED etkinlikleri işlenir. Bu işlev, akış yüklemeyi ve hatalarını işlemenin yanı sıra SDK'nın gerektirdiği, reklam oynatılırken oynatıcı kontrollerini devre dışı bırakır. Akış yüklendiğinde, video oynatıcı yüklenir ve sağlanan URL'yi bir loadStream() işlevini 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

Daha sonra, büyük video etkinlikleri için etkinlik işleyiciler uygulayın. Bu örnekte, bir onStreamEvent() işlevi çağırarak STREAM_INITIALIZED, LOADED, ERROR, AD_BREAK_STARTED ve AD_BREAK_ENDED etkinlikleri işlenir. Bu işlev, akış yüklemeyi ve hatalarını işlemenin yanı sıra SDK'nın gerektirdiği, reklam oynatılırken oynatıcı kontrollerini devre dışı bırakır.

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

Akış meta verilerini işleme

Bu adımda, reklam etkinlikleri gerçekleştiğinde SDK'yı bilgilendirmek amacıyla meta veriler için etkinlik işleyiciler uygularsınız. Yayın içi meta veri etkinliklerini dinleme; akış biçimine (HLS veya DASH), akış türüne (canlı veya VOD yayın), oynatıcınızın türüne 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ısı)

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

Her şey yüklendikten ve hazır olduğunda videonun otomatik olarak oynatılması 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 akışlarına yönelik ID3 meta verilerini dinlemek için farklı dizeler kullanmanız gerekir:

  • Canlı yayınlar: 'https://developer.apple.com/streaming/emsg-id3'
  • VOD yayınları: '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 oynatıcı kullanıyorsanız meta veri etkinliklerini dinlemek için 'emsg' dizesini kullanın. Ardından, StreamManager.onTimedMetadata() için yaptığınız aramadaki 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ına sahip 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ızdaki etkinlik mesajı verilerini 'urn:google:dai:2018' dizesiyle 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 oynatmayı devam ettirebilmesi 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. Şu anda HTML5 için IMA DAI SDK'sı ile kapsül yayınlama akışında reklam istiyor ve bu reklamları gösteriyorsunuz. Daha gelişmiş SDK özellikleri hakkında bilgi edinmek için diğer kılavuzları veya GitHub'daki örnekleri inceleyin.