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ı herhangi birinden reklam iste VAST uyumlu reklam sunucusu oluşturup uygulamalarınızda reklam oynatmayı yönetin. 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çme

Kapsül yayınlama DAI

Bu kılavuzda, DAI Kapsül Yayınlama yayınının canlı veya VOD için nasıl oynatılacağı gösterilmektedir içeriği kullanarak, hls.js tabanlı bir video oynatıcı ile HTML5 için IMA DAI SDK'sını kullanarak oynatma için. 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ı kullanarak kapsül yayınlama uygulaması iki ana bileşen içerir. aşağıda açıklanmıştır:

  • 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 isteğe bağlı başka parametreler içerir.

  • StreamManager: Şu öğeler arasındaki iletişimi işleyen bir nesne: izleme ping'lerini tetikleme ve IMA DAI SDK'sını kullanma gibi, 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, web sunucusu veya barındırılan başka bir geliştirme test için kullanılacak ortam

Geliştirme ortamı yapılandırma

SDK, bağımlılıkları şu sayfayla aynı protokolü kullanarak yüklediğinden: 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

    Ayrıca, istemciler ve güvenlik açıkları gibi, barındırılan Apache HTTP Server olarak ayarlamanız gerekir.

Basit bir video oynatıcı oluşturma

Öncelikle dai.html dosyasını değiştirerek basit bir HTML5 video öğesi ve kullanımı hakkında daha fazla bilgi edinin. 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 süreci izlemesi durumunda oynatılacak bir yedek akışın URL'si önemli bir hatayla karşılaştığını varsayalım.

  • 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 girmenizi gerektirir: 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 akış kimliğini almak için gereklidir.

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'de bir komut dosyası etiketi kullanarak DAI çerçevesini etiketin önüne ekleyin dai.js için

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

Reklam grubu istemek için bir ima.dai.api.StreamManager oluşturun. DAI akışlarını istemekten ve yönetmekten sorumludur. 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, canlı yayın sunan kapsülü istemek için bir işlev tanımlayın. Bu işlev ilk olarak bir PodStreamRequest 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)

  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

Reklam grubu istemek için bir ima.dai.api.StreamManager oluşturun. DAI akışlarını istemekten ve yönetmekten sorumludur. 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ü istemek için 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, STREAM_INITIALIZED, LOADED, ERROR, AD_BREAK_STARTED ve onStreamEvent() işlevi çağırarak AD_BREAK_ENDED etkinlik. Bu işlevi, akış yüklemeyi ve hataları işlemenin yanı sıra oynatıcıyı devre dışı bırakma , SDK'nın gerektirdiği şekilde bir reklam oynatılırken kontrol eder.

Ayrıca, VOD kapsül yayınlama akışları için çağrı gerekir StreamManager.loadStreamMetadata() tarihinde STREAM_INITIALIZED etkinliği. Ayrıca, video teknolojisi iş ortağı (VTP) ile iletişime geçebilirsiniz. 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, aşağıdaki durumlarda SDK'yı bilgilendirmek amacıyla meta veriler için etkinlik işleyicileri uygularsınız: reklam etkinliklerinin gerçekleşmesidir. Yayın içi meta veri etkinliklerini dinleme yayın biçimi (HLS veya DASH), yayın türü (Canlı veya VOD yayın), oynatıcı türü ve kullanılan DAI arka ucunun türü gibi. Bkz. Zamanlanmış Meta veri rehberini inceleyin.

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

HLS.js oynatıcısı kullanıyorsanız şunu dinleyin: HLS.js FRAG_PARSING_METADATA etkinliğini kullanarak ID3 meta verilerini almak ve StreamManager.processMetadata() sürümüne sahip SDK.

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 videolar için ID3 meta verilerini dinlemek üzere farklı dizeler kullanmanız gerekir. akışlar:

  • 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ü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)

Oyun için Shaka Player'ı 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)

Oyun için Shaka Player'ı VOD akışı oynatma, dinlemek için 'timelineregionenter' dizesini kullanın meta veri etkinlikleridir. Ardından, aramanızdaki etkinlik mesajı verilerini kullanarak StreamManager.processMetadata() 'urn:google:dai:2018' dizesi için.

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 aşağıdakilerle kapsül yayınlama akışında reklam istiyor ve gösteriyorsunuz: HTML5 için IMA DAI SDK'sı. Daha gelişmiş SDK özellikleri hakkında bilgi edinmek için veya buradaki örneklerden GitHub'ı tıklayın.