إدراج إعلان

يمكن استخدام ExoPlayer لإدراج الإعلانات من جهة العميل ومن جهة الخادم.

إدراج الإعلانات من جهة العميل

في عملية إدراج الإعلانات من جهة العميل، ينتقل المشغّل بين تحميل الوسائط من عناوين URL مختلفة أثناء الانتقال بين تشغيل المحتوى والإعلانات. يتم تحميل المعلومات المتعلقة بالإعلانات بشكل منفصل عن الوسائط، مثل علامة إعلان VAST أو VMAP بتنسيق XML. ويمكن أن يشمل ذلك مواضع إشارات الإعلانات بالنسبة إلى بداية المحتوى، وعناوين URI الفعلية لوسائط الإعلانات، والبيانات الوصفية، مثل ما إذا كان من الممكن تخطّي إعلان معيّن.

عند استخدام AdsMediaSource في ExoPlayer لإدراج الإعلانات من جهة العميل، يحصل المشغّل على معلومات عن الإعلانات التي سيتم تشغيلها. هناك عدة فوائد لهذا التغيير:

  • يمكن للمشغّل عرض البيانات الوصفية والوظائف المتعلقة بالإعلانات باستخدام واجهة برمجة التطبيقات الخاصة به.
  • يمكن أن تعرض مكوّنات واجهة مستخدم ExoPlayer علامات لمواضع عرض الإعلانات تلقائيًا، وتغيير سلوكها بناءً على ما إذا كان الإعلان قيد التشغيل.
  • داخليًا، يمكن للمشغّل الاحتفاظ بمخزن مؤقت متسق في جميع عمليات الانتقال بين الإعلانات والمحتوى.

في هذا الإعداد، يتولّى المشغّل التبديل بين الإعلانات والمحتوى، ما يعني أنّ التطبيقات لا تحتاج إلى التحكّم في عدة مشغّلات منفصلة في الخلفية والمقدّمة للإعلانات والمحتوى.

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

دعم الإعلانات التعريفية

يمكن تحديد معرّف موارد منتظم (URI) لعلامة إعلان عند إنشاء MediaItem:

Kotlin

val mediaItem =
  MediaItem.Builder()
    .setUri(videoUri)
    .setAdsConfiguration(MediaItem.AdsConfiguration.Builder(adTagUri).build())
    .build()

Java

MediaItem mediaItem =
    new MediaItem.Builder()
        .setUri(videoUri)
        .setAdsConfiguration(new MediaItem.AdsConfiguration.Builder(adTagUri).build())
        .build();

لتفعيل دعم المشغّل لملفات الوسائط التي تحدّد علامات الإعلانات، من الضروري إنشاء وإدخال DefaultMediaSourceFactory تم ضبطه باستخدام AdsLoader.Provider وAdViewProvider عند إنشاء المشغّل:

Kotlin

val mediaSourceFactory: MediaSource.Factory =
  DefaultMediaSourceFactory(context)
    .setLocalAdInsertionComponents(adsLoaderProvider, playerView)
val player = ExoPlayer.Builder(context).setMediaSourceFactory(mediaSourceFactory).build()

Java

MediaSource.Factory mediaSourceFactory =
    new DefaultMediaSourceFactory(context)
        .setLocalAdInsertionComponents(adsLoaderProvider, /* adViewProvider= */ playerView);
ExoPlayer player =
    new ExoPlayer.Builder(context).setMediaSourceFactory(mediaSourceFactory).build();

داخليًا، سيلف DefaultMediaSourceFactory مصدر وسائط المحتوى في AdsMediaSource. سيحصل AdsMediaSource على AdsLoader من AdsLoader.Provider وسيستخدمه لإدراج الإعلانات على النحو المحدّد في علامة الإعلان الخاصة بملف الوسائط.

تنفّذ واجهة PlayerView في ExoPlayer واجهة AdViewProvider. توفّر مكتبة ExoPlayer IMA واجهة AdsLoader، كما هو موضّح لاحقًا.

قوائم تشغيل تتضمّن إعلانات

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

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

Kotlin

// Build the media items, passing the same ads identifier for both items,
// which means they share ad playback state so ads play only once.
val firstItem =
  MediaItem.Builder()
    .setUri(firstVideoUri)
    .setAdsConfiguration(
      MediaItem.AdsConfiguration.Builder(adTagUri).setAdsId(adTagUri).build()
    )
    .build()
val secondItem =
  MediaItem.Builder()
    .setUri(secondVideoUri)
    .setAdsConfiguration(
      MediaItem.AdsConfiguration.Builder(adTagUri).setAdsId(adTagUri).build()
    )
    .build()
player.addMediaItem(firstItem)
player.addMediaItem(secondItem)

Java

// Build the media items, passing the same ads identifier for both items,
// which means they share ad playback state so ads play only once.
MediaItem firstItem =
    new MediaItem.Builder()
        .setUri(firstVideoUri)
        .setAdsConfiguration(
            new MediaItem.AdsConfiguration.Builder(adTagUri).setAdsId(adTagUri).build())
        .build();
MediaItem secondItem =
    new MediaItem.Builder()
        .setUri(secondVideoUri)
        .setAdsConfiguration(
            new MediaItem.AdsConfiguration.Builder(adTagUri).setAdsId(adTagUri).build())
        .build();
player.addMediaItem(firstItem);
player.addMediaItem(secondItem);

إدراج الإعلانات من جهة العميل بتوجيه من الخادم

يتضمّن ExoPlayer مكوّن HlsInterstitialsAdsLoader الذي يتيح إدراج الإعلانات المحدّدة في قائمة تشغيل HLS على جانب العميل تلقائيًا. يُرجى الاطّلاع على القسم حول HlsInterstitialsAdsLoader في صفحة HLS.

مكتبة ExoPlayer IMA

توفّر مكتبة ExoPlayer IMA السمة ImaAdsLoader لدمج إدراج الإعلانات من جهة العميل في تطبيقك، وتتضمّن وظائف حزمة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية من جهة العميل لإتاحة إدراج إعلانات VAST/VMAP. للحصول على تعليمات حول كيفية استخدام المكتبة، بما في ذلك كيفية التعامل مع التشغيل في الخلفية واستئناف التشغيل، يُرجى الاطّلاع على ملف README.

يستخدم التطبيق التجريبي مكتبة IMA، ويتضمّن العديد من نماذج علامات إعلانات VAST/VMAP في قائمة النماذج.

اعتبارات واجهة المستخدم

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

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

لمزيد من المعلومات عن طرق عرض الإعلانات المركّبة، يُرجى الاطّلاع على Open Measurement في حزمة تطوير البرامج للإعلانات التفاعلية (IMA SDK).

الإعلانات المصاحبة

تحتوي بعض علامات الإعلانات على إعلانات مصاحبة إضافية يمكن عرضها في "خانات" في واجهة مستخدم التطبيق. يمكن تمرير هذه الخانات باستخدام ImaAdsLoader.Builder.setCompanionAdSlots(slots). لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إضافة إعلانات مصاحبة.

إعلانات مستقلة

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

استخدام حزمة تطوير برامج (SDK) تابعة لجهة خارجية لعرض الإعلانات

إذا كنت بحاجة إلى تحميل الإعلانات باستخدام حزمة تطوير برامج (SDK) تابعة لجهة خارجية، ننصحك بالتحقّق مما إذا كانت توفّر ميزة دمج ExoPlayer. وإذا لم يكن الأمر كذلك، ننصحك بتنفيذ AdsLoader مخصّص يغلّف حزمة تطوير البرامج (SDK) لعرض الإعلانات التابعة لجهة خارجية، لأنّه يوفّر مزايا AdsMediaSource الموضّحة سابقًا. يُعدّ ImaAdsLoader مثالاً على عملية التنفيذ.

بدلاً من ذلك، يمكنك استخدام دعم قائمة التشغيل في ExoPlayer لإنشاء تسلسل من الإعلانات ومقاطع المحتوى:

Kotlin

// A pre-roll ad.
val preRollAd = MediaItem.fromUri(preRollAdUri)
// The start of the content.
val contentStart =
  MediaItem.Builder()
    .setUri(contentUri)
    .setClippingConfiguration(
      MediaItem.ClippingConfiguration.Builder().setEndPositionMs(120000).build()
    )
    .build()
// A mid-roll ad.
val midRollAd = MediaItem.fromUri(midRollAdUri)
// The rest of the content
val contentEnd =
  MediaItem.Builder()
    .setUri(contentUri)
    .setClippingConfiguration(
      MediaItem.ClippingConfiguration.Builder().setStartPositionMs(120000).build()
    )
    .build()

// Build the playlist.
player.addMediaItem(preRollAd)
player.addMediaItem(contentStart)
player.addMediaItem(midRollAd)
player.addMediaItem(contentEnd)

Java

// A pre-roll ad.
MediaItem preRollAd = MediaItem.fromUri(preRollAdUri);
// The start of the content.
MediaItem contentStart =
    new MediaItem.Builder()
        .setUri(contentUri)
        .setClippingConfiguration(
            new MediaItem.ClippingConfiguration.Builder().setEndPositionMs(120_000).build())
        .build();
// A mid-roll ad.
MediaItem midRollAd = MediaItem.fromUri(midRollAdUri);
// The rest of the content
MediaItem contentEnd =
    new MediaItem.Builder()
        .setUri(contentUri)
        .setClippingConfiguration(
            new MediaItem.ClippingConfiguration.Builder().setStartPositionMs(120_000).build())
        .build();

// Build the playlist.
player.addMediaItem(preRollAd);
player.addMediaItem(contentStart);
player.addMediaItem(midRollAd);
player.addMediaItem(contentEnd);

إدراج الإعلانات من جهة الخادم

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

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

يمكن لـ DefaultMediaSourceFactory في ExoPlayer تفويض كل هذه المهام إلى MediaSource لإدراج الإعلانات من جهة الخادم لمعرّفات الموارد المنتظمة (URI) التي تستخدم المخطط ssai://:

Kotlin

val player =
  ExoPlayer.Builder(context)
    .setMediaSourceFactory(
      DefaultMediaSourceFactory(context).setServerSideAdInsertionMediaSourceFactory(ssaiFactory)
    )
    .build()

Java

Player player =
    new ExoPlayer.Builder(context)
        .setMediaSourceFactory(
            new DefaultMediaSourceFactory(context)
                .setServerSideAdInsertionMediaSourceFactory(ssaiFactory))
        .build();

مكتبة ExoPlayer IMA

توفّر مكتبة ExoPlayer IMA السمة ImaServerSideAdInsertionMediaSource لدمجها مع مصادر بيانات الإعلانات التي يتم إدراجها من جهة الخادم في حزمة تطوير البرامج للإعلانات التفاعلية (IMA) في تطبيقك. وتتضمّن هذه المكتبة وظائف حزمة تطوير البرامج (SDK) لعرض الإعلانات الديناميكي (DAI) في IMA لنظام التشغيل Android وتدمج البيانات الوصفية للإعلانات المقدَّمة في المشغّل بشكل كامل. على سبيل المثال، يتيح لك ذلك استخدام طرق مثل Player.isPlayingAd()، والاستماع إلى عمليات الانتقال بين المحتوى والإعلانات، والسماح للمشغّل بالتعامل مع منطق تشغيل الإعلانات، مثل تخطّي الإعلانات التي سبق تشغيلها.

لاستخدام هذه الفئة، عليك إعداد ImaServerSideAdInsertionMediaSource.AdsLoader و ImaServerSideAdInsertionMediaSource.Factory وربطهما بالمشغّل:

Kotlin

// MediaSource.Factory to load the actual media stream.
val defaultMediaSourceFactory = DefaultMediaSourceFactory(context)
// AdsLoader that can be reused for multiple playbacks.
val adsLoader =
  ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(context, adViewProvider).build()
// MediaSource.Factory to create the ad sources for the current player.
val adsMediaSourceFactory =
  ImaServerSideAdInsertionMediaSource.Factory(adsLoader, defaultMediaSourceFactory)
// Configure DefaultMediaSourceFactory to create both IMA DAI sources and
// regular media sources. If you just play IMA DAI streams, you can also use
// adsMediaSourceFactory directly.
defaultMediaSourceFactory.setServerSideAdInsertionMediaSourceFactory(adsMediaSourceFactory)
// Set the MediaSource.Factory on the Player.
val player = ExoPlayer.Builder(context).setMediaSourceFactory(defaultMediaSourceFactory).build()
// Set the player on the AdsLoader
adsLoader.setPlayer(player)

Java

// MediaSource.Factory to load the actual media stream.
DefaultMediaSourceFactory defaultMediaSourceFactory = new DefaultMediaSourceFactory(context);
// AdsLoader that can be reused for multiple playbacks.
ImaServerSideAdInsertionMediaSource.AdsLoader adsLoader =
    new ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(context, adViewProvider).build();
// MediaSource.Factory to create the ad sources for the current player.
ImaServerSideAdInsertionMediaSource.Factory adsMediaSourceFactory =
    new ImaServerSideAdInsertionMediaSource.Factory(adsLoader, defaultMediaSourceFactory);
// Configure DefaultMediaSourceFactory to create both IMA DAI sources and
// regular media sources. If you just play IMA DAI streams, you can also use
// adsMediaSourceFactory directly.
defaultMediaSourceFactory.setServerSideAdInsertionMediaSourceFactory(adsMediaSourceFactory);
// Set the MediaSource.Factory on the Player.
Player player =
    new ExoPlayer.Builder(context).setMediaSourceFactory(defaultMediaSourceFactory).build();
// Set the player on the AdsLoader
adsLoader.setPlayer(player);

حمِّل مفتاح مادة عرض IMA أو معرّف مصدر المحتوى ومعرّف الفيديو من خلال إنشاء عنوان URL باستخدام ImaServerSideAdInsertionUriBuilder:

Kotlin

val ssaiUri =
  ImaServerSideAdInsertionUriBuilder()
    .setAssetKey(assetKey)
    .setFormat(C.CONTENT_TYPE_HLS)
    .build()
player.setMediaItem(MediaItem.fromUri(ssaiUri))

Java

Uri ssaiUri =
    new ImaServerSideAdInsertionUriBuilder()
        .setAssetKey(assetKey)
        .setFormat(C.CONTENT_TYPE_HLS)
        .build();
player.setMediaItem(MediaItem.fromUri(ssaiUri));

أخيرًا، يمكنك تحرير أداة تحميل الإعلانات بعد الانتهاء من استخدامها:

Kotlin

adsLoader.release()

Java

adsLoader.release();

اعتبارات واجهة المستخدم

تنطبق اعتبارات واجهة المستخدم نفسها الخاصة بإدراج الإعلانات من جهة العميل على إدراج الإعلانات من جهة الخادم أيضًا.

الإعلانات المصاحبة

تحتوي بعض علامات الإعلانات على إعلانات مصاحبة إضافية يمكن عرضها في "خانات" في واجهة مستخدم التطبيق. يمكن تمرير هذه الخانات باستخدام ImaServerSideAdInsertionMediaSource.AdsLoader.Builder.setCompanionAdSlots(slots). لمزيد من المعلومات، يُرجى الاطّلاع على إضافة إعلانات مصاحبة.

استخدام حزمة تطوير برامج (SDK) تابعة لجهة خارجية لعرض الإعلانات

إذا كنت بحاجة إلى تحميل الإعلانات باستخدام حزمة تطوير برامج (SDK) تابعة لجهة خارجية، ننصحك بالتحقّق مما إذا كانت توفّر ميزة دمج ExoPlayer. وإذا لم يكن الأمر كذلك، ننصحك بتقديم MediaSource مخصّص يقبل معرّفات الموارد المنتظمة (URI) باستخدام المخطط ssai:// على غرار ImaServerSideAdInsertionMediaSource.

يمكن تفويض المنطق الفعلي لإنشاء بنية الإعلان إلى ServerSideAdInsertionMediaSource للأغراض العامة، والذي يلتف حول بث MediaSource ويسمح للمستخدم بضبط وتعديل AdPlaybackState الذي يمثّل البيانات الوصفية للإعلان.

غالبًا ما تحتوي مجموعات الإعلانات المُدرَجة من جهة الخادم على أحداث محدّدة بوقت لإعلام المشغّل بالبيانات الوصفية للإعلان. يمكنك الاطّلاع على التنسيقات المتوافقة للحصول على معلومات حول تنسيقات البيانات الوصفية المحدّدة زمنيًا التي يتوافق معها ExoPlayer. يمكن لعمليات تنفيذ حزمة تطوير البرامج (SDK) المخصّصة للإعلانات MediaSource الاستماع إلى أحداث البيانات الوصفية المحدّدة زمنيًا من المشغّل باستخدام Player.Listener.onMetadata.