Bu sayfa, Cloud Translation API ile çevrilmiştir.

Doğrusal DAI akışlarında zamanlanmış meta verileri işleme

Interactive Media Ads (IMA) Dinamik Reklam Ekleme (DAI) SDK'sı, izleyici konumlarını ve istemci tarafı reklam etkinliklerini izlemek için yayının medya segmentlerine (bant içi meta veriler) veya akış manifest dosyasına (manifest içi meta veriler) yerleştirilmiş meta veri bilgilerini kullanır. Meta veriler, oynatılan yayının türüne bağlı olarak farklı biçimlerde gönderilir.

Video oynatıcı, zamanlanmış meta verileri gruplar halinde alır. Oynatıcıya bağlı olarak meta veriler planlanan zamanda veya toplu olarak gösterilebilir. Her meta veri dizesinin, tetiklenmesi gereken zamanla ilişkili bir sunum zaman damgası (PTS) vardır.

Meta verileri yakalayıp IMA DAI SDK'sına iletmekten uygulamanız sorumludur. SDK, bu bilgileri iletmek için aşağıdaki yöntemleri sunar:

onTimedMetadata

Bu yöntem, işlenmesi için hazır olan meta veri dizelerini SDK'ya iletir. Tek bir bağımsız değişken alır:

metadata: google_ ön ekiyle ilişkilendirilmiş bir dize değeri içeren TXXX anahtarı içeren bir nesne.

processMetadata

Bu yöntem, meta veri dizelerinin belirtilen PTS'den sonra SDK tarafından işlenmesini planlar. Aşağıdaki bağımsız değişkenleri alır:

type: İşlenen etkinliğin türünü içeren bir dize. Kabul edilen değerler HLS için ID3 veya DASH için urn:google:dai:2018'dir.
data: google_ ön ekiyle başlayan bir dize değeri veya şu biçimi izleyen bir bayt dizisiID3:u\0004u\000u\000u\0000TXXXu\0004u\000u\000u\0000google_xxxxxxxx.
timestamp: Verilerin işlenmesi gereken zaman damgası (saniye cinsinden).

IMA DAI SDK'sı tarafından desteklenen her akış türü, aşağıdaki bölümlerde açıklandığı gibi benzersiz bir zamanlanmış meta veri biçimi kullanır.

HLS MPEG2TS akışları

MPEG2TS segmentlerini kullanan doğrusal DAI HLS akışları, bant içi ID3 etiketleri aracılığıyla zamanlanmış meta verileri video oynatıcıya iletir. Bu ID3 etiketleri MPEG2TS segmentlerine yerleştirilir ve TXXX alan adı (kullanıcı tarafından tanımlanan özel metin içeriği için) verilir.

Safari'de oynatma

Safari, ID3 etiketlerini gizli parça olarak otomatik olarak işler. Böylece, her bir meta veri parçasını işlemek için cuechange etkinlikleri doğru zamanda tetiklenir. İçerik veya türden bağımsız olarak tüm meta verileri IMA DAI SDK'sına iletebilirsiniz. Alakasız meta veriler otomatik olarak filtrelenir.

Aşağıda bununla ilgili bir örnek verilmiştir:

videoElement.textTracks.addEventListener('addtrack', (e) => {
  const track = e.track;
  if (track.kind === 'metadata') {
    track.mode = 'hidden';
    track.addEventListener('cuechange', () => {
      for (const cue of track.activeCues) {
        const metadata = {};
        metadata[cue.value.key] = cue.value.data;
        streamManager.onTimedMetadata(metadata);
      }
    });
  }
});
...

HLS.js

HLS.js, ID3 etiketlerini FRAG_PARSING_METADATA etkinliği aracılığıyla bir örnek dizisi olarak toplu olarak sağlar. HLS.js, ID3 verilerini bayt dizilerinden dizelere çevirmez ve etkinlikleri ilgili PTS'lerine kaydırmaz. IMA DAI SDK'sı bu kod çözme ve filtreleme işlemini otomatik olarak gerçekleştirdiğinden, örnek verilerin bayt dizisinden dizeye kodunun çözülmesi veya alakasız ID3 etiketlerinin filtrelenmesi gerekmez.

Aşağıda bununla ilgili bir örnek verilmiştir:

hls.on(Hls.Events.FRAG_PARSING_METADATA, (e, data) => {
  if (streamManager && data) {
    data.samples.forEach((sample) => {
      streamManager.processMetadata('ID3', sample.data, sample.pts);
    });
  }
});
...

HLS CMAF akışları

Ortak Medya Uygulaması Çerçevesi'ni (CMAF) kullanan doğrusal DAI HLS akışları, CMAF üzerinden ID3 standardını izleyerek bant içi eMSGv1 kutuları aracılığıyla zamanlanmış meta verileri iletir. Bu eMSG kutuları her medya segmentinin başına yerleştirilir. Her ID3 eMSG, akıştaki son kesintiye göre bir PTS içerir.

HLS.js'nin 1.2.0 sürümü itibarıyla, önerilen oynatıcılarımızın ikisi de ID3'yi CMAF üzerinden kullanıcıya ID3 etiketleriymiş gibi iletir. Bu nedenle, aşağıdaki örnekler HLS MPEG2TS akışlarıyla aynıdır. Ancak bu durum tüm oynatıcılarda geçerli olmayabilir. Bu nedenle, HLS CMAF akışları için destek uygulamak, ID3'ün eMSG aracılığıyla ayrıştırılması için benzersiz kod gerektirebilir.

Safari'de oynatma

Safari, eMSG meta verileri aracılığıyla ID3'yi sözde ID3 etkinlikleri olarak ele alır ve bunları gruplar halinde, otomatik olarak gizli bir parça olarak sağlar. Böylece cuechange etkinlikleri, her bir meta veri parçasını işlemek için doğru zamanda tetiklenir. Zamanlamayla alakalı olsun veya olmasın tüm meta verileri IMA DAI SDK'sına iletebilirsiniz. DAI ile ilgili olmayan tüm meta veriler otomatik olarak filtrelenir.

Aşağıda bununla ilgili bir örnek verilmiştir:

videoElement.textTracks.addEventListener('addtrack', (e) => {
  const track = e.track;
  if (track.kind === 'metadata') {
    track.mode = 'hidden';
    track.addEventListener('cuechange', () => {
      for (const cue of track.activeCues) {
        const metadata = {};
        metadata[cue.value.key] = cue.value.data;
        streamManager.onTimedMetadata(metadata);
      }
    });
  }
});
...

HLS.js

1.2.0 sürümü itibarıyla HLS.js, eMSG meta verileri aracılığıyla ID3'yi sözde ID3 etkinlikleri olarak değerlendirir ve bunları FRAG_PARSING_METADATA etkinliği aracılığıyla bir örnek dizisi olarak toplu olarak sağlar. HLS.js, ID3 verilerini bayt dizilerinden dizelere çevirmez ve etkinlikleri ilgili PTS'lerine kaydırmaz. IMA DAI SDK'sı bu kod çözme işlemini otomatik olarak gerçekleştirdiğinden, örnek verilerin bayt dizisinden dizeye kodunun çözülmesi gerekmez.

Aşağıda bununla ilgili bir örnek verilmiştir:

hls.on(Hls.Events.FRAG_PARSING_METADATA, (e, data) => {
  if (streamManager && data) {
    data.samples.forEach((sample) => {
      streamManager.processMetadata('ID3', sample.data, sample.pts);
    });
  }
});
...

DASH akışları

Doğrusal DAI DASH akışları, meta verileri özel schemeIdUri değeri urn:google:dai:2018 ile bir etkinlik akışındaki manifest etkinlikleri olarak iletir. Bu akışlardaki her etkinlik bir metin yükü ve PTS içerir.

DASH.js

Dash.js, her etkinlik akışının schemeIdUri değerinden sonra adlandırılan özel etkinlik işleyicileri sağlar. Bu özel işleyiciler toplu olarak tetiklenir. Bu nedenle, etkinliği doğru zamanlamak için PTS değerini işlemek size kalır. IMA DAI SDK'sı, streamManager yöntemi (processMetadata()) ile bunu sizin için halledebilir.

Aşağıda bununla ilgili bir örnek verilmiştir:

const dash = dashjs.MediaPlayer().create();
dash.on('urn:google:dai:2018', (payload) => {
  const mediaId = payload.event.messageData;
  const pts = payload.event.calculatedPresentationTime;
  streamManager.processMetadata('urn:google:dai:2018', mediaId, pts);
});
...

Shaka Player

Shaka Player, etkinlikleri timelineregionenter etkinliğinin bir parçası olarak gösterir. Shaka Player ile biçimlendirme uyumsuzluğu nedeniyle meta veri değeri, ayrıntı özelliği eventNode.attributes['messageData'] aracılığıyla ham olarak alınmalıdır.

Aşağıda bununla ilgili bir örnek verilmiştir:

player.addEventListener('timelineregionenter', function(event) {
  const detail = event.detail;
  if ( detail.eventNode.attributes &&
       detail.eventNode.attributes['messageData']) {
    const mediaId = detail.eventNode.attributes['messageData'];
    const pts = detail.startTime;
    streamManager.processMetadata("urn:google:dai:2018", mediaId, pts);
  }
});
...

Kapsül yayınlama

Kapsül yayınlama için zamanlanmış meta verileri aktarmayla ilgili olarak aşağıdaki ölçütlere bağlı olarak farklı yapılandırmalar vardır:

Canlı veya seç-izle yayın türü
HLS veya DASH yayın biçimi
Kullanılan oynatıcı türü
Kullanılan DAI arka uç türü

HLS akış biçimi (canlı ve seç-izle yayınlar, 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ı 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ışları biçimi, Canlı ve VOD akış türü)

DASH.js oynatıcı kullanıyorsanız canlı veya seç-izle yayınların ID3 meta verilerini dinlemek için 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 aktarın.

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ınları destekleyen 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

Seç-izle akışı 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ı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);
       }
}