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

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

يتلقى مشغّل الفيديو بيانات وصفية محددة زمنيًا على دفعات. اعتمادًا على اللاعب، فيمكن عرض البيانات الوصفية في الوقت المحدد أو على دفعات. كل بيانات تعريف سلسلة لها طابع زمني مرتبط للعرض التقديمي (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

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

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

التشغيل في Safari

يتعامل Safari مع ID3 من خلال البيانات الوصفية لـ eMSG كأحداث افتراضية 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

اعتبارًا من الإصدار 1.2.0، يتعامل بروتوكول HLS.js مع المعرّف 3 من خلال البيانات الوصفية لـ eMSG على أنّه معرّف زائف 3. بشكل مجمّع من خلال حدث "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 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
• نوع المشغّل المُستخدَم
• نوع الواجهة الخلفية "إدراج إعلان ديناميكي" المستخدَمة

تنسيق البث 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().

لإظهار عناصر التحكم في الفيديو تلقائيًا بعد تحميل كل شيء وجاهزيته، استمع إلى حدث 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 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);
       }
}