درج آگهی

از ExoPlayer می‌توان برای درج آگهی در سمت کارخواه و سمت سرور استفاده کرد.

درج آگهی سمت کارخواه

در درج آگهی سمت کارخواه، پخش‌کننده هنگام جابه‌جایی بین پخش محتوا و آگهی، بین بارگیری رسانه از نشانی‌های وب مختلف جابه‌جا می‌شود. اطلاعات درباره آگهی‌ها جدا از رسانه بار می‌شود، مثلاً از برچسب آگهی XML VAST یا VMAP. این می‌تواند شامل موقعیت‌های نشانه آگهی نسبت به شروع محتوا، URIهای رسانه آگهی واقعی، و فراداده‌هایی مانند قابل‌رد شدن بودن یک آگهی خاص باشد.

هنگام استفاده از AdsMediaSource ExoPlayer برای درج آگهی سمت کارخواه، پخش‌کننده اطلاعاتی درباره آگهی‌هایی که باید پخش شوند دارد. این کار چند مزیت دارد:

  • پخش‌کننده می‌تواند فراداده و عملکرد مربوط به آگهی‌ها را بااستفاده از API خود نمایش دهد.
  • مؤلفه‌های ExoPlayer UI می‌توانند نشانگرهای جایگاه‌های آگهی را به‌طور خودکار نشان دهند و رفتارشان را بسته به اینکه آگهی درحال پخش است یا نه تغییر دهند.
  • به‌طور داخلی، پخش‌کننده می‌تواند میان‌گیری ثابتی را درطول انتقال بین آگهی‌ها و محتوا حفظ کند.

در این راه‌اندازی، پخش‌کننده جابه‌جایی بین آگهی‌ها و محتوا را انجام می‌دهد، یعنی برنامه‌ها نیازی به کنترل چندین پخش‌کننده پس‌زمینه و پیش‌زمینه جداگانه برای آگهی‌ها و محتوا ندارند.

هنگام آماده‌سازی ویدیوهای محتوا و برچسب‌های آگهی برای استفاده با درج آگهی سمت مشتری، آگهی‌ها باید در حالت ایده‌آل در نمونه‌های همگام‌سازی (فریم‌های کلیدی) در ویدیو محتوا قرار گیرند تا پخش‌کننده بتواند پخش محتوا را به‌طور یکپارچه ازسر بگیرد.

پشتیبانی آگهی اعلانی

هنگام ساختن MediaItem می‌توان شناسه منبع یکسان برچسب آگهی را مشخص کرد:

کاتلین

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

جاوا

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

برای فعال کردن پشتیبانی پخش‌کننده برای فایل‌های رسانه‌ای که برچسب‌های آگهی را مشخص می‌کنند، لازم است هنگام ایجاد پخش‌کننده، یک DefaultMediaSourceFactory پیکربندی‌شده با AdsLoader.Provider و AdViewProvider بسازید و تزریق کنید:

کاتلین

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

جاوا

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 ارائه می‌دهد، همان‌طور که بعداً توضیح داده شده است.

فهرست‌های پخش با آگهی

هنگام پخش فهرست پخش با چند فایل رسانه‌ای، رفتار پیش‌فرض این است که برچسب آگهی درخواست شود و وضعیت بازپخش آگهی یک‌بار برای هر ترکیب شناسه رسانه، شناسه منبع یکسان محتوا، و شناسه منبع یکسان برچسب آگهی ذخیره شود. این یعنی کاربران برای هر فایل رسانه‌ای دارای آگهی که شناسه رسانه یا شناسه منبع یکسان محتوای متمایز دارد آگهی خواهند دید، حتی اگر شناسه منبع یکسان برچسب آگهی مطابقت داشته باشد. اگر فایل رسانه‌ای تکرار شود، کاربر آگهی‌های مربوطه را فقط یک بار خواهد دید (وضعیت بازپخش آگهی ذخیره می‌کند که آیا آگهی‌ها پخش شده‌اند یا نه، بنابراین پس‌از اولین وقوع رد می‌شوند).

It's possible to customize this behavior by passing an opaque ads identifier with which ad playback state for a given media item is linked, based on object equality. در اینجا مثالی آورده شده است که در آن وضعیت بازپخش آگهی فقط به URI برچسب آگهی پیوند داده شده است، نه به ترکیب شناسه رسانه و URI برچسب آگهی، با ارسال URI برچسب آگهی به‌عنوان شناسه آگهی. نتیجه این است که آگهی‌ها فقط یک‌بار بار می‌شود و کاربر هنگام پخش فهرست پخش از ابتدا تا انتها، آگهی‌ها را در مورد دوم نخواهد دید.

کاتلین

// 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)

جاوا

// 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 را برای ادغام درج آگهی سمت کارخواه در برنامه شما ارائه می‌دهد. این کتابخانه عملکرد کیت توسعه نرم‌افزار IMA سمت کارخواه را برای پشتیبانی از درج آگهی‌های VAST/VMAP دربرمی‌گیرد. برای دستورالعمل‌های نحوه استفاده از کتابخانه، ازجمله نحوه مدیریت پس‌زمینه و ازسرگیری بازپخش، به README مراجعه کنید.

برنامه نمایشی از کتابخانه IMA استفاده می‌کند و شامل چندین نمونه برچسب آگهی VAST/VMAP در فهرست نمونه است.

ملاحظات میانای کاربر

PlayerView به‌طور پیش‌فرض کنترل‌های انتقال را درطول بازپخش آگهی‌ها پنهان می‌کند، اما برنامه‌ها می‌توانند با فراخوانی setControllerHideDuringAds این رفتار را تغییر دهند. IMA SDK درحین پخش آگهی، نماهای بیشتری را در بالای پخش‌کننده نشان می‌دهد (برای مثال، پیوند «اطلاعات بیشتر» و دکمه رد کردن، درصورت وجود).

کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی ممکن است گزارش دهد که آیا آگهی‌ها توسط نماهای ارائه‌شده توسط برنامه که در بالای پخش‌کننده ارائه شده‌اند، پنهان شده‌اند یا نه. برنامه‌هایی که باید نماهای ضروری برای کنترل بازپخش را هم‌پوشانی کنند باید آن‌ها را در کیت توسعه نرم‌افزار IMA ثبت کنند تا بتوان آن‌ها را از محاسبات قابلیت مشاهده حذف کرد. وقتی از PlayerView به‌عنوان AdViewProvider استفاده می‌کنید، هم‌پوشانی‌های کنترل آن به‌طور خودکار ثبت می‌شود. برنامه‌هایی که از واسط کاربر پخش‌کننده سفارشی استفاده می‌کنند باید نماهای هم‌پوشانی را با برگرداندن آن‌ها از AdViewProvider.getAdOverlayInfos ثبت کنند.

برای اطلاعات بیشتر درباره نماهای هم‌پوشان، به سنجش باز در کیت توسعه نرم‌افزار IMA مراجعه کنید.

تبلیغات هم‌نشین

برخی‌از برچسب‌های آگهی حاوی آگهی‌های همپای اضافی هستند که می‌توانند در «جایگاه‌های» رابط کاربری برنامه نشان داده شوند. این جایگاه‌ها را می‌توان بااستفاده از ImaAdsLoader.Builder.setCompanionAdSlots(slots) منتقل کرد. برای اطلاعات بیشتر، به افزودن آگهی‌های همپا مراجعه کنید.

آگهی‌های مستقل

کیت توسعه نرم‌افزار آگهی‌های رسانه‌ای تعاملی برای درج آگهی در محتوای رسانه‌ای طراحی شده است، نه برای پخش آگهی‌های مستقل به‌تنهایی. بنابراین، بازپخش آگهی‌های مستقل توسط کتابخانه IMA پشتیبانی نمی‌شود. توصیه می‌کنیم برای این مورد استفاده، از کیت توسعه نرم‌افزار تبلیغات تلفن همراه Google استفاده کنید.

استفاده از کیت توسعه نرم‌افزار آگهی‌های طرف سوم

اگر لازم است آگهی‌ها را بااستفاده از کیت توسعه نرم‌افزار آگهی‌های شخص ثالث بار کنید، بهتر است بررسی کنید که آیا ازقبل ادغام ExoPlayer را ارائه می‌دهد یا نه. اگر نه، پیاده‌سازی یک AdsLoader سفارشی که کیت توسعه نرم‌افزار آگهی‌های طرف سوم را دربرمی‌گیرد، رویکرد توصیه‌شده است، زیرا مزایای AdsMediaSource را که قبلاً توضیح داده شد ارائه می‌دهد. ImaAdsLoader به‌عنوان نمونه پیاده‌سازی عمل می‌کند.

یا می‌توانید از پشتیبانی فهرست پخش ExoPlayer برای ساختن توالی آگهی‌ها و کلیپ‌های محتوا استفاده کنید:

کاتلین

// 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)

جاوا

// 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);

درج آگهی سمت سرور

در درج آگهی سمت سرور (که درج آگهی پویا یا DAI نیز نامیده می‌شود)، جاری‌سازی رسانه هم حاوی آگهی و هم حاوی محتوا است. مانیفست DASH ممکن است به هر دو بخش محتوا و آگهی اشاره کند، احتمالاً در دوره‌های زمانی جداگانه. برای HLS، به اسناد Apple درباره گنجاندن آگهی‌ها در فهرست پخش مراجعه کنید.

هنگام استفاده از درج آگهی سمت سرور، ممکن است کارخواه نیاز داشته باشد نشانی وب رسانه را به‌طور پویا حل کند تا جریان به‌هم‌پیوسته را دریافت کند، ممکن است نیاز داشته باشد هم‌پوشانی‌های آگهی را در واسط کاربر نمایش دهد، یا ممکن است نیاز داشته باشد رویدادها را به کیت توسعه نرم‌افزار آگهی یا سرور آگهی گزارش دهد.

DefaultMediaSourceFactory ExoPlayer می‌تواند همه این وظایف را به درج آگهی سمت سرور MediaSource برای URIهایی که از طرح ssai:// استفاده می‌کنند واگذار کند:

کاتلین

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

جاوا

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

کتابخانه ExoPlayer IMA

کتابخانه ExoPlayer IMA ImaServerSideAdInsertionMediaSource را برای ادغام با جریان‌های آگهی درج‌شده در سمت سرور IMA در برنامه شما ارائه می‌دهد. این کتابخانه عملکرد IMA DAI SDK برای Android را دربرمی‌گیرد و فراداده آگهی ارائه‌شده را به‌طور کامل در پخش‌کننده ادغام می‌کند. برای مثال، این کار به شما امکان می‌دهد از روش‌هایی مثل Player.isPlayingAd() استفاده کنید، به انتقال‌های محتوا-آگهی گوش دهید، و به پخش‌کننده اجازه دهید منطق بازپخش آگهی را مدیریت کند، مثلاً آگهی‌هایی را که قبلاً پخش شده‌اند رد کند.

برای استفاده از این کلاس، باید ImaServerSideAdInsertionMediaSource.AdsLoader و ImaServerSideAdInsertionMediaSource.Factory را راه‌اندازی کنید و آن‌ها را به پخش‌کننده متصل کنید:

کاتلین

// 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)

جاوا

// 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 یا شناسه منبع محتوا و شناسه ویدیو را با ساختن نشانی وب با ImaServerSideAdInsertionUriBuilder بار کنید:

کاتلین

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

جاوا

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

درنهایت، وقتی دیگر از بارکننده آگهی استفاده نمی‌شود، آن را آزاد کنید:

کاتلین

adsLoader.release()

جاوا

adsLoader.release();

ملاحظات میانای کاربر

همان ملاحظات واسط کاربر که برای درج آگهی سمت کارخواه وجود دارد، برای درج آگهی سمت سرور نیز اعمال می‌شود.

تبلیغات هم‌نشین

برخی‌از برچسب‌های آگهی حاوی آگهی‌های همپای اضافی هستند که می‌توانند در «جایگاه‌های» واسط کاربر برنامه نشان داده شوند. این جایگاه‌ها را می‌توان بااستفاده از ImaServerSideAdInsertionMediaSource.AdsLoader.Builder.setCompanionAdSlots(slots) منتقل کرد. برای اطلاعات بیشتر، به افزودن آگهی‌های همپا مراجعه کنید.

استفاده از کیت توسعه نرم‌افزار آگهی‌های طرف سوم

اگر لازم است آگهی‌ها را بااستفاده از کیت توسعه نرم‌افزار آگهی‌های شخص ثالث بار کنید، بهتر است بررسی کنید که آیا ازقبل ادغام ExoPlayer را ارائه می‌دهد یا نه. اگر نه، توصیه می‌شود MediaSource سفارشی‌ای ارائه دهید که URI-های دارای طرح ssai:// مشابه ImaServerSideAdInsertionMediaSource را بپذیرد.

منطق واقعی ایجاد ساختار آگهی را می‌توان به ServerSideAdInsertionMediaSource چندمنظوره واگذار کرد که یک جاری‌سازی MediaSource را دربرمی‌گیرد و به کاربر اجازه می‌دهد AdPlaybackState را که نشان‌دهنده فراداده آگهی است تنظیم و به‌روز کند.

اغلب، جاری‌سازی‌های آگهی درج‌شده در سمت سرور حاوی رویدادهای زمان‌بندی‌شده برای اطلاع‌رسانی به پخش‌کننده درباره فراداده آگهی هستند. برای اطلاعات درباره قالب‌های فراداده زمان‌بندی‌شده‌ای که ExoPlayer پشتیبانی می‌کند، به قالب‌های پشتیبانی‌شده مراجعه کنید. پیاده‌سازی‌های سفارشی کیت توسعه نرم‌افزار آگهی MediaSource می‌توانند بااستفاده از Player.Listener.onMetadata، رویدادهای فراداده زمان‌بندی‌شده را از پخش‌کننده دریافت کنند.