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

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

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

الخدمة الكاملة عرض الإعلانات في حزم

إدراج إعلان ديناميكي في البودكاست

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

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

ملاحظة: تتوافق حزمة تطوير البرامج لإعلانات الوسائط التفاعلية (DAI) على Android مع كلّ من بث HLS وبث DASH.

يوضّح هذا الدليل كيفية ضبط exoplayer وIMA DAI SDK لتشغيل بث مباشر وفق بروتوكول HTTP ‏(HLS). للاطّلاع على مثال على مشغّل فيديو يتيح بث محتوى HLS وDASH، يُرجى مراجعة المثال المتقدّم.

نقطة أساسية: لاستخدام ميزة "عرض الإعلانات المباشرة في حزم" من "إعلانات الوسائط التفاعلية"، يجب أن تعمل مع شريك يقدّم هذه الميزة وأن يكون لديك حساب متقدّم على "مدير إعلانات Google‏ 360". إذا كان لديك حساب على "مدير إعلانات Google"، تواصَل مع مدير حسابك للحصول على مزيد من التفاصيل. للحصول على معلومات حول الاشتراك في "مدير إعلانات Google"، يُرجى الانتقال إلى مركز مساعدة "مدير إعلانات Google".

ملاحظة: للحصول على معلومات حول الدمج مع منصات أخرى أو حول استخدام حِزم تطوير البرامج (SDK) من جهة العميل الخاصة بـ "إعلانات الوسائط التفاعلية"، يُرجى الاطّلاع على حِزم تطوير البرامج (SDK) الخاصة بـ "إعلانات الوسائط التفاعلية".

نظرة عامة حول عرض "إعلانات ضمن مجموعة" في "إدراج الإعلان الديناميكي" من "إعلانات الوسائط التفاعلية"

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

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

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

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

• من المهم أن يرسل تطبيقك أحداث ID3 باستخدام VideoStreamPlayerCallback.onUserTextReceived() لكي تعمل ميزة "إعلانات البث المباشر" في "إعلانات الوسائط التفاعلية". اطّلِع على مثال مقتطف الرمز الخاص بخدمة DAI الكاملة.

إعداد متغيرات "عرض الإعلانات ضمن البودكاست"

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

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

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

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

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

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

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

ملاحظة: إنّ مَعلمات البث المقدَّمة هي لبث مباشر ضمن "غرفة بث مباشر". لاختبار بث فيديو عند الطلب (VOD) باستخدام ميزة "عرض الإعلانات المتسلسلة"، عليك تقديم معلَمات بث الاختبار الخاصة بك.

/** 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;
SampleAdsWrapper.java

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

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

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

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

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

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

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

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

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

تعديل عنوان 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();
SampleAdsWrapper.java

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

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);
SampleAdsWrapper.java

بالنسبة إلى طلبات عرض الإعلانات ضمن حزمة الفيديو عند الطلب، تستدعي حزمة 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();
    }
SampleAdsWrapper.java

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

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

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