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

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

اختيار حلّ DAI المطلوب

خدمة كاملة خدمة Pod

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

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

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

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

يوضِّح هذا الدليل كيفية ضبط المشغّل الخارجي وحزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية لتشغيل بث HLS. للاطّلاع على مثال لمشغِّل فيديو يتيح البث باستخدام بروتوكول HLS وDASH، يُرجى مراجعة المثال المتقدّم.

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

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

نظرة عامة على عرض الإعلانات المتسلسلة لإعلانات الوسائط التفاعلية

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

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

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

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

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

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

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

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

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

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

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

• API_KEY: يُستخدم فقط لأحداث البث المباشر: مفتاح اختياري لواجهة برمجة التطبيقات يمكن أن يكون مطلوبًا لاسترداد رقم تعريف مصدر البيانات من حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية.

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

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

/** 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() أن تحمِّل "إعلانات الوسائط التفاعلية" عنوان 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() منه.

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

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

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