إعداد حزمة تطوير البرامج لإعلانات الوسائط التفاعلية لعرض الإعلانات أثناء التشغيل

اختيار النظام الأساسي: HTML5 Android iOS tvOS Cast Roku

تسهّل حِزم تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية دمج إعلانات الوسائط المتعددة في مواقعك الإلكترونية وتطبيقاتك. يمكن لحِزم تطوير البرامج لإعلانات الوسائط التفاعلية طلب الإعلانات من أي خادم إعلانات متوافق مع VAST وإدارة تشغيل الإعلانات في تطبيقاتك. باستخدام حِزم تطوير البرامج (SDK) الخاصة بميزة "إدراج الإعلان الديناميكي" في "إعلانات الوسائط التفاعلية" (IMA DAI)، تقدّم التطبيقات طلب بث لإعلان وفيديو محتوى، سواء كان فيديو عند الطلب أو محتوى مباشرًا. بعد ذلك، تعرض حزمة SDK بث فيديو مدمجًا، ما يغنيك عن إدارة التبديل بين الفيديو الإعلاني وفيديو المحتوى داخل تطبيقك.

اختيار حلّ "الإعلانات الديناميكية داخل الفيديو" الذي يهمّك

Pod Serving DAI

تسهّل حِزم تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية دمج إعلانات الوسائط المتعددة في مواقعك الإلكترونية وتطبيقاتك. يمكن لحِزم تطوير البرامج لإعلانات الوسائط التفاعلية طلب الإعلانات من أي خادم إعلانات متوافق مع VAST وإدارة تشغيل الإعلانات في تطبيقاتك. باستخدام حِزم تطوير البرامج (SDK) الخاصة بميزة "إدراج الإعلان الديناميكي" في "إعلانات الوسائط التفاعلية" (IMA DAI)، تقدّم التطبيقات طلب بث لإعلان وفيديو محتوى، سواء كان فيديو عند الطلب أو محتوى مباشرًا. بعد ذلك، تعرض حزمة SDK بث فيديو مدمجًا، ما يغنيك عن إدارة التبديل بين الفيديو الإعلاني وفيديو المحتوى داخل تطبيقك.

يوضّح هذا الدليل كيفية تشغيل بث "عرض إعلانات ضمن مجموعة" باستخدام حزمة IMA DAI SDK مع مشغّل فيديو لتشغيل بث مباشر وفيديو عند الطلب. لعرض أو اتّباع مثال على عملية دمج مكتملة، نزِّل مثال عرض الحزمة.

نظرة عامة على عرض مجموعة الإعلانات المتسلسلة في IMA DAI

  • ‫StreamRequest: عنصر يحدّد طلب بث إلى خوادم Google الإعلانية. يجب أن يتم إنشاؤها باستخدام ImaSdkFactory.createPodStreamRequest() أو ImaSdkFactory.createPodVodStreamRequest() لتفعيل ميزة "عرض الإعلانات ضمن حزمة". تتطلّب هذه الطرق رمز شبكة، ويتطلّب createPodStreamRequest أيضًا مفتاح أصول مخصّص ومفتاح واجهة برمجة تطبيقات اختياريًا. يتضمّن كلاهما مَعلمات اختيارية أخرى.

  • StreamManager: عنصر يعالج التواصل بين بث الفيديو و"حزمة تطوير البرامج (SDK) للإعلانات الديناميكية أثناء عرض الفيديو" من "إعلانات الوسائط التفاعلية"، مثل إرسال طلبات ping للتتبّع وإعادة توجيه أحداث البث إلى الناشر.

المتطلبات الأساسية

إعداد متغيّرات عرض الإعلانات المتسلسلة

يتم إجراء جميع التغييرات اللازمة لعرض الإعلانات ضمن حزمة SampleAdsWrapper.java. تتمثّل الخطوة الأولى في تعديل المتغيّرات الثابتة.

في ما يلي الثوابت الخاصة بطلبات بث مجموعات الإعلانات المتسلسلة التي يجب إضافتها:

  • STREAM_URL: يُستخدم فقط في البث المباشر - عنوان URL لبث الفيديو الذي يقدّمه مشغّل ملف البيان أو شريك خارجي يستخدم ميزة "عرض الإعلانات ضمن حزمة". يجب أن يطلب منك إدخال معرّف البث الذي توفّره حزمة تطوير البرامج لإعلانات الوسائط التفاعلية (IMA) الخاصة بميزة "الإعلانات الديناميكية أثناء عرض الفيديو" (DAI)، وذلك قبل إرسال طلب. في هذه الحالة، يتضمّن عنوان URL للبث عنصرًا نائبًا، "[[STREAMID]]"، يتم استبداله بمعرّف البث قبل تقديم الطلب.

  • NETWORK_CODE: معرِّف الشبكة لحسابك على "إدارة إعلانات Google‏ 360".

  • CUSTOM_ASSET_KEY: يُستخدَم فقط في الأحداث المباشرة: مفتاح العنصر المخصّص الذي يحدّد حدث "عرض الإعلانات المتسلسلة" في "إدارة إعلانات Google‏ 360". يمكن إنشاء هذا الملف من خلال أداة تعديل ملف البيان أو شريك خارجي يقدّم خدمة Pod Serving.

  • ‫API_KEY: يُستخدم فقط في أحداث البث المباشر: مفتاح اختياري لواجهة برمجة التطبيقات يمكن أن يكون مطلوبًا لاسترداد معرّف بث من حزمة تطوير البرامج (SDK) الخاصة بـ IMA DAI.

تم تصميم Android DAI BasicExample لتشغيل مجموعة متنوعة من أنواع البث المختلفة، ولكن بالنسبة إلى ميزة "عرض الإعلانات ضمن مجموعة"، تم إعدادها لتشغيل بث واحد فقط. غيِّر قسم المتغيرات في المثال ليتطابق مع ما يلي:

/** This class implements IMA to add pod ad-serving support to SampleVideoPlayer */
@SuppressLint("UnsafeOptInUsageError")
/* @SuppressLint is needed for new media3 APIs. */
public class SampleAdsWrapper
    implements AdEvent.AdEventListener, AdErrorEvent.AdErrorListener, AdsLoader.AdsLoadedListener {

  // Set up the pod serving variables.
  private static final String NETWORK_CODE = "";
  private static final String CUSTOM_ASSET_KEY = "";
  private static final String API_KEY = "";
  private static final String STREAM_URL = "";
  private static final StreamFormat STREAM_FORMAT = StreamFormat.HLS;

إنشاء طلب بث مباشر أو بث مباشر لفيديو عند الطلب لتفعيل ميزة "عرض الإعلانات ضمن مجموعة"

عرض الإعلانات ضمن البث المباشر

أزلنا الطريقة buildStreamRequest() التي كانت تُستخدَم للتبديل بين إنشاء أنواع مختلفة من الفيديوهات المباشرة. بعد ذلك، عدِّل requestAndPlayAds() لاستدعاء ImaSdkFactory.createPodStreamRequest() من أجل إنشاء طلب إعلان Live Pod Serving.

// Live pod stream request.
request = sdkFactory.createPodStreamRequest(NETWORK_CODE, CUSTOM_ASSET_KEY, API_KEY);

عرض الإعلانات ضمن مجموعة في بث الفيديو عند الطلب

أزلنا الطريقة buildStreamRequest() التي كانت تُستخدَم للتبديل بين إنشاء أنواع مختلفة من الفيديوهات المباشرة. بعد ذلك، عدِّل requestAndPlayAds() لاستدعاء ImaSdkFactory.createPodVodStreamRequest() لإنشاء طلب إعلان ضمن حزمة VOD.

// VOD pod stream request.
request = sdkFactory.createPodVodStreamRequest(NETWORK_CODE);

بعد إنشاء مثيل لطلب البث، اطلب البث باستخدام AdsLoader.requestStream():

request.setFormat(STREAM_FORMAT);
adsLoader.requestStream(request);

تعديل عنوان URL للبث وضبطه

عرض الإعلانات ضمن البث المباشر

استدعِ طريقة StreamManager.getStreamId() للحصول على معرّف مصدر البيانات. يجب إدراج هذا الرمز في STEAM_URL بدلاً من "[[STREAMID]]". بعد إجراء هذا التغيير، اضبط عنوان URL للبث الجديد باستخدام طريقة videoPlayer.setStreamUrl() واستخدِم طريقة videoPlayer.play() لبدء تشغيل البث.

// Play the live pod stream.
streamID = streamManager.getStreamId();
String liveStreamUrl = STREAM_URL.replace("[[STREAMID]]", streamID);
// Call videoPlayer.play() here, because IMA doesn't call the VideoStreamPlayer.loadUrl()
// function for livestreams.
videoPlayer.setStreamUrl(liveStreamUrl);
videoPlayer.play();

عرض الإعلانات ضمن مجموعة في بث الفيديو عند الطلب

  1. استدعِ طريقة StreamManager.getStreamId() للحصول على معرّف مصدر البيانات.
  2. اطلب عنوان URL للبث من شريكك في تكنولوجيا الفيديو (VTP).
  3. بعد تلقّي عنوان URL من شريك تكنولوجيا الفيديو، استخدِم طريقة StreamManager.loadThirdPartyStream() مع عنوان URL لتحميل البث، بالإضافة إلى أي ترجمات يعرضها شريك تكنولوجيا الفيديو.
// Play the VOD pod stream.
streamID = streamManager.getStreamId();
String vodStreamUrl = "";
// Refer to your Video Tech Partner (VTP) or video stitching guide to fetch the stream URL
// and the subtitles for a the ad stitched VOD stream.

// In the following commented out code, 'vtpInterface' is a place holder
// for your own video technology partner (VTP) API calls.
// vodStreamUrl = vtpInterface.requestStreamURL(streamID);
List<Map<String, String>> subtitles = new ArrayList<>();
streamManager.loadThirdPartyStream(vodStreamUrl, subtitles);

بالنسبة إلى طلبات عرض الإعلانات المتسلسلة في الفيديو عند الطلب، تستدعي حزمة IMA الدالة VideoStreamPlayer.loadUrl() عند تحميل البث. لبدء تشغيل البث، أضِف طلبَي videoPlayer.setStreamUrl() وvideoPlayer.play() إلى دالة الاستدعاء VideoStreamPlayer.loadUrl():

private VideoStreamPlayer createVideoStreamPlayer() {
  return new VideoStreamPlayer() {
    @Override
    public void loadUrl(String url, List<HashMap<String, String>> subtitles) {
      // IMA doesn't make calls to VideoStreamPlayer.loadUrl() for pod serving live streams.
      // The following code is for VOD streams.
      videoPlayer.setStreamUrl(url);
      videoPlayer.play();
    }

تنظيف مواد عرض IMA DAI

بعد الانتهاء بنجاح من طلب الإعلانات وعرضها في بث Pod Serving باستخدام حزمة تطوير البرامج IMA DAI SDK، ننصحك بتنظيف أي موارد بعد اكتمال جلسة Pod Serving. اتّصِل بالرقم StreamManager.destroy() لإيقاف تشغيل البث المباشر، وإيقاف جميع عمليات تتبُّع الإعلانات، وإصدار جميع مواد عرض البث المباشر التي تم تحميلها.

للاطّلاع على أمثلة أخرى على استخدام حزمة تطوير البرامج (SDK) لنظام التشغيل Android، يمكنك الرجوع إلى الأمثلة على GitHub.