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

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

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

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

نظرة عامة على عرض مجموعات إعلانية متسلسلة في 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) لتقنية IMA DAI، ننصحك بإزالة أي موارد بعد اكتمال جلسة عرض الإعلانات المتعدّدة. يمكنك استدعاء StreamManager.destroy() لإيقاف تشغيل البث وإيقاف تتبُّع الإعلانات وإصدار جميع مواد عرض البث التي تم تحميلها.

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