يتناول هذا الدليل كيفية دمج حزمة تطوير البرامج (SDK) لتقنية IMA DAI في تطبيق مشغّل فيديو. إذا أردت الاطّلاع على نموذج عملية دمج مكتملة أو اتّباع خطواتها، يمكنك تنزيل BasicExample من GitHub.
نظرة عامة على IMA DAI
يتضمن تنفيذ ميزة IMA DAI أربعة مكوّنات رئيسية لحزمة تطوير البرامج (SDK)، كما يوضّح هذا الدليل:
-
IMAAdDisplayContainer: هو عنصر حاوية يقع فوق عنصر تشغيل الفيديو ويضم عناصر واجهة المستخدم الخاصة بالإعلان. -
IMAAdsLoader: هو عنصر يطلب أحداثًا ويتعامل مع الأحداث التي يتم تشغيلها بواسطة عناصر استجابة طلب الحدث. يجب إنشاء مثيل واحد فقط من أداة تحميل الإعلانات، ويمكن إعادة استخدامه طوال مدة تشغيل التطبيق. -
IMAStreamRequest: إماIMAVODStreamRequestأوIMALiveStreamRequest. عنصر يحدّد طلب بث يمكن أن تكون طلبات البث إما لفيديو عند الطلب أو لأحداث بث مباشر. تحدّد طلبات البث المباشر مفتاح مادة عرض، بينما تحدّد طلبات الفيديو عند الطلب معرّف "نظام إدارة المحتوى" ومعرّف الفيديو. يمكن أن يتضمّن كلا نوعَي الطلبات اختياريًا مفتاح واجهة برمجة التطبيقات اللازم للوصول إلى مصادر بيانات معيّنة، ورمز شبكة "إدارة إعلانات Google" لكي تعالج حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK) معرّفات الإعلانات على النحو المحدّد في إعدادات "إدارة إعلانات Google". -
IMAStreamManager: عنصر يعالج أحداث بث "إدراج الإعلانات الديناميكية" والتفاعلات مع الخلفية الخاصة بهذه الميزة يتولّى مدير البث أيضًا معالجة طلبات تتبُّع الاتصال وإعادة توجيه أحداث البث والإعلانات إلى الناشر.
المتطلبات الأساسية
قبل البدء، تحتاج إلى ما يلي:
- الإصدار 13 من Xcode أو إصدار أحدث
- طريقة تثبيت حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK):
- Swift Package Manager (مُفضَّل)
- نسخة قابلة للتنزيل من حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK) لنظام التشغيل iOS
ستحتاج أيضًا إلى المَعلمات لطلب البث من حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK). للاطّلاع على أمثلة على مَعلمات الطلب، يُرجى مراجعة نماذج أحداث البث.
| مَعلمات البث المباشر | |
|---|---|
| مفتاح مادة العرض |
مفتاح مادة العرض
الذي يحدّد البث المباشر في "مدير إعلانات Google" مثال: c-rArva4ShKVIAkNfy6HUQ
|
| مَعلمات بث الفيديو عند الطلب | |
| معرّف مصدر المحتوى |
معرّف مصدر المحتوى من "إدارة إعلانات Google". مثال: 2548831
|
| معرّف الفيديو |
معرّف الفيديو من "إدارة إعلانات Google" مثال: tears-of-steel
|
| المَعلمات الشائعة (للفيديوهات عند الطلب وأحداث البث المباشر) | |
| رمز الشبكة |
رمز شبكة "إدارة إعلانات Google" مثال: 21775744923
|
إنشاء مشروع Xcode جديد
في Xcode، أنشئ مشروعًا جديدًا لنظام التشغيل iOS باستخدام Objective-C باسم "BasicExample".
إضافة حزمة IMA DAI SDK إلى مشروع Xcode
لتثبيت حزمة تطوير البرامج للإعلانات التفاعلية، اختَر الطريقة المفضّلة لديك.
الإجراء المقترَح: تثبيت حزمة تطوير البرامج (SDK) باستخدام Swift Package Manager
تتوافق حزمة تطوير البرامج لإعلانات الوسائط التفاعلية مع Swift Package Manager بدءًا من الإصدار 3.18.4. اتّبِع هذه الخطوات لاستيراد حزمة Swift.
في Xcode، ثبِّت حزمة Swift لحزمة تطوير البرامج (SDK) لتقنية IMA DAI: انتقِل إلى File > Add Packages.
في الطلب الذي يظهر، ابحث عن مستودع GitHub لحزمة Swift Package الخاصة بحزمة تطوير البرامج (SDK) لتقنية IMA DAI:
https://github.com/googleads/swift-package-manager-google-interactive-media-ads-iosاختَر إصدار حزمة Swift Package من حزمة تطوير البرامج (SDK) لتقنية IMA DAI الذي تريد استخدامه. بالنسبة إلى المشاريع الجديدة، استخدِم Up to Next Major Version.
بعد الانتهاء، يحلّ Xcode التبعيات المرتبطة بحِزمك وينزّلها في الخلفية. لمزيد من التفاصيل حول كيفية إضافة تبعيات الحِزم، يُرجى الاطّلاع على مقالة Apple.
تنزيل حزمة SDK وتثبيتها يدويًا
إذا كنت لا تريد استخدام Swift Package Manager، يمكنك تنزيل حزمة IMA SDK وإضافتها يدويًا إلى مشروعك.
إنشاء مشغّل فيديو
نفِّذ مشغّل فيديو في وحدة التحكّم في العرض الرئيسية، وأدرِج مشغّل AV في عرض واجهة المستخدم. تستخدم حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK) طريقة عرض واجهة المستخدم لعرض عناصر في واجهة المستخدم الخاصة بالإعلانات.
Objective-C
Swift
إعداد أداة تحميل الإعلانات
استورِد حزمة IMA SDK إلى وحدة التحكّم في العرض واعتمد بروتوكولَي
IMAAdsLoaderDelegate
وIMAStreamManagerDelegate
لمعالجة أحداث أداة تحميل الإعلانات ومدير البث.
أضِف هذه السمات الخاصة لتخزين مكوّنات حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK) الرئيسية:
IMAAdsLoader- يدير طلبات البث طوال فترة استخدام تطبيقك.
IMAAdDisplayContainer- تتولّى هذه الفئة إدراج عناصر واجهة مستخدم الإعلانات وإدارتها.
IMAAVPlayerVideoDisplay- يتيح التواصل بين حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK) ومشغّل الوسائط ويتعامل مع البيانات الوصفية المحدّدة بوقت.IMAStreamManager: يدير تشغيل البث ويشغّل الأحداث ذات الصلة بالإعلانات.
ابدأ أداة تحميل الإعلانات وحاوية عرض الإعلانات وعرض الفيديو بعد تحميل العرض.
Objective-C
Swift
تقديم طلب بث
عندما يضغط المستخدم على زر التشغيل، أرسِل طلب بث جديد.
استخدِم الفئة IMALiveStreamRequest لأحداث البث المباشر. بالنسبة إلى أحداث البث المباشر للفيديوهات عند الطلب، استخدِم الفئة
IMAVODStreamRequest.
يتطلّب طلب البث مَعلمات البث، بالإضافة إلى مرجع إلى حاوية عرض الإعلانات وعرض الفيديو.
Objective-C
Swift
الاستماع إلى أحداث تحميل البث
تستدعي الفئة IMAAdsLoader الطرق IMAAdsLoaderDelegate عند نجاح عملية الإعداد أو تعذُّر طلب البث.
في طريقة التفويض adsLoadedWithData، اضبط IMAStreamManagerDelegate.
ابدأ تشغيل مدير البث. عند الإعداد، يبدأ مدير البث
عملية التشغيل.
في طريقة التفويض
failedWithErrorData
، سجِّل الخطأ. يمكنك تشغيل البث الاحتياطي إذا أردت. اطّلِع على أفضل الممارسات المتعلّقة بإدراج الإعلانات الديناميكي.
Objective-C
Swift
الاستماع إلى أحداث الإعلانات
يستدعي IMAStreamManager
طُرق
IMAStreamManagerDelegate
لتمرير أحداث البث والأخطاء إلى تطبيقك.
في هذا المثال، سجِّل أحداث الإعلانات الأساسية في وحدة التحكّم:
Objective-C
Swift
شغِّل تطبيقك. إذا نجحت العملية، اطلب بثّ "إدراج الإعلان الديناميكي" من Google وشغِّله باستخدام حزمة IMA SDK. لمزيد من المعلومات حول ميزات حزمة تطوير البرامج (SDK) الأكثر تقدّمًا، يُرجى الاطّلاع على الأدلة الأخرى المدرَجة في الشريط الجانبي الأيمن أو النماذج على GitHub.