تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

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

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

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

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

أنشئ إعدادات لحدث بث مباشر باستخدام بث مباشر لمحتوى خاص بك أو بث مباشر اختباري. يستند هذا الدليل إلى بث مباشر وفق بروتوكول HTTP ‏(HLS).

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

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

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

رقم المشروع

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

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

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

OAUTH_TOKEN

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

رمز الشبكة

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

رقم تعريف الإعدادات المباشرة: رقم تعريف الإعدادات المباشرة الذي حدّدته عند إنشاء حدث البث المباشر: LIVE_CONFIG_ID
مفتاح مادة العرض المخصّصة: مفتاح مادة العرض المخصّصة في "مدير إعلانات Google" الذي تم إنشاؤه أثناء عملية إنشاء إعدادات لحدث بث مباشر باستخدام Video Stitcher API: CUSTOM_ASSET_KEY

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

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

‫type: سلسلة يجب ضبطها على 'ID3' لأحداث البث المباشر وفق بروتوكول HLS و'urn:google:dai:2018' لأحداث البث المباشر وفق بروتوكول DASH
data: بالنسبة إلى رسائل أحداث DASH، هذه هي سلسلة بيانات الرسالة.
timestamp: رقم يمثّل وقت بدء رسالة الحدث لملفات DASH البث

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

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

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

python3 -m http.server 8000

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

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

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

طلب بث مباشر

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

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

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

// StreamManager which will be used to request ad-enabled 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() {
  requestVideoStitcherStream();

  playButton.style.display = "none";
  playButton.removeEventListener('click', initiatePlayback);
  playButton.addEventListener('click', resumePlayback);
}
...

function requestVideoStitcherStream() {
  const streamRequest = new google.ima.dai.api.VideoStitcherLiveStreamRequest();
  streamRequest.liveStreamEventId = 'LIVE_CONFIG_ID';
  streamRequest.region = 'LOCATION';
  streamRequest.projectNumber = 'PROJECT_NUMBER';
  streamRequest.oAuthToken = 'OAUTH_TOKEN';
  streamRequest.networkCode = 'NETWORK_CODE';
  streamRequest.customAssetKey = 'CUSTOM_ASSET_KEY';

  streamManager.requestStream(streamRequest);
}

للاختبار على الجهاز، إذا كانت ملفات البث المباشر متوفّرة في ملف تخزين على Cloud Storage، عليك تفعيل سياسة مشاركة الموارد المتعددة المصادر (CORS) لمصدر http://localhost:8000.

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

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

يمكنك تخصيص طلب البث عن طريق إضافة خيارات الجلسة لإلغاء الإعدادات التلقائية لواجهة برمجة التطبيقات Cloud Video Stitcher API باستخدام VideoStitcherLiveStreamRequest.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 الإعلانات التي يتم استرجاعها من علامة الإعلان لكل فاصل إعلاني. يتم الإشارة إلى الفواصل الإعلانية في البيان باستخدام علامات الإعلانات. يُدرج برنامج ترميز البث المباشر علامات الإعلانات.

إذا كنت تستخدِم بثًا مباشرًا خاصًا بك، عليك إدراج علامة الإعلان. للحصول على مزيد من المعلومات عن علامات الإعلانات المتوافقة مع HLS وDASH، يُرجى الاطّلاع على مستندات علامات الإعلانات.
إذا أنشأت بثًا مباشرًا باستخدام Google Cloud Livestream API، أدرِج حدث قناة فاصل إعلاني.

يتم تشغيل الإعلان فور إدراج الفاصل الإعلاني.

تَنظيم

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

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

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