يوضّح هذا الدليل كيفية دمج حزمة تطوير البرامج (SDK) لتقنية IMA DAI في تطبيق مشغّل فيديو. إذا كنت تريد الاطّلاع على نموذج دمج مكتمل أو متابعته، يمكنك تنزيل المثال البسيط من GitHub.
نظرة عامة على IMA DAI
يتضمّن تنفيذ حزمة تطوير البرامج (SDK) لتقنية IMA DAI مكوّنَين رئيسيَّين كما هو موضّح في هذا الدليل:
-
StreamRequest: إماVODStreamRequestأوLiveStreamRequest: عنصر يحدّد طلب بث. يمكن أن تكون طلبات البث إما لفيديو عند الطلب أو لأحداث بث مباشر. تحدّد طلبات البث المباشر مفتاح مادة عرض، بينما تحدّد طلبات الفيديو عند الطلب معرّف "نظام إدارة المحتوى" ومعرّف الفيديو. يمكن أن يتضمّن كلا نوعَي الطلبات اختياريًا مفتاح واجهة برمجة التطبيقات اللازم للوصول إلى مصادر بيانات معيّنة، ورمز شبكة "إدارة إعلانات Google" لكي تعالج حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK) معرّفات الإعلانات على النحو المحدّد في إعدادات "إدارة إعلانات Google". -
StreamManager: عنصر يعالج أحداث بث "إدراج الإعلانات الديناميكية" والتفاعلات مع الخلفية الخاصة بهذه الميزة يتولّى مدير البث أيضًا معالجة طلبات تتبُّع الاتصال وإعادة توجيه أحداث البث والإعلانات إلى الناشر.
المتطلبات الأساسية
- ثلاثة ملفات فارغة
- dai.html
- dai.css
- dai.js
- تثبيت Python على جهاز الكمبيوتر أو خادم ويب لاستخدامه في الاختبار
بدء خادم تطوير
بما أنّ حزمة تطوير البرامج (SDK) لتقنية IMA DAI تحمّل التبعيات باستخدام البروتوكول نفسه الذي تستخدمه الصفحة التي يتم تحميلها منها، عليك استخدام خادم ويب لاختبار تطبيقك. وتتمثل إحدى الطرق السريعة لبدء خادم تطوير محلي في استخدام خادم Python المدمج.
باستخدام سطر الأوامر، من الدليل الذي يحتوي على ملف
index.html، شغِّل:python -m http.server 8000في متصفّح الويب، انتقِل إلى
http://localhost:8000/يمكنك أيضًا استخدام أي خادم ويب آخر، مثل خادم Apache HTTP.
إنشاء مشغّل فيديو
أولاً، عدِّل dai.html لإنشاء عنصر فيديو HTML5 وعنصر div لاستخدامه في النقرة. يستورد المثال التالي حزمة تطوير البرامج (SDK) لتقنية IMA DAI. لمزيد من التفاصيل، يُرجى الاطّلاع على استيراد حزمة تطوير البرامج (SDK) لتقنية "إدراج الإعلان الديناميكي" (DAI) في "إعلانات الوسائط التفاعلية" (IMA).
أضِف أيضًا العلامات اللازمة لتحميل ملفات dai.css وdai.js، بالإضافة إلى استيراد مشغّل فيديو hls.js. بعد ذلك،
عدِّل dai.css لتحديد حجم عناصر الصفحة وموضعها.
أخيرًا، في dai.js، حدِّد المتغيّرات للاحتفاظ بمعلومات طلب البث،
ودالة initPlayer() لتشغيلها عند تحميل الصفحة، واضبط
زر التشغيل لطلب بث عند النقر.
لاستئناف التشغيل أثناء الفواصل الإعلانية المتوقفة مؤقتًا، يجب إعداد متتبِّعات الأحداث لحدثَي pause وstart في عنصر الفيديو من أجل عرض عناصر التحكّم في المشغّل وإخفائها.
تحميل حزمة تطوير البرامج (SDK) لتقنية IMA DAI
بعد ذلك، أضِف إطار عمل IMA باستخدام علامة برمجية في dai.html، قبل علامة dai.js.
إعداد StreamManager
لطلب مجموعة من الإعلانات، أنشئ ima.dai.api.StreamManager، وهو المسؤول عن طلب وإدارة أحداث البث المباشر لإدراج الإعلانات الديناميكية. تتلقّى الدالة الإنشائية عنصر فيديو وعنصرًا في واجهة المستخدم للإعلان من أجل معالجة النقرات على الإعلانات.
تقديم طلب بث
تحديد الدوال لطلب أحداث البث يتضمّن هذا المثال دوال لكل من الفيديوهات عند الطلب وأحداث البث المباشر، والتي تنشئ نُسخًا من الفئة VODStreamRequest والفئة LiveStreamRequest. بعد الحصول على مثيل streamRequest، استدعِ طريقة streamManager.requestStream() باستخدام مثيل طلب البث.
تتطلّب كلتا طريقتَي طلب البث مفتاح واجهة برمجة تطبيقات اختياريًا. إذا كنت تستخدم بثًا محميًا، عليك إنشاء مفتاح مصادقة لإدراج الإعلانات الديناميكية. لمزيد من التفاصيل، يُرجى الاطّلاع على المصادقة على طلبات بث الفيديو عبر ميزة "إدراج إعلان ديناميكي".
لا تتم حماية أي من البثَّين في هذا المثال باستخدام مفتاح مصادقة "إدراج الإعلان ديناميكيًا"، لذا لا يتم استخدام apiKey.
تحليل البيانات الوصفية للبث
يجب أيضًا إضافة معالج للاستماع إلى أحداث البيانات الوصفية المحدّدة بوقت وإعادة توجيه
الأحداث إلى فئة StreamManager لكي تصدر IMA أحداث الإعلانات أثناء الفواصل
الإعلانية:
يستخدم هذا الدليل مشغّل hls.js لتشغيل البث، ولكن تنفيذ البيانات الوصفية يعتمد على نوع المشغّل الذي تستخدمه.
التعامل مع أحداث البث
تنفيذ متتبِّعات الأحداث لأحداث الفيديو الرئيسية يتعامل هذا المثال مع الأحداث LOADED وERROR وAD_BREAK_STARTED وAD_BREAK_ENDED من خلال استدعاء دالة onStreamEvent(). تتعامل هذه الدالة مع تحميل البث وأخطاء البث وإيقاف عناصر التحكّم في المشغّل أثناء تشغيل الإعلانات، وهو ما تتطلّبه حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK).
عند تحميل البث، يتم تحميل مشغّل الفيديو وتشغيل عنوان URL المقدَّم
باستخدام دالة loadUrl().
هذا كل شيء! يمكنك الآن طلب الإعلانات وعرضها باستخدام حزمة تطوير البرامج (SDK) لـ IMA DAI. للاطّلاع على المزيد من ميزات حزمة تطوير البرامج (SDK) المتقدّمة، يُرجى مراجعة الأدلة الأخرى أو النماذج على GitHub.