يتناول هذا الدليل كيفية دمج حزمة تطوير البرامج (SDK) لتقنية "إدراج الإعلان الديناميكي" (DAI) في "إعلانات الوسائط التفاعلية" (IMA) في تطبيق مشغّل فيديو. إذا أردت الاطّلاع على نموذج دمج مكتمل أو متابعته، يمكنك تنزيل PodServingExample من GitHub.
نظرة عامة على IMA DAI
يتضمن تنفيذ ميزة "إدراج الإعلان الديناميكي" في "حزمة تطوير البرامج لإعلانات الوسائط التفاعلية" أربعة مكوّنات رئيسية في حزمة تطوير البرامج (SDK)، كما يوضّح هذا الدليل:
-
IMAAdDisplayContainer: هو عنصر حاوية يقع فوق عنصر تشغيل الفيديو ويضم عناصر واجهة المستخدم الخاصة بالإعلان. -
IMAAdsLoader: هو عنصر يطلب أحداثًا ويتعامل مع الأحداث التي يتم تشغيلها بواسطة عناصر استجابة طلب البث. يجب إنشاء مثيل واحد فقط من أداة تحميل الإعلانات، والذي يمكن إعادة استخدامه طوال مدة تشغيل التطبيق. -
IMAStreamRequest: إماIMAPodVODStreamRequestأوIMAPodStreamRequest. -
IMAStreamManager: هو عنصر يعالج أحداث البث والتفاعلات الخاصة بميزة "إدراج إعلان ديناميكي" مع الخلفية الخاصة بهذه الميزة. يتولّى مدير البث أيضًا تتبُّع إشعارات الاتصال وإعادة توجيه أحداث البث والإعلانات إلى الناشر.
بالإضافة إلى ذلك، لتشغيل أحداث البث المباشر التي تعرض مجموعات إعلانية متتالية، عليك تنفيذ معالج VTP مخصّص. يرسل معالج VTP المخصّص هذا معرّف البث إلى شريكك الفني في الفيديو (VTP) مع أي معلومات أخرى يحتاجها لعرض بيان بث يحتوي على كل من المحتوى والإعلانات المدمجة. يوفّر مزوّد تكنولوجيا الفيديو تعليمات حول كيفية تنفيذ معالج مزوّد تكنولوجيا الفيديو المخصّص.
المتطلبات الأساسية
قبل البدء، تحتاج إلى ما يلي:
- الإصدار 13 من Xcode أو إصدار أحدث
- طريقة تثبيت حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK):
- Swift Package Manager (الخيار المفضّل)
- نسخة قابلة للتنزيل من حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK) لنظام التشغيل iOS
ستحتاج أيضًا إلى المَعلمات لطلب البث من حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK).
| مَعلمات البث المباشر | |
|---|---|
| رمز الشبكة |
رمز الشبكة لحسابك على "إدارة إعلانات Google 360" |
| مفتاح مادة العرض المخصّص |
مفتاح مادة العرض المخصّصة الذي يحدّد حدث "عرض الإعلانات في مجموعات" في "مدير الإعلانات 360". يتم إنشاء هذا الملف من خلال معالج البيان أو شريك عرض مجموعات الإعلانات المتتالية التابع لجهة خارجية. |
| مَعلمات بث الفيديو عند الطلب | |
| رمز الشبكة |
رمز الشبكة لحسابك على "إدارة إعلانات Google 360" |
إنشاء مشروع Xcode جديد
في Xcode، أنشئ مشروع iOS جديدًا باستخدام Objective-C باسم "PodServingExample".
إضافة حزمة تطوير البرامج (SDK) لتقنية IMA DAI إلى مشروع Xcode
لتثبيت حزمة تطوير البرامج للإعلانات التفاعلية، اختَر الطريقة المفضّلة لديك.
الإجراء المقترَح: تثبيت حزمة تطوير البرامج (SDK) باستخدام Swift Package Manager
تتوافق حزمة تطوير البرامج لإعلانات الوسائط التفاعلية مع Swift Package Manager بدءًا من الإصدار 3.18.4. اتّبِع هذه الخطوات لاستيراد حزمة Swift.
في Xcode، ثبِّت حزمة Swift Package الخاصة بحزمة تطوير البرامج (SDK) لتقنية IMA DAI: انتقِل إلى File > Add Packages.
في الطلب الذي يظهر، ابحث عن مستودع GitHub لحزمة Swift Package الخاصة بـ IMA DAI SDK:
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
تقديم طلب بث
عندما يضغط المستخدم على زر التشغيل، أرسِل طلب بث جديد.
استخدِم الفئة IMAPodStreamRequest لأحداث البث المباشر. بالنسبة إلى أحداث البث المباشر للفيديو عند الطلب، استخدِم الفئة
IMAPodVODStreamRequest.
يتطلّب طلب البث مَعلمات البث، بالإضافة إلى مرجع إلى حاوية عرض الإعلانات وعرض الفيديو.
Objective-C
Swift
الاستماع إلى أحداث تحميل البث
تستدعي الفئة IMAAdsLoader الطرق IMAAdsLoaderDelegate عند نجاح عملية الإعداد أو تعذُّر طلب البث.
في طريقة التفويض adsLoadedWithData، اضبط IMAStreamManagerDelegate.
مرِّر رقم تعريف مصدر البيانات إلى معالج VTP المخصّص، واسترجع عنوان URL لبيان مصدر البيانات. بالنسبة إلى أحداث البث المباشر، حمِّل عنوان URL الخاص بملف البيان في شاشة عرض الفيديو،
وابدأ التشغيل. بالنسبة إلى أحداث البث المباشر للفيديوهات عند الطلب، مرِّر عنوان URL الخاص بملف البيان إلى طريقة loadThirdPartyStream في مدير أحداث البث المباشر. تطلب هذه الطريقة بيانات أحداث الإعلانات من "إدارة إعلانات Google 360"، ثم تحمّل عنوان URL للبيان وتبدأ التشغيل.
في طريقة التفويض
failedWithErrorData
، سجِّل الخطأ. يمكنك تشغيل البث الاحتياطي إذا أردت. يمكنك الاطّلاع على أفضل الممارسات المتعلّقة بإدراج الإعلانات الديناميكية.
Objective-C
Swift
تنفيذ معالج VTP المخصّص
يرسل معالج VTP المخصّص معرّف البث الخاص بالمشاهد إلى شريكك الفني في مجال الفيديو (VTP) مع أي معلومات أخرى يطلبها شريكك الفني في مجال الفيديو لعرض بيان بث يحتوي على كل من المحتوى والإعلانات المدمجة. يوفّر موفّر تكنولوجيا الفيديو (VTP) تعليمات محدّدة حول كيفية تنفيذ معالج VTP المخصّص.
على سبيل المثال، قد يتضمّن نموذج VTP عنوان URL لنموذج بيان يحتوي على الماكرو [[STREAMID]]. في هذا المثال، يُدرج المعالج معرّف البث بدلاً من
وحدة الماكرو ويعرض عنوان URL لملف البيان الناتج.
Objective-C
Swift
الاستماع إلى أحداث الإعلانات
يستدعي IMAStreamManager
طُرق
IMAStreamManagerDelegate
لتمرير أحداث البث والأخطاء إلى تطبيقك.
في هذا المثال، سجِّل أحداث الإعلانات الأساسية في وحدة التحكّم:
Objective-C
Swift
حذف مواد عرض IMA DAI
لإيقاف تشغيل البث وإيقاف تتبُّع جميع الإعلانات وإصدار جميع مواد عرض البث المحمَّلة، يمكنك استدعاء IMAStreamManager.destroy().
شغِّل تطبيقك. إذا نجحت العملية، اطلب بثّ "إدراج الإعلان الديناميكي" من Google وشغِّله باستخدام حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK). لمزيد من المعلومات حول ميزات حزمة تطوير البرامج (SDK) الأكثر تقدّمًا، يُرجى الاطّلاع على الأدلة الأخرى المدرَجة في الشريط الجانبي الأيمن أو النماذج على GitHub.