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ı, görüntüleyenlerin konumlarını ve istemci taraflı reklam etkinliklerini izlemek için akışın medya segmentlerine (grup içi meta veriler) veya akış manifest dosyasına (manifest meta verileri) yerleştirilen meta veri bilgilerini kullanır. Meta veriler, oynatılan akışı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 gruplar halinde gösterilebilir. Her meta veri dizesinin, ne zaman tetikleneceğini belirten bir ilişkili sunum zaman damgası (PTS) vardır.

Uygulamanız meta verileri yakalamak ve IMA DAI SDK'sına iletmekten sorumludur. SDK, bu bilgilerin aktarılması için aşağıdaki yöntemleri sunar:

onTimedMetadata

Bu yöntem, işlenmeye hazır olan meta veri dizelerini SDK'ya yönlendirir. Tek bir bağımsız değişken gerektirir:

metadata: Önünde google_ olan ilişkili dize değerine sahip TXXX anahtarını içeren bir nesne.

processMetadata

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

type: İşlenmekte olan etkinliğin türünü içeren bir dize. HLS için ID3 veya DASH için urn:google:dai:2018 kabul edilen değerlerdir.
data: Önünde google_ bulunan bir dize değeri veya böyle bir dizenin kodunu çözen bir bayt dizisi.
timestamp: Verilerin işlenmesi gereken saniye cinsinden zaman damgası.

IMA DAI SDK'sı tarafından desteklenen her akış türü, aşağıdaki bölümlerde açıklanan şekilde 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 segmentlerinin içine yerleştirilir ve TXXX alan adı (özel kullanıcı tanımlı metin içeriği için) verilir.

Safari'de oynat

Safari, ID3 etiketlerini otomatik bir şekilde gizli kanal şeklinde işler. Bu nedenle, işaret değişiklikleri etkinlikleri her bir meta veri parçasını işlemek için doğru zamanda tetiklenir. İçerik veya tür ne olursa olsun tüm meta verilerin IMA DAI SDK'sına iletilmesinde bir sakınca yoktur. Alakasız meta veriler otomatik olarak filtrelenir.

Aşağıda 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 bir örnek dizisi olarak FRAG_PARSING_METADATA etkinliği aracılığıyla gruplar halinde sağlar. HLS.js, ID3 verilerini bayt dizilerinden dizelere çevirmez ve etkinlikleri, karşılık gelen PTS'lerine uyarlamaz. IMA DAI SDK'sı bu kod çözmeyi ve filtrelemeyi otomatik olarak gerçekleştirdiğinden, örnek verilerin bayt dizisinden dizeye dönüştürülmesine veya alakasız ID3 etiketlerinin filtrelenmesine gerek yoktur.

Aşağıda 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 Uygulama Çerçevesi (CMAF) kullanan doğrusal DAI HLS akışları, zamanlanmış meta verileri ID3'ten CMAF'ye kadar bant içi eMSGv1 kutuları üzerinden geçirir. Bu eMSG kutuları, her bir medya segmentinin başına yerleştirilir ve her bir ID3 eMSG, akıştaki son süreksizliğe göre bir PTS içerir.

HLS.js'nin 1.2.0 sürümünden itibaren, önerdiğimiz her iki oynatıcı da CMAF aracılığıyla ID3'ü kullanıcıya ID3 etiketleriymiş gibi geçirmektedir. Bu nedenle, aşağıdaki örnekler HLS MPEG2TS akışları için aynıdır. Ancak bu durum tüm oynatıcılar için geçerli olmayabilir. Bu nedenle, HLS CMAF akışları için destek uygulamak, ID3'ü eMSG aracılığıyla ayrıştırmak için benzersiz bir kod gerektirebilir.

Safari'de oynat

Safari, ID3'ten eMSG meta verilerini sözde ID3 etkinlikleri olarak işler ve bunları otomatik olarak gizli bir kanal şeklinde sağlar. Böylece, işaret değişikliği etkinlikleri, her bir meta veri parçasını işlemek için doğru zamanda tetiklenir. Zamanlamayla ilgili olsun veya olmasın tüm meta verilerin IMA DAI SDK'sına iletilmesinde bir sakınca yoktur. DAI ile ilgili olmayan meta veriler otomatik olarak filtrelenir.

Aşağıda 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

Sürüm 1.2.0'dan itibaren HLS.js, ID3'ü eMSG meta verileri aracılığıyla yapay kimlik3 etkinlikleri olarak işler ve bunları FRAG_PARSING_METADATA etkinliği aracılığıyla gruplar halinde bir örnek dizisi olarak sağlar. HLS.js, ID3 verilerini bayt dizilerinden dizelere çevirmez ve etkinlikleri, karşılık gelen PTS'lerine göre uyarlamaz. IMA DAI SDK'sı kod çözme işlemini otomatik olarak gerçekleştirdiğinden, örnek verilerin bayt dizisinden dizeye dönüştürülmesine gerek yoktur.

Aşağıda 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ışında manifest etkinlikleri olarak aktarır. Bu akışlardaki her etkinlik bir metin yükü ve PTS içerir.

DASH.js

Dash.js, her etkinlik akışının schemaIdUri değerinden adlandırılmış özel etkinlik işleyiciler sağlar. Bu özel işleyiciler gruplar halinde etkinleşerek etkinliği doğru bir şekilde zamanlamak için PTS değerini işlemeyi size bırakır. IMA DAI SDK'sı processMetadata() adlı StreamManager yöntemiyle bu işlemi sizin için gerçekleştirebilir.

Aşağıda 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 Oyuncusu

Shaka Player, timelineregionenter etkinliği kapsamında etkinlikleri öne çıkarıyor. Shaka Player ile biçimlendirme uyumsuzluğu nedeniyle, meta veri değeri, eventElement.attributes['messageData'].value ayrıntı özelliği aracılığıyla ham olarak alınmalıdır.

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

player.addEventListener('timelineregionenter', function(event) {
  const detail = event.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;
    streamManager.processMetadata("urn:google:dai:2018", mediaId, pts);
  }
});
...

Kapsül yayınlama

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

Canlı veya VOD yayın türü
HLS veya DASH akış biçimi
Kullanılan oynatıcının türü
Kullanılan DAI arka ucu türü

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

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

Her şey yüklenip hazır olduktan sonra videoyu otomatik olarak oynatmak için HLS.js MANIFEST_PARSED etkinliğini izleyerek oynatmayı tetikleyin.

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ısı kullanıyorsanız canlı veya VOD akışlarında ID3 meta verilerini dinlemek için farklı dizeler kullanmanız gerekir:

Canlı yayınlar: 'https://developer.apple.com/streaming/emsg-id3'
VOD akışları: 'urn:google:dai:2018'

ID3 meta verilerini StreamManager.processMetadata() ile SDK'ya iletin.

Her şey yüklendikten ve 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ınlar içeren 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ı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, 'urn:google:dai:2018' dizesiyle birlikte StreamManager.processMetadata() çağrınızda yer alan 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);
       }
}