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

اختيار النظام الأساسي: HTML5 Android iOS tvOS Cast Roku

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

اختَر حلّ "إدراج الإعلان الديناميكي" المفضّل لديك:

تشغيل أحداث البث المباشر المسجّلة باستخدام Google Cloud Video Stitcher API

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

يقدّم هذا الدليل تفاصيل إضافية عن المثال الأساسي من دليل البدء لتقنية IMA DAI.

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

لعرض نموذج دمج مكتمل أو اتّباعه، نزِّل مثال دمج الفيديو في السحابة الإلكترونية لبروتوكول HLS أو DASH.

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

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

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

الموقع الجغرافي
منطقة Google Cloud التي تم فيها إنشاء إعدادات الفيديو عند الطلب: LOCATION
رقم المشروع
رقم مشروع Google Cloud الذي يستخدم Video Stitcher API: PROJECT_NUMBER
رمز OAuth مميّز

رمز OAuth المميز قصير الأجل لحساب الخدمة مع دور مستخدم Video Stitcher: 

OAUTH_TOKEN

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

رمز الشبكة

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

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

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

يمكنك الاطّلاع على مزيد من المعلومات حول إنشاء معرّف إعدادات الفيديو عند الطلب في دليل إنشاء إعدادات الفيديو عند الطلب في Cloud stitching.

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

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

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

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

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

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

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

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

python3 -m http.server 8000

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

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

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

طلب بث فيديو عند الطلب

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

في النموذج الحالي، هناك دوال لطلب بث فيديو مسجّل أو بث مباشر. لجعلها تعمل مع 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. إذا قدّمت خيارًا غير معروف، ستعرض Cloud Video Stitcher API رسالة خطأ HTTP 400. يمكنك مراجعة دليل تحديد المشاكل وحلّها للحصول على المساعدة.

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

...

// The following session options are examples. Use session options
// that are compatible with your video stream.
streamRequest.videoStitcherSessionOptions = {
  "manifestOptions": {
    "bitrateOrder": "ascending"
  }
};

streamManager.requestStream(streamRequest);

تَنظيم

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

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

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