درج آگهی

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

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

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

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

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

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

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

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

هنگام ساختن 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 را به‌آسانی دراختیار قرار می‌دهد.

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

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

می‌توانید این رفتار را با ارسال شناسه آگهی مبهمی که وضعیت بازپخش آگهی برای یک عنصر رسانه‌ای معین براساس برابری شیء به آن پیوند داده شده است سفارشی‌سازی کنید. در اینجا مثالی آورده شده است که در آن وضعیت بازپخش آگهی فقط به نشانی وب برچسب آگهی پیوند داده شده است، نه به ترکیب شناسه رسانه و نشانی وب برچسب آگهی، با ارسال نشانی وب برچسب آگهی به‌عنوان شناسه آگهی. تأثیر این کار این است که آگهی‌ها فقط یک‌بار بارگیری می‌شوند و کاربر هنگام پخش فهرست پخش از ابتدا تا انتها، آگهی‌ها را در مورد دوم نمی‌بیند.

کاتلین

// 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» نمای‌های اضافی را در بالای پخش‌کننده درحین پخش آگهی نشان می‌دهد (برای مثال، پیوند «اطلاعات بیشتر» و دکمه رد کردن، درصورت وجود).

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

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

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

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

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

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

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

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

کاتلین

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 سفارشی‌ای ارائه دهید که نشانی‌های وب را با طرح ssai:// مشابه ImaServerSideAdInsertionMediaSource بپذیرد.

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

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