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

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

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

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

onTimedMetadata

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

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

processMetadata

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

• 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 غير الملائمة، لأنّ أداة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية تُجري عملية فك الترميز والفلترة تلقائيًا.

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

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 هذه في بداية كل قطاع من الوسائط، بحيث يحتوي كل معرّف eMSG على معرّف 3 على نقطة اتصال مرتبطة بآخر انقطاع في البث.

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

التشغيل في Safari

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

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

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 DASH الخطية البيانات الوصفية كأحداث بيان في بث حدث باستخدام قيمة 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);
});
...

لاعب شاكا

ملاحظة: إذا كنت تستخدم دعم DAI المضمّن في Shaka Player، لن تحتاج إلى معالجة البيانات الوصفية المحدّدة زمنيًا يدويًا. تنطبق هذه النصيحة على المستخدمين المتقدمين الذين ينفّذون يدويًا حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية باستخدام مشغّل Shaka.

يعرض 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 للحصول على البيانات الوصفية لرقم التعريف 3 وتمريرها إلى حزمة تطوير البرامج (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'

نقْل البيانات الوصفية لرقم التعريف 3 إلى حزمة تطوير البرامج (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 لتشغيل أحداث البث المباشر (تنسيق البث DASH)

إذا كنت تستخدم مشغّل Shaka لتشغيل البث المباشر، استخدِم السلسلة '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 لتشغيل الفيديوهات عند الطلب (بتنسيق DASH)

إذا كنت تستخدم مشغِّل Shaka لتشغيل فيديو عند الطلب، استخدِم السلسلة '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);
       }
}