بدء استخدام حزمة تطوير البرامج للإعلانات التفاعلية (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 Video Stitcher API وتشغيله، وكيفية إدراج فاصل إعلاني أثناء التشغيل.

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

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

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

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

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

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

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

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

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

OAUTH_TOKEN

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

رمز الشبكة

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

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

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

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

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

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

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

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

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

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

python3 -m http.server 8000

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

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

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

طلب بث مباشر

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

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

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

تَنظيم

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

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

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