الإعداد باستخدام ميزة "إدراج الإعلان الديناميكي" (DAI) في خدمة Pod

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

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

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

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

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

  • StreamManager: عنصر يعالج الاتصال بين بث الفيديو وحزمة تطوير البرامج (SDK) لتقنية IMA DAI، مثل تنشيط إشعارات التتبّع وإعادة توجيه أحداث البث إلى الناشر.

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

  • تطبيق Android تم إعداده مسبقًا باستخدام حزمة تطوير البرامج (SDK) لإدراج الإعلان الديناميكي (DAI) في إعلانات الوسائط التفاعلية (IMA) لتشغيل فيديوهات البث المباشر مع إعلانات DAI. إذا لم يكن لديك تطبيق من هذا النوع، ننصحك باستخدام Android DAI BasicExample كنقطة انطلاق. يحتوي BasicExample على قاعدة الرموز البرمجية المُشار إليها في هذا الدليل.

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

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

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

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

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

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

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

  • 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 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

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

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