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 ile 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ği. SDK, daha sonra Böylece, reklam ve içerik videosu arasında geçiş yönetmek zorunda kalmazsınız. bir kontrol listesidir.

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

DAI kapsülü yayınlama

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. Tamamlanmış bir örneği görüntülemek veya takip etmek isterseniz entegrasyonu için aşağıdaki adımları uygulayın: HLS.js ve Safari Oynatma HLS kapsül yayınlama örneği. DASH.js desteği için DASH kapsülü sunma örneğine bakın. Bu örnek uygulamaları HTML5 DAI GitHub sürümünden indirebilirsiniz öğrenin.

DAI Kapsül Yayınlamaya 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: Şu akış isteğini tanımlayan bir nesne: Google'ın reklam sunucuları. İstekler bir Ağ Kodu ve PodStreamRequest ayrıca bir Özel Öğe Anahtarı ve isteğe bağlı bir API anahtarı. Her ikisi de diğer isteğe bağlı parametreleri içerir.

  • StreamManager: Şu öğeler arasındaki iletişimi işleyen bir nesne: ve IMA DAI SDK'sını (örneğin, izleme ping'lerini tetikleme ve akış etkinliklerini yayıncıya yönlendirme.

Ö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üklendikten sonra, uygulamanızı test etmek için bir web sunucusu kullanmanız gerekir. Hızlı Python'un yerleşik sunucusunu kullanmaktır.

  1. index.html dosyanızı içeren dizinden, bir komut satırı kullanarak dosya çalıştırma:

    python -m http.server 8000

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

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

Basit bir video oynatıcı oluşturma

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

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 tanımlayın. ve sayfa yüklendiğinde çalıştırılacak bir initPlayer() işlevi.

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. tarafından sağlanan video akışı URL'si manifest düzenleyiciniz veya üçüncü taraf iş ortağınız aracılığıyla hazırlayın. Uygulama aktarmadan önce, IMA DAI SDK'sı tarafından sağlanan akış kimliğini istekte bulunabilirsiniz. Bu durumda, akış URL'si bir yer tutucu içerir. [[STREAMID]], 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. Oluşturduğunuz Ad Manager 360'ta kapsül yayınlama etkinliğinizi tanımlar. Bu, şunlar tarafından oluşturulabilir: manifest düzenleyiciniz veya üçüncü taraf kapsül sunma iş ortağınız.

  • 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ş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ı istemekten ve yönetmekten sorumlu 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, 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ı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 öğesidir ve sonuçta elde edilen örnek reklamı işlemek için bir reklam kullanıcı arayüzü öğesi alır etkileşimleridir.

Ardından, VOD akışı sunan kapsülü isteyecek bir işlev tanımlayın. Bu işlev ilk olarak bir PodVodStreamRequest oluşturur ve bunu StreamRequest ile yapılandırır Parametreler 2. adımda sağlanır ve streamManager.requestStream() öğesini çağırır ekleyebilirsiniz.

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, STREAM_INITIALIZED, ERROR, AD_BREAK_STARTED ve AD_BREAK_ENDED etkinlikleri için onStreamEvent() işlevini çağırın. Bu işlev, akışı işler yükleme ve hataların yanı sıra, reklam gösterilirken oynatıcı kontrollerini devre dışı bırakma (SDK'nın gerektirdiği bir oyundur.) Akış yüklendiğinde video oynatıcı, sağlanan URL'yi bir loadStream() işlevini kullanarak yükleyip 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, 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 çağrı gerekir StreamManager.loadStreamMetadata() tarihinde STREAM_INITIALIZED etkinliği. Video teknolojisi iş ortağından (VTP) da bir yayın URL'si istemeniz gerekir. loadStreamMetadata() çağrısı başarılı olduğunda loadStream() işlevini çağırmanız gereken bir LOADED etkinliğini tetikler. akışı yükleyip oynatmak için akış URL'nizi ekleyin.

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 dinleyicileri 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. Bkz. Zamanlanmış Meta veri rehberini inceleyin.

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

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 sonra videoyu otomatik olarak oynatmak için şunu dinleyin: Oynatmayı tetiklemek için HLS.js MANIFEST_PARSED etkinliğini kullanın.

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 seç-izle akışlar için ID3 meta verilerini dinlemek üzere 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 iletin.

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ı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 yayınları (DASH yayınları biçimi) içeren Shaka Player

Oyun için Shaka Player'ı VOD akışı oynatma, dinlemek için 'timelineregionenter' dizesini kullanın meta veri etkinlikleridir. 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

İzin vermek için video öğesinin pause ve start etkinliklerine etkinlik işleyiciler ekleyin Kullanıcının, SDK reklam araları sırasında durakladığında oynatmaya devam etmesini sağlar.

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