بدء استخدام حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية

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

اختيار حلّ DAI الذي يهمّك

الخدمة الكاملة عرض مجموعة فيديوهات Cloud stitching API Live Cloud stitching API VOD

تشغيل أحداث الفيديوهات المسجّلة المسجّلة في Google Cloud Video Stitcher API

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

يوضّح هذا الدليل المزيد من المعلومات حول المثال الأساسي من دليل البدء لإدراج الإعلانات الديناميكية أثناء عرض الفيديو (IMA DAI).

للحصول على معلومات عن الدمج مع الأنظمة الأساسية الأخرى أو استخدام حِزم تطوير البرامج (SDK) من جهة العميل لإعلانات الوسائط التفاعلية، يُرجى الاطّلاع على حِزم تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية.

للاطّلاع على نموذج تكامل مكتمل أو اتّباعه، نزِّل مثال أدوات دمج الفيديوهات في Cloud لتنسيق HLS أو DASH.

ملاحظة: تتيح أداة تطوير برامج IMA DAI لبرنامج HTML5 إمكانية عرض كلّ من أحداث البث بتنسيق HLS وDASH، ولكنّ تشغيل كلّ منهما يتطلّب استخدام مشغّل وسائط أو إضافة مختلفة، مثل HLS.js أو DASH.js، مع اختلافات في عمليات التنفيذ.

يوضّح هذا الدليل كيفية ضبط HLS.js وIMA DAI SDK لتشغيل بث HLS، مع ملاحظات مهمة حول الاختلافات في التنفيذ لتنسيق DASH.

اطّلِع على IMA نموذج تطبيق DASH.js للحصول على نقطة بداية لتنفيذ أحداث DASH DAI باستخدام IMA.

إعداد مشروع على Google Cloud

إعداد مشروع على Google Cloud وضبط حسابات الخدمة للوصول إلى المشروع

أدخِل المتغيّرات التالية لاستخدامها في حزمة تطوير البرامج لإعلانات الوسائط التفاعلية:

الموقع الجغرافي

منطقة Google Cloud التي تم فيها إنشاء إعدادات الفيديوهات عند الطلب: LOCATION

رقم المشروع

رقم مشروع Google Cloud الذي يستخدم Video Stitcher API: PROJECT_NUMBER

الرمز المميّز لبروتوكول OAuth

رمز مميّز OAuth قصير العمر لحساب الخدمة مع دور مستخدم "مُوصِّل الفيديوهات":

OAUTH_TOKEN

يمكنك الاطّلاع على مزيد من المعلومات حول إنشاء علامات OAuth مؤقتة. يمكن إعادة استخدام الرمز المميّز لبروتوكول OAuth في طلبات متعددة طالما أنّه لم يتم انتهاء صلاحيته.

رمز الشبكة

رمز شبكة "مدير إعلانات Google" لطلب الإعلانات: NETWORK_CODE

رقم تعريف إعداد الفيديوهات عند الطلب

رقم تعريف إعداد الفيديو عند الطلب لبث الفيديو عند الطلب: VOD_CONFIG_ID

يمكنك الاطّلاع على مزيد من المعلومات حول إنشاء معرّف إعدادات الفيديوهات عند الطلب في دليل إنشاء إعدادات الفيديوهات عند الطلب باستخدام ميزة "الربط في السحابة الإلكترونية".

ضبط بيئة تطوير

نقطة رئيسية: تتيح فئة VideoStitcherVodStreamRequest لتنسيق DAI في IMA إمكانية استخدام كلّ من خلاصات HLS وخلاصات DASH متعددة الفترات. يتم إدراج الفواصل الإعلانية فقط بين فترات DASH.

لا تعرض نماذج تطبيقات IMA سوى طلبات أحداث البث باستخدام بروتوكول HLS. سيظل بإمكانك استخدام DASH streams عند إنشاء فئة VideoStitcherVodStreamRequest. عند إعداد مشغّل متوافق مع DASH، عليك إعداد مستمع لأحداث التقدّم في مشغّل الفيديو الذي يمكنه تقديم البيانات الوصفية للفيديو إلى StreamManager.processMetadata(). تأخذ هذه الدالة ثلاث مَعلمات:

1. ‫type: سلسلة يجب ضبطها على 'ID3' لأحداث البث المباشر وفق بروتوكول HLS و'urn:google:dai:2018' لأحداث البث المباشر وفق بروتوكول DASH

2. data: بالنسبة إلى رسائل أحداث DASH، هذه هي سلسلة بيانات الرسالة.

3. timestamp: رقم يمثّل وقت بدء رسالة الحدث لملفات DASH البث

أرسِل البيانات الوصفية في أقرب وقت ممكن وبقدر الإمكان من خلال أحداث المشغّل. إذا كانت metadata مفقودة أو غير صحيحة، قد لا تؤدي حزمة تطوير البرامج IMA DAI SDK إلى بدء أحداث الإعلانات، مما يؤدي إلى الإبلاغ عن أحداث الإعلانات بشكل غير صحيح.

نزِّل أمثلة IMA DAI لملف HTML5 واستخرِج ملف zip الذي يتضمّن hls_js/simple نموذجًا في مجلد جديد. هذا المثال هو تطبيق ويب يمكنك استضافته محليًا لأغراض الاختبار.

لاستضافة المثال محليًا، انتقِل إلى المجلد الجديد وشغِّل الأمر التالي python لبدء خادم ويب:

python3 -m http.server 8000

لا يتوفّر http.server إلا في Python 3.x. يمكنك استخدام أي خادم ويب آخر، مثل Apache HTTP Server أو Node JS.

افتح متصفّح ويب وانتقِل إلى localhost:8000 لعرض مشغّل فيديو. يجب أن يكون المتصفّح متوافقًا مع مكتبة HLS.js.

إذا كان كل شيء يعمل على النحو المطلوب، سيؤدي النقر على زر التشغيل في مشغّل الفيديو إلى بدء عرض الفيلم القصير "Tears of Steel"، مع عرض فواصل إعلانية كل 30 ثانية.

طلب بث فيديو مسجّل

لاستبدال بث العيّنة ببث الفيديو عند الطلب الذي تمّت فيه إزالة الفواصل الإعلانية، استخدِم فئة VideoStitcherVodStreamRequest لإنشاء جلسة إعلان تلقائيًا باستخدام "مدير إعلانات Google". يمكنك استخدام واجهة مستخدم "مدير إعلانات Google" من أجل تحديد جلسات DAI التي تم إنشاؤها للتتبّع وتصحيح الأخطاء.

في النموذج الحالي، تتوفّر دوال لطلب بث فيديو مسجّل أو بث مباشر. لكي تعمل هذه الوظيفة مع Google Cloud Video Stitcher API، عليك إضافة وظيفة جديدة لعرض عنصر VideoStitcherVodStreamRequest.

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

// StreamManager which will be used to request DAI streams.
let streamManager;
...

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(
    videoElement,
    adUiElement
  );
  streamManager.addEventListener(
    [
      google.ima.dai.api.StreamEvent.Type.LOADED,
      google.ima.dai.api.StreamEvent.Type.ERROR,
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED
    ],
    onStreamEvent, false);

  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
    if (streamManager && data) {
      // For each ID3 tag in our metadata, we pass in the type - ID3, the
      // tag data (a byte array), and the presentation timestamp (PTS).
      data.samples.forEach(function(sample) {
        streamManager.processMetadata('ID3', sample.data, sample.pts);
      });
    }
  });

  videoElement.addEventListener('pause', () => {
    playButton.style.display = "block";
  });

  playButton.addEventListener('click', initiatePlayback);
}

function initiatePlayback() {
  requestVodVideoStitcherStream();

  playButton.style.display = "none";
  playButton.removeEventListener('click', initiatePlayback);
  playButton.addEventListener('click', resumePlayback);
}
...
function requestVodVideoStitcherStream() {
  const streamRequest = new google.ima.dai.api.VideoStitcherVodStreamRequest();
  streamRequest.vodConfigId = 'VOD_CONFIG_ID';
  streamRequest.region = 'LOCATION';
  streamRequest.projectNumber = 'PROJECT_NUMBER';
  streamRequest.oAuthToken = 'OAUTH_TOKEN';
  streamRequest.networkCode = 'NETWORK_CODE';

  streamManager.requestStream(streamRequest);
}

إعادة تحميل الصفحة بعد ذلك، يمكنك طلب بث الفيديو عند الطلب المخصّص وتشغيله.

(اختياري) إضافة خيارات جلسة البث

يمكنك تخصيص طلب البث عن طريق إضافة خيارات الجلسة لإلغاء الإعدادات التلقائية لواجهة برمجة التطبيقات Cloud Video Stitcher API باستخدام VideoStitcherVodStreamRequest.videoStitcherSessionOptions. إذا قدّمت خيارًا غير معروف، ستستجيب واجهة برمجة التطبيقات Video Stitcher API بخطأ HTTP 400. يمكنك الرجوع إلى دليل تحديد المشاكل وحلّها للحصول على المساعدة.

على سبيل المثال، يمكنك إلغاء خيارات البيان باستخدام مقتطف الرمز البرمجي التالي الذي يطلب بيانَي بث مع صيغ مرتبة من أقل معدل نقل بيانات إلى أعلى.

...

// The following session options are examples. Use session options
// that are compatible with your video stream.
streamRequest.videoStitcherSessionOptions = {
  "manifestOptions": {
    "includeRenditions": [
      {"bitrateBps": 3000, "codecs": "hvc1.1.4.L126.B0, mp4a.40.2"},
      {"bitrateBps": 2000, "codecs": "avc1.64001f, mp4a.40.2"},
    ],
    "bitrateOrder": "ascending"
  }
};

streamManager.requestStream(streamRequest);

تَنظيم

بعد أن استضفت بنجاح بثًا للفيديوهات عند الطلب باستخدام Google Cloud Video Stitcher API وطلبته باستخدام حزمة تطوير البرامج IMA DAI SDK لنظام HTML5، من المهم تنظيف أي موارد لعرض الإعلانات.

اتّبِع دليل تنظيف الفيديوهات عند الطلب لإزالة أيّ موارد ومواد عرض غير ضرورية.

أخيرًا، في نافذة المحطة الطرفية التي بدأت فيها خادم الويب Python 3، استخدِم الأمر ctrl+C لإنهاء الخادم المحلي.