بدء استخدام حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية

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

اختيار حلّ DAI الذي يهمّك

الخدمة الكاملة عرض مجموعة فيديوهات

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

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

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

ملاحظة: تتيح أداة تطوير البرامج لعرض الإعلانات الديناميكية في "إعلانات الوسائط التفاعلية" لنظام التشغيل Android بثّ كلّ من HLS وDASH.

يوضّح هذا الدليل كيفية ضبط حِزم تطوير البرامج exoplayer وIMA DAI SDK لتشغيل بث HLS. للحصول على مثال لمشغّل فيديو يتيح بثّ HLS وDASH، يمكنك الاطّلاع على المثال المتقدّم.

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

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

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

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

• ‫StreamManager: عنصر يعالج التواصل بين مجرى الفيديو وحزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية (IMA DAI SDK)، مثل تنشيط إشارات التتبّع و forwarded stream events إلى الناشر.

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

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

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

إعداد متغيّرات عرض الحِزم

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

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

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

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

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

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

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

ملاحظة: مَعلمات البث المقدَّمة مخصّصة لبث مجموعة قنوات بث مباشر. لاختبار البث باستخدام بث الفيديو عند الطلب لعرض مجموعة من الفيديوهات، عليك تقديم مَعلمات البث التجريبي.

/** This class adds ad-serving support to Sample HlsVideoPlayer */
public class SampleAdsWrapper
        implements AdEvent.AdEventListener, AdErrorEvent.AdErrorListener, AdsLoader.AdsLoadedListener {

  // Podserving Stream Constants.
  private static final String STREAM_URL =
          "https://encodersim.sandbox.google.com/masterPlaylist/9c654d63-5373-4673-8c8d-6d92b66b9d46/" +
          "master.m3u8?gen-seg-redirect=true&network=51636543&event=google-sample" +
          "&pids=devrel4628000,devrel896000,devrel3528000,devrel1428000,devrel2628000,devrel1928000" +
          "&seg-host=dai.google.com&stream_id=[[STREAMID]]";
  private static final String NETWORK_CODE = "51636543";
  private static final String CUSTOM_ASSET_KEY = "google-sample";
  private static final String API_KEY = "";

  private static final String PLAYER_TYPE = "DAISamplePlayer";

  /** Log interface, so we can output the log commands to the UI or similar. */
  public interface Logger {

...

أنشئ طلبًا لبث مجموعة فيديوهات في فيديو واحد، سواء كان بثًا مباشرًا أو فيديو مسجّلاً، لتفعيل ميزة "عرض مجموعة الفيديوهات".

عرض مجموعات البث المباشر

أزِل الطريقة buildStreamRequest() التي تم استخدامها للتبديل بين إنشاء أنواع مختلفة من أحداث البث. بعد ذلك، غيِّر requestAndPlayAds() إلى طلب ImaSdkFactory.createPodStreamRequest() لإنشاء طلب عرض إعلانات مجموعات إعلانية متسلسلة في الفيديوهات المباشرة. أخيرًا، اطلب البث باستخدام AdsLoader.requestStream().

public void requestAndPlayAds() {
  StreamRequest request =
      sdkFactory.createPodStreamRequest(NETWORK_CODE, CUSTOM_ASSET_KEY, API_KEY);
  request.setFormat(StreamFormat.HLS);

  adsLoader.addAdErrorListener(this);
  adsLoader.addAdsLoadedListener(this);
  adsLoader.requestStream(request);
}

عرض مجموعة فيديوهات مسجّلة

أزِل الطريقة buildStreamRequest() التي تم استخدامها للتبديل بين إنشاء أنواع مختلفة من أحداث البث. بعد ذلك، غيِّر requestAndPlayAds() إلى طلب ImaSdkFactory.createPodVodStreamRequest() لإنشاء طلب عرض إعلانات مجموعة فيديوهات عند الطلب. أخيرًا، اطلب البث باستخدام AdsLoader.requestStream().

public void requestAndPlayAds() {
  StreamRequest request =
      sdkFactory.createPodVodStreamRequest(NETWORK_CODE);
  request.setFormat(StreamFormat.HLS);

  adsLoader.addAdErrorListener(this);
  adsLoader.addAdsLoadedListener(this);
  adsLoader.requestStream(request);
}

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

عرض مجموعات البث المباشر

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

@Override
public void onAdsManagerLoaded(AdsManagerLoadedEvent event) {
  streamManager = event.getStreamManager();
  streamManager.addAdErrorListener(this);
  streamManager.addAdEventListener(this);

  // To enable streams
  String streamID = streamManager.getStreamId();
  String streamUrl = STREAM_URL.replace("[[STREAMID]]", streamID);

  streamManager.init();

  videoPlayer.setStreamUrl(streamUrl);
  videoPlayer.play();
}

عرض مجموعة فيديوهات مسجّلة

يُرجى الاتصال برقم StreamManager.getStreamId() للحصول على معرّف مصدر البيانات. بعد ذلك، اطلب عنوان URL لبث المحتوى من شريك تكنولوجيا الفيديو (VTP). بعد ذلك، اتصل بالرقم StreamManager.loadThirdPartyStream() لتحميل IMA عنوان URL للبث وأي ترجمة تقدّمها وحدة التحكّم في البرنامج التلفزيوني (TVP).

@Override
public void onAdsManagerLoaded(AdsManagerLoadedEvent event) {
  streamManager = event.getStreamManager();
  streamManager.addAdErrorListener(this);
  streamManager.addAdEventListener(this);

  // To enable streams
  String streamID = streamManager.getStreamId();
  // 'vtpInterface' is a place holder for your own video technology partner
  // (VTP) API calls.
  String streamUrl = vtpInterface.requestStreamURL(streamID);

  streamManager.init();

  // Pass any subtitles returned by your VTP in this step as well.
  streamManager.loadThirdPartyStream(streamUrl, subtitles);
}

عند تفعيل ميزة "عرض مجموعات الإعلانات"، لا تُجري منصّة IMA مكالمات إلى VideoStreamPlayer.loadUrl()، لذا يمكنك إزالة أيّ مكالمات إلى videoPlayer.setStreamUrl() وvideoPlayer.play() منها.

تنظيف مواد عرض "الإعلانات الديناميكية أثناء عرض الفيديو" في IMA

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

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