معالجة البيانات الوصفية المحددة بوقت في ساحات مشاركات DAI الخطية

تعتمد حزمة تطوير البرامج لإدراج الإعلانات الديناميكية (DAI) لإعلانات الوسائط التفاعلية على معلومات بيانات وصفية مضمّنة في شرائح وسائط البث (البيانات الوصفية ضمن النطاق) أو في ملف بيان البث (البيانات الوصفية ضمن العرض) لتتبُّع مواضع المشاهدين وأحداث الإعلانات من جهة العميل. يتم إرسال البيانات الوصفية بتنسيقات مختلفة حسب نوع البث الذي يتم تشغيله.

يتلقى مشغّل الفيديو البيانات الوصفية ذات التوقيت المحدد على دفعات. اعتمادًا على المشغّل، يمكن عرض البيانات التعريفية في الوقت المحدّد أو على دفعات. لكل سلسلة بيانات وصفية طابع زمني مرتبط للعرض التقديمي (PTS) لتحديد وقت تشغيلها.

يكون تطبيقك مسؤولاً عن تسجيل البيانات الوصفية وإعادة توجيهها إلى "حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية". توفر حزمة SDK الطرق التالية لتمرير هذه المعلومات:

onTimedMetadata

تعيد هذه الطريقة توجيه سلاسل البيانات الوصفية الجاهزة للمعالجة إلى حزمة تطوير البرامج (SDK). يتطلب ذلك وسيطة واحدة:

• metadata: كائن يحتوي على مفتاح TXXX مع قيمة سلسلة مرتبطة مسبوقة بـ google_.

processMetadata

تعمل هذه الطريقة على جدولة سلاسل البيانات الوصفية التي ستعالجها حزمة تطوير البرامج (SDK) بعد بروتوكول PTS المحدَّد. يتطلب هذا الأمر الوسيطات التالية:

• type: سلسلة تحتوي على نوع الحدث الذي تتم معالجته. القيم المقبولة هي ID3 لبروتوكول HLS أو urn:google:dai:2018 لبروتوكول DASH
• data: إما قيمة سلسلة مسبوقة بـ google_ أو صفيف بايت يتم فك ترميزه لمثل هذه السلسلة.
• timestamp: الطابع الزمني بالثواني عندما يجب معالجة البيانات.

إنّ كل نوع من أنواع البث المتوافقة مع "حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية" يستخدم نموذجًا فريدًا من البيانات الوصفية الموقّتة على النحو الموضّح في الأقسام التالية.

مجموعات البث HLS MPEG2TS

في عمليات بث DAI HLS الخطية باستخدام مقاطع MPEG2TS، يتم تمرير البيانات الوصفية المحددة بوقت إلى مشغّل الفيديو من خلال علامات ID3 ضمن النطاق. يتم تضمين علامات ID3 هذه ضمن مقاطع MPEG2TS ويتم منحها اسم حقل TXXX (للمحتوى النصي المخصص من تحديد المستخدم).

التشغيل في Safari

يعالج Safari علامات ID3 تلقائيًا كمسار مخفي، لذا يتم تنشيط أحداث تغيير الإشارات في الوقت المناسب لمعالجة كل جزء من البيانات الوصفية. يمكن تمرير كل البيانات الوصفية إلى حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية، بصرف النظر عن المحتوى أو النوع. تتم تصفية بيانات التعريف غير ذات الصلة تلقائيًا.

وفي ما يلي مثال لذلك:

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 على دفعات من خلال حدث FRAG_PARSING_METADATA، كصفيف من النماذج. لا يترجم HLS.js بيانات ID3 من صفائف البايت إلى سلاسل ولا يعوض الأحداث إلى PTS المقابلة لها. ليس من الضروري فك ترميز عينة البيانات من مصفوفة بايت إلى سلسلة، أو فلترة علامات ID3 غير ذات الصلة، لأنّ حزمة IMA DAI SDK تنفذ عملية فك الترميز والفلترة هذه تلقائيًا.

وفي ما يلي مثال لذلك:

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

في عمليات بث DAI HLS الخطية باستخدام إطار عمل الوسائط المشتركة (CMAF)، يتم تمرير البيانات الوصفية المحددة بوقت من خلال مربعات eMSGv1 ضمن النطاق باتّباع معيار ID3 إلى CMAF. يتم تضمين صناديق eMSG هذه في بداية كل قطاع من الوسائط، ويحتوي كل ملف ID3 eMSG على "PTS" مقارنةً بآخر انقطاع في البث.

اعتبارًا من الإصدار 1.2.0 من HLS.js، يمرّر كلا المشغّلين المقترَحين معرّف 3 من خلال CMAF للمستخدم كما لو كانت علامات ID3. لهذا السبب، تنطبق الأمثلة التالية على مجموعات البث HLS MPEG2TS. مع ذلك، قد لا ينطبق ذلك على جميع اللاعبين، لذلك قد يتطلّب دعم مصادر بث HLS CMAF رمزًا فريدًا لتحليل المعرّف 3 من خلال eMSG.

التشغيل في Safari

يتعامل Safari مع ID3 من خلال البيانات الوصفية eMSG كأحداث Peudo ID3، ويضيفها بشكل تلقائي على أنّها مسارات مخفيّة، مثلاً كي يتم تنشيط أحداث cuechange في الوقت الصحيح لمعالجة كل جزء من البيانات الوصفية. ويمكن تمرير جميع البيانات الوصفية إلى حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية، سواء كانت مرتبطة بالتوقيت أم لا. وتتم فلترة أي بيانات وصفية غير مرتبطة بميزة DAI تلقائيًا.

وفي ما يلي مثال لذلك:

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، يتعامل HLS.js مع المعرّف 3 من خلال البيانات الوصفية لـ eMSG باعتبارها أحداثًا زائفة ID3، يوفّرها على دفعات من خلال حدث FRAG_PARSING_METADATA، كمجموعة من النماذج. لا يترجم HLS.js بيانات ID3 من صفائف البايت إلى سلاسل ولا يُعوض الأحداث إلى PTS المقابلة لها. ليس من الضروري فك ترميز نموذج البيانات من مصفوفة بايت إلى سلسلة، لأنّ حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية تُجري عملية فك الترميز هذه تلقائيًا.

وفي ما يلي مثال لذلك:

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

مجموعات بث DASH

تنقل أحداث البث DAI المجدوَلة البيانات الوصفية كأحداث بيان في بث حدث باستخدام قيمة schemeIdUri المخصّصة urn:google:dai:2018. يحتوي كل حدث في مجموعات البث هذه على حمولة نصية وPTS.

DASH.js

توفر Dash.js معالِجات أحداث مخصصة تحمل قيمة schemeIdUri لكل بث حدث. تعمل هذه المعالِجات المخصَّصة على تنشيطها على دفعات، ما يتيح لك معالجة قيمة بروتوكول PTS من أجل ضبط وقت الحدث بشكل صحيح. يمكن لحزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية معالجة هذا الإجراء نيابةً عنك باستخدام طريقة StreamManager، أي processMetadata().

وفي ما يلي مثال لذلك:

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 الأحداث كجزء من حدث timelineregionenter. بسبب عدم توافق التنسيق مع Shaka Player، يجب استرداد قيمة البيانات الوصفية بتنسيق أولي، من خلال خاصية التفاصيل eventElement.attributes['messageData'].value.

وفي ما يلي مثال لذلك:

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);
  }
});
...

عرض الكبسولات

بالنسبة إلى عرض الإعلانات المتسلسلة، تتوفّر إعدادات مختلفة لتمرير البيانات الوصفية المؤقّتة استنادًا إلى المعايير التالية:

• نوع بث مباشر أو فيديو عند الطلب
• تنسيق البث HLS أو DASH
• نوع المشغّل الذي يتم استخدامه
• نوع خلفية DAI المستخدمة

تنسيق البث HLS (أحداث البث المباشر والفيديوهات عند الطلب، مشغّل HLS.js)

إذا كنت تستخدم مشغِّل HLS.js، استمع إلى حدث HLS.js FRAG_PARSING_METADATA للحصول على البيانات الوصفية من ID3 وتمريرها إلى حزمة تطوير البرامج (SDK) باستخدام StreamManager.processMetadata().

لتشغيل الفيديو تلقائيًا بعد أن يتم تحميل الفيديو وجاهزيته، استمِع إلى حدث HLS.js MANIFEST_PARSED لبدء التشغيل.

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، نوع البث المباشر والفيديوهات عند الطلب)

إذا كنت تستخدم مشغِّل DASH.js، عليك استخدام سلاسل مختلفة للاستماع إلى بيانات ID3 الوصفية لأحداث البث المباشر أو الفيديوهات عند الطلب:

• أحداث البث المباشر: 'https://developer.apple.com/streaming/emsg-id3'
• عدد مشاهدات الفيديوهات عند الطلب: 'urn:google:dai:2018'

مرِّر البيانات الوصفية من ID3 إلى حزمة تطوير البرامج (SDK) باستخدام StreamManager.processMetadata().

لعرض عناصر التحكّم في الفيديو تلقائيًا بعد تحميل كل العناصر وجاهزيتها، استمِع إلى حدث MANIFEST_LOADED على DASH.js.

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);
}

Shaka Player مع أحداث بث مباشر (تنسيق أحداث البث DASH)

إذا كنت تستخدم Shaka Player لتشغيل البث المباشر، استخدِم السلسلة 'emsg' للاستماع إلى أحداث البيانات الوصفية. بعد ذلك، استخدِم بيانات رسالة الحدث في مكالمتك على الرقم StreamManager.onTimedMetadata().

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});
}

Shaka Player مع فيديوهات متوفرة عند الطلب (تنسيق DASH)

إذا كنت تستخدم Shaka Player لتشغيل بث الفيديو عند الطلب، استخدِم السلسلة 'timelineregionenter' للاستماع إلى أحداث البيانات الوصفية. بعد ذلك، استخدِم بيانات رسالة الحدث في الطلب StreamManager.processMetadata() مع السلسلة 'urn:google:dai:2018'.

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);
       }
}