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

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

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

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

onTimedMetadata

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

• ‫metadata: عنصر يحتوي على مفتاح TXXX مع قيمة سلسلة مرتبطة تتم إضافة google_ إليها في البداية

processMetadata

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

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

يستخدم كل نوع من أنواع مصادر البيانات المتوافقة مع حزمة IMA DAI SDK شكلاً فريدًا من metadata المبرمَجة، كما هو موضّح في الأقسام التالية.

مصادر بيانات HLS MPEG2TS

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

التشغيل في Safari

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

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

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

أحداث البث المباشر وفق بروتوكول HTTP باستخدام CMAF

إنّ أحداث HLS المباشرة التي تستخدم ميزة DAI وتستند إلى إطار عمل Common Media Application Framework (CMAF) تُرسِل ملفًا متضمّنًا لبيانات وصفية موقّتة من خلال مربّعات eMSGv1 ضمن النطاق وفقًا لمعيار ID3 من خلال CMAF. يتم تضمين مربّعات eMSG هذه في بداية كل جزء من الوسائط، ويحتوي كل مربّع eMSG من النوع ID3 على PTS بالنسبة إلى آخر انقطاع في البث.

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

التشغيل في Safari

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

تُرسِل أحداث DASH المباشرة غير القابلة للتقديم أو الإيقاف (DAI) للمحتوى المجدوَل البيانات الوصفية كأحداث بيان في بث أحداث باستخدام القيمة المخصّصة schemeIdUri urn:google:dai:2018. يحتوي كل حدث في هذين البثَّين على حمولة نصية وقيمة PTS.

DASH.js

توفّر Dash.js معالجات أحداث مخصّصة يتم تسميتها حسب قيمة schemeIdUri لكل مجرى حدث. يتم تنشيط هذه المعالِجات المخصّصة بشكلٍ مجمّع، ما يترك لك مهمة معالجة قيمة PTS لتحديد وقت الحدث بشكلٍ صحيح. يمكن لحزمة تطوير البرامج لإدراج إعلان ديناميكي في إعلانات الوسائط التفاعلية (IMA DAI SDK) التعامل مع هذا الأمر نيابةً عنك، باستخدام طريقة 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

يعرض Shaka Player الأحداث كجزء من حدث timelineregionenter. بسبب عدم توافق التنسيق مع Shaka Player، يجب استرجاع قيمة البيانات الوصفية في شكلها الأصلي من خلال سمة التفاصيل eventNode.attributes['messageData'].

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

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

عرض مجموعة الإعلانات

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

• نوع البث المباشر أو الفيديو عند الطلب
• تنسيق البث المباشر وفق بروتوكول HTTP ‏(HLS) أو DASH
• نوع المشغّل المستخدَم
• نوع الخلفية المستخدَمة في ميزة "الإعلانات أثناء التشغيل"

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

إذا كنت تستخدِم مشغّل HLS.js، استمع إلى حدث FRAG_PARSING_METADATA في HLS.js للحصول على البيانات الوصفية بتنسيق 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().

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

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' للاستماع إلى أحداث metadata. بعد ذلك، استخدِم بيانات رسالة الحدث في طلبك المرسَل إلى 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);
       }
}