يوضّح هذا الدليل كيفية دمج حزمة تطوير البرامج (SDK) لتقنية IMA DAI في تطبيق مشغّل فيديو بسيط. إذا أردت الاطّلاع على نموذج دمج مكتمل أو متابعته، يمكنك تنزيل BasicExample من GitHub.
نظرة عامة على IMA DAI
يتضمن تنفيذ IMA DAI أربعة مكوّنات رئيسية لحزمة تطوير البرامج (SDK) كما هو موضّح في هذا الدليل:
StreamDisplayContainer: هو عنصر حاوية يقع أعلى عنصر تشغيل الفيديو ويضم عناصر في واجهة المستخدم للإعلان.-
AdsLoader: هو عنصر يطلب أحداثًا ويتعامل مع الأحداث التي يتم تشغيلها بواسطة عناصر الاستجابة لطلب البث. يجب إنشاء مثيل واحد فقط من أداة تحميل الإعلانات، ويمكن إعادة استخدامه طوال مدة تشغيل التطبيق. -
StreamRequest: تمثّل هذه السمة عنصرًا يحدّد طلب مصدر بيانات. يمكن أن تكون طلبات البث إما لفيديو عند الطلب أو لأحداث بث مباشر. تحدّد طلبات البث المباشر مفتاح مادة عرض، بينما تحدّد طلبات الفيديو عند الطلب معرّف "نظام إدارة المحتوى" ومعرّف الفيديو. يمكن أن يتضمّن كلا نوعَي الطلبات اختياريًا مفتاح واجهة برمجة التطبيقات اللازم للوصول إلى مصادر بيانات معيّنة، ورمز شبكة "إدارة إعلانات Google" لكي تعالج حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK) معرّفات الإعلانات على النحو المحدّد في إعدادات "إدارة إعلانات Google". -
StreamManager: عنصر يعالج أحداث بث "إدراج الإعلانات الديناميكية" والتفاعلات مع الخلفية الخاصة بهذه الميزة يتولّى مدير البث أيضًا معالجة طلبات تتبُّع الاتصال وإعادة توجيه أحداث البث والإعلانات إلى الناشر.
المتطلبات الأساسية
- استوديو Android
- نموذج لتطبيق مشغّل فيديو لدمج حزمة تطوير البرامج (SDK)
تنزيل تطبيق مشغّل الفيديو النموذجي وتشغيله
يوفّر نموذج التطبيق مشغّل فيديو يعمل على تشغيل فيديو HLS. يمكنك استخدام هذا التطبيق كنقطة بداية لدمج إمكانات IMA DAI في حزمة تطوير البرامج (SDK) لإدراج الإعلان الديناميكي في إعلانات الوسائط التفاعلية.
نزِّل تطبيق مشغّل الفيديو النموذجي واستخرِجه.
افتح "استوديو Android" واختَر فتح مشروع حالي في "استوديو Android"، أو إذا كان "استوديو Android" قيد التشغيل، اختَر ملف > جديد > استيراد مشروع. بعد ذلك، اختَر
SampleVideoPlayer/build.gradle.شغِّل مزامنة Gradle من خلال اختيار أدوات > Android > مزامنة المشروع مع ملفات Gradle.
تأكَّد من أنّ تطبيق المشغّل يتم تجميعه وتشغيله على جهاز Android فعلي أو جهاز افتراضي متوافق مع Android باستخدام تشغيل > تشغيل "التطبيق". من الطبيعي أن يستغرق تحميل الفيديو بضع ثوانٍ قبل تشغيله.
فحص مشغّل الفيديو النموذجي
لا يحتوي مشغّل الفيديو النموذجي على أي رمز دمج لحزمة تطوير البرامج (SDK) الخاصة بتقنية IMA DAI حتى الآن. يتكوّن نموذج التطبيق من جزأين رئيسيين:
samplevideoplayer/SampleVideoPlayer.java: مشغّل HLS مستند إلى ExoPlayer يُستخدَم كأساس لدمج IMA DAI.
videoplayerapp/MyActivity.java: ينشئ هذا النشاط مشغّل الفيديو ويمرّر إليهContextوmedia3.ui.PlayerView.
إضافة حزمة تطوير البرامج (SDK) لتقنية IMA DAI إلى تطبيق المشغّل
يجب أيضًا تضمين مرجع إلى حزمة تطوير البرامج (SDK) لتقنية IMA DAI. في "استوديو Android"، أضِف ما يلي إلى ملف build.gradle على مستوى التطبيق، والذي يقع في app/build.gradle. تتطلّب حزمة IMA SDK تفعيل ميزة إزالة التجميل اللغوي للمكتبة، وهو ما يجب فعله من خلال ضبط coreLibraryDesugaringEnabled true وإضافة 'com.android.tools:desugar_jdk_libs' كعنصر تابع في ملف build.gradle. لمعرفة التفاصيل، يُرجى الاطّلاع على واجهات برمجة التطبيقات Java 11+ المتاحة من خلال إزالة التجميل اللغوي باستخدام مواصفات nio.
دمج حزمة تطوير البرامج (SDK) لتقنية IMA DAI
أنشئ فئة جديدة باسم
SampleAdsWrapperفي حزمةvideoplayerapp(فيapp/java/com.google.ads.interactivemedia.v3.samples/videoplayerapp/) لتضمينSampleVideoPlayerالحالي وإضافة منطق لتنفيذ IMA DAI. لإجراء ذلك، عليك أولاً إنشاءAdsLoaderيُستخدَم لطلب بث "إدراج الإعلان الديناميكي".يتضمّن هذا المقتطف عيّنات من مَعلمات البث المباشر والفيديو عند الطلب (VOD) بتنسيقَي HLS وDASH. لتحديد البث الذي يتم تشغيله، عليك تعديل المتغيّر
CONTENT_TYPE.أنشئ إجراءً مساعدًا
createSampleVideoPlayerCallback()لمعالجة إنشاء مثيل واجهةSampleVideoPlayerCallbackيوسّعVideoStreamPlayer.VideoStreamPlayerCallback.للعمل مع ميزة "إدراج الإعلان الديناميكي"، يجب أن يمرّر المشغّل أحداث ID3 إلى حزمة تطوير البرامج (SDK) الخاصة بميزة IMA DAI. تؤدي الطريقة
callback.onUserTextReceived()هذه المهمة، كما هو موضّح في الرمز النموذجي التالي.أضِف طريقة
buildStreamRequest()لإنشاءSteamRequest. تتيح هذه الطريقة التبديل بين أحداث البث المختلفة بناءً على كيفية ضبط المتغيّرCONTENT_TYPE. البث التلقائي المستخدَم في هذا الدليل هو بث HLS لنموذج فيديو عند الطلب من IMA.تحتاج أيضًا إلى
VideoStreamPlayerلتشغيل البث، لذا أضِف طريقةcreateVideoStreamPlayer()، والتي تنشئ فئة مجهولة تنفّذVideoStreamPlayer.نفِّذ المستمعين المطلوبين وأضِف ميزة معالجة الأخطاء.
يُرجى ملاحظة تنفيذ
AdErrorListener، لأنّه يستدعي عنوان URL احتياطيًا في حال تعذّر تشغيل الإعلانات. بما أنّ المحتوى والإعلانات يتم عرضها في بث واحد، يجب أن تكون مستعدًا لطلب بث احتياطي في حال حدوث خطأ في بث "إدراج الإعلان ديناميكيًا".أضِف رمزًا للتسجيل.
عدِّل
MyActivityفيvideoplayerappلإنشاء مثيل واستدعاءSampleAdsWrapper. يمكنك أيضًا استدعاءImaSdkFactory.initialize()هنا باستخدام طريقة مساعدة لإنشاء مثيلImaSdkSettings.أضِف طريقة المساعدة
getImaSdkSettings()لإنشاء مثيلImaSdkSettings.عدِّل ملف تصميم النشاط
activity_my.xmlلإضافة عناصر في واجهة المستخدم لتسجيل الدخول.
تهانينا! أنت الآن تطلب إعلانات الفيديو وتعرضها في تطبيق Android. لضبط عملية التنفيذ، يُرجى الاطّلاع على الإشارات المرجعية وSnapback ومستندات واجهة برمجة التطبيقات.
تحديد المشاكل وحلّها
إذا كنت تواجه مشاكل في تشغيل إعلان فيديو، جرِّب تنزيل BasicExample المكتمل. إذا كان يعمل بشكل صحيح في BasicExample، من المحتمل أن تكون هناك مشكلة في رمز دمج IMA في تطبيقك.
إذا استمرّت المشاكل، يُرجى الانتقال إلى منتدى حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK).