إدراج إعلان

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

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

عند إدراج الإعلان من جهة العميل، يبدِّل المشغّل بين تحميل الوسائط من عناوين URL مختلفة عند الانتقال بين محتوى تشغيل المحتوى والإعلانات. معلومات حول الإعلانات بشكل منفصل عن الوسائط، مثل تحميل نموذج عرض إعلانات فيديو (VAST) بتنسيق XML أو علامة إعلان VMAP. وقد يشمل ذلك مواضع إشارات الإعلانات بالنسبة إلى بداية ومعرفات الموارد المنتظمة (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 ملف AdsLoader سهل الاستخدام على النحو الموضَّح أدناه.

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

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

من الممكن تخصيص هذا السلوك من خلال تمرير معرّف إعلانات مبهم حالة تشغيل الإعلان المرتبطة بعنصر وسائط معيّن، استنادًا إلى العنصر والمساواة. في ما يلي مثال حيث تكون حالة تشغيل الإعلان مرتبطة بعلامة الإعلان عنوان 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

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

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

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

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

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

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

لمزيد من المعلومات عن طرق العرض المركّبة، يُرجى مراجعة افتح عملية القياس في حزمة تطوير البرامج لإعلانات الوسائط التفاعلية.

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

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

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

تم تصميم حزمة تطوير البرامج لإعلانات الوسائط التفاعلية لإدراج الإعلانات في محتوى الوسائط، وليس للتشغيل إعلانات مستقلة في حد ذاتها. وبالتالي لا يمكن تشغيل الإعلانات المستقلة. بمكتبة إعلانات الوسائط التفاعلية نقترح استخدام 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(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(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 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 ClippingConfiguration.Builder().setStartPositionMs(120_000).build())
        .build();

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

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

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

عند استخدام ميزة إدراج الإعلانات من جهة الخادم، قد يحتاج العميل إلى حلّ الوسائط عنوان 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

توفّر مكتبة إعلانات الوسائط التفاعلية في ExoPlayer القيمة ImaServerSideAdInsertionMediaSource تسهيل عملية الدمج مع مجموعات بث الإعلانات المدرجة من جهة الخادم لإعلانات الوسائط التفاعلية في التطبيق. فهو يشمل وظائف حزمة تطوير البرامج لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية لنظام التشغيل 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);

تحميل مفتاح مادة عرض إعلانات الوسائط التفاعلية أو معرّف مصدر المحتوى ومعرّف الفيديو من خلال إنشاء عنوان 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