Ürünlerimiz hakkında görüşlerinizi paylaşmak ve geri bildirimde bulunmak için Google Advertising and Measurement Community sunucusundaki resmi Ad Manager Discord kanalına katılın.

Google, içerikleri tercih ettiğiniz dile çevirmek için yapay zeka teknolojisini kullanır. Yapay zeka çevirilerinde hata olabilir.

Kapsül hizmeti DAI ile ayarlama

Platform seçin: HTML5 Android iOS tvOS Yayınla Roku

Bu kılavuzda, oynatma için hls.js kullanan bir video oynatıcıyla HTML5 için IMA DAI SDK'yı kullanarak 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 Playback desteğiyle tamamlanmış bir örnek entegrasyonu görüntülemek veya takip etmek için HLS kapsül yayınlama örneğini inceleyin. 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ınlama'ya genel bakış

IMA DAI SDK'sını kullanarak kapsül yayınlamayı uygulamak, bu kılavuzda gösterilen iki ana bileşeni içerir:

PodStreamRequest / PodVodStreamRequest: Google'ın reklam sunucularına yönelik bir akış isteğini tanımlayan nesne. İstekler bir Ağ Kodu belirtir ve PodStreamRequest ayrıca bir Özel Öğe Anahtarı ve isteğe bağlı bir API anahtarı gerektirir. Her ikisi de isteğe bağlı diğer parametreleri 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 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 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 bir geliştirme sunucusu başlatmanın hızlı bir yolu, Python'un yerleşik sunucusunu kullanmaktır.

Komut satırını kullanarak index.html dosyanızı içeren dizinden şu komutu çalıştırın:
```
python -m http.server 8000
```
Not: http.server yalnızca Python 3.x'te kullanılabilir.
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.

Video oynatıcı oluşturma

İlk olarak, 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 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ıştırılacak bir initPlayer() işlevini tanımlayın.

Akış isteği sabitleri aşağıdaki gibidir:

BACKUP_STREAM: Reklam işlemi önemli bir hatayla karşılaşırsa oynatılacak yedek akışın URL'si.
STREAM_URL: Yalnızca canlı yayınlar için kullanılır. Kapsül Yayınlama'yı kullanan manifest düzenleyiciniz veya üçü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 girmeniz gerekir. Bu durumda, akış URL'si bir yer tutucu ([[STREAMID]]) içerir ve bu yer tutucu, istek gönderilmeden ö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 yayınlama 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 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="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.js etiketinden önce dai.html dosyasındaki bir komut dosyası etiketini 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şlatma ve canlı veya VOD yayın isteği gönderme

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

Ardından, kapsül yayınlama canlı yayınını 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 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

Ardından, kapsül yayınlama VOD akışını 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ı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 yönetme

Canlı Yayın Kapsül Yayınlama

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

Ayrıca VOD kapsül yayınlama akışları, STREAM_INITIALIZED etkinliğine yanıt olarak StreamManager.loadStreamMetadata() çağrısı yapılmasını gerektirir. 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ü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);
}

Akış 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; yayın biçimine (HLS veya DASH), yayın türüne (canlı veya VOD yayını), oynatıcı türünüze ve kullanılan DAI arka ucunun türüne bağlı olarak değişebilir. Daha fazla bilgi için Zamanlanmış Meta Veriler kılavuzumuzu inceleyin.

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üklenip hazır olduktan sonra videoyu otomatik olarak oynatmak için oynatmayı tetikleyecek 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ı 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 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ı içeren Shaka Player (DASH akışları biçimi)

VOD yayını oynatmak için Shaka Player kullanıyorsanız meta veri etkinliklerini dinlemek için 'timelineregionenter' dizesini kullanın. Ardından, 'urn:google:dai:2018' dizesiyle 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);
       }
}

Oyuncu etkinliklerini yönetme

SDK reklam araları sırasında duraklatıldığında kullanıcının oynatmaya devam etmesine izin vermek 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';
  }
}

IMA DAI öğelerini temizleme

IMA DAI SDK ile kapsül sunma akışında reklam isteme ve gösterme işlemlerini başarıyla tamamladığınızda, kapsül sunma oturumu tamamlandıktan sonra tüm kaynakları temizlemenizi öneririz. Canlı yayın oynatmayı durdurmak, tüm reklam izlemeyi durdurmak ve yüklenen tüm canlı yayın öğelerini serbest bırakmak için StreamManager.destroy() yöntemini çağırın.

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

Kapsül hizmeti DAI ile ayarlama Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

DAI Kapsül Yayınlama'ya genel bakış

Ön koşullar

Geliştirme ortamı yapılandırma

Video oynatıcı oluşturma

dai.html

dai.css

dai.js

IMA DAI SDK'sını yükleme

dai.html

StreamManager'ı başlatma ve canlı veya VOD yayın isteği gönderme

Canlı Yayın Kapsül Yayınlama

dai.js

VOD Kapsül Yayınlama

dai.js

Yayın etkinliklerini yönetme

Canlı Yayın Kapsül Yayınlama

dai.js

VOD Kapsül Yayınlama

Akış meta verilerini işleme

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

DASH.js (DASH akış biçimi, Canlı ve VOD akış türü)

Canlı yayınlarla Shaka Player (DASH akış biçimi)

VOD akışları içeren Shaka Player (DASH akışları biçimi)

Oyuncu etkinliklerini yönetme

IMA DAI öğelerini temizleme

Kapsül hizmeti DAI ile ayarlama