广告插入

ExoPlayer 可用于客户端和服务器端广告插入。

客户端广告插入

在客户端广告插入中，播放器会在播放内容和广告之间切换时，从不同的 URL 加载媒体。广告信息独立于媒体加载，例如从 XML VAST 或 VMAP 广告代码加载。这可以包括相对于内容开头的广告提示位置、实际广告媒体 URI 以及广告是否可跳过的元数据。

在客户端广告插入中使用 ExoPlayer 的 AdsMediaSource 时，播放器会获取要播放的广告的信息。这有几个好处

  • 播放器可以使用其 API 公开与广告相关的元数据和功能。
  • ExoPlayer UI 组件可以自动显示广告位置标记，并根据广告是否正在播放来改变其行为。
  • 在内部，播放器可以在广告和内容之间的切换过程中保持一致的缓冲区。

在此设置中，播放器负责在广告和内容之间进行切换，这意味着应用无需管理用于广告和内容的多个单独的后台/前台播放器。

在准备用于客户端广告插入的内容视频和广告代码时，理想情况下，广告应放置在内容视频中的同步样本（关键帧）处，以便播放器可以无缝恢复内容播放。

声明式广告支持

构建 MediaItem 时可以指定广告代码 URI

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

为使播放器支持指定广告代码的媒体项目，在创建播放器时，需要构建并注入一个配置有 AdsLoader.Provider 和 AdViewProvider 的 DefaultMediaSourceFactory。

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.Provider 获取 AdsLoader，并使用它来插入媒体项目广告代码定义的广告。

ExoPlayer 的 PlayerView 实现了 AdViewProvider。ExoPlayer IMA 库提供了一个易于使用的 AdsLoader，如下所述。

带广告的播放列表

播放包含多个媒体项目的播放列表时，默认行为是为每个媒体 ID、内容 URI 和广告代码 URI 组合请求广告代码并存储一次广告播放状态。这意味着用户将看到具有不同媒体 ID 或内容 URI 的每个带广告的媒体项目的广告，即使广告代码 URI 匹配。如果媒体项目重复，用户将仅看到一次相应的广告（广告播放状态会存储广告是否已播放，因此在首次出现后会跳过）。

可以通过传递不透明的广告标识符来自定义此行为，给定媒体项目的广告播放状态会根据对象相等性与其关联。以下是一个示例，其中广告播放状态仅与广告代码 URI 关联，而不是媒体 ID 和广告代码 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 播放列表中定义的广告插入到客户端。请参阅HLS 页面上关于 HlsInterstitialsAdsLoader 的部分。

ExoPlayer IMA 库

ExoPlayer IMA 库提供了 ImaAdsLoader，可以轻松地将客户端广告插入集成到您的应用中。它封装了客户端 IMA SDK 的功能，以支持 VAST/VMAP 广告的插入。有关如何使用该库的说明，包括如何处理后台运行和恢复播放，请参阅 README。

演示应用使用 IMA 库，并在示例列表中包含多个 VAST/VMAP 广告代码示例。

UI 考虑事项

默认情况下，PlayerView 会在广告播放期间隐藏其传输控件，但应用可以通过调用 setControllerHideDuringAds 来切换此行为。IMA SDK 会在广告播放时在播放器顶部显示额外的视图（例如，“更多信息”链接和跳过按钮，如果适用）。

IMA SDK 可能会报告广告是否被应用提供的在播放器顶部渲染的视图遮挡。需要叠加对控制播放至关重要的视图的应用必须将其注册到 IMA SDK，以便将其从可见性计算中省略。PlayerView 用作 AdViewProvider 时，它将自动注册其控制叠加层。使用自定义播放器 UI 的应用必须通过从 AdViewProvider.getAdOverlayInfos 返回叠加视图来注册它们。

有关叠加视图的更多信息，请参阅 IMA SDK 中的 Open Measurement。

伴随广告

某些广告代码包含可以显示在应用 UI“槽位”中的其他伴随广告。这些槽位可以通过 ImaAdsLoader.Builder.setCompanionAdSlots(slots) 传递。有关更多信息，请参阅添加伴随广告。

独立广告

IMA SDK 旨在将广告插入媒体内容中，而不是单独播放独立广告。因此，IMA 库不支持独立广告的播放。我们建议为此用例改用Google 移动广告 SDK。

使用第三方广告 SDK

如果您需要通过第三方广告 SDK 加载广告，值得检查它是否已提供 ExoPlayer 集成。如果没有，建议实现一个包装第三方广告 SDK 的自定义 AdsLoader，因为它提供了上述 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);

服务器端广告插入

在服务器端广告插入（也称为动态广告插入或 DAI）中，媒体流包含广告和内容。DASH 清单可以指向内容和广告片段，可能在不同的时段。对于 HLS，请参阅 Apple 关于将广告合并到播放列表的文档。

使用服务器端广告插入时，客户端可能需要动态解析媒体 URL 以获取拼接流，可能需要在 UI 中显示广告叠加层，或者可能需要向广告 SDK 或广告服务器报告事件。

ExoPlayer 的 DefaultMediaSourceFactory 可以将所有这些任务委托给使用 ssai:// 方案的 URI 的服务器端广告插入 MediaSource。

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 的服务器端插入广告流集成到您的应用中。它封装了适用于 Android 的 IMA DAI SDK 的功能，并将提供的广告元数据完全集成到播放器中。例如，这允许您使用 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);

通过使用 ImaServerSideAdInsertionUriBuilder 构建 URL 来加载您的 IMA 资产密钥，或内容源 ID 和视频 ID。

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

UI 考虑事项

与客户端广告插入相同的 UI 考虑事项也适用于服务器端广告插入。

伴随广告

某些广告代码包含可以显示在应用 UI“槽位”中的其他伴随广告。这些槽位可以通过 ImaServerSideAdInsertionMediaSource.AdsLoader.Builder.setCompanionAdSlots(slots) 传递。有关更多信息，请参阅添加伴随广告。

使用第三方广告 SDK

如果您需要使用第三方广告 SDK 加载广告，值得检查它是否已提供 ExoPlayer 集成。如果没有，建议提供一个自定义的 MediaSource，它接受与 ImaServerSideAdInsertionMediaSource 类似的 ssai:// 方案的 URI。

创建广告结构的实际逻辑可以委托给通用 ServerSideAdInsertionMediaSource，它封装了一个流 MediaSource 并允许用户设置和更新表示广告元数据的 AdPlaybackState。

通常，服务器端插入的广告流包含定时事件，用于通知播放器广告元数据。请参阅支持的格式，了解 ExoPlayer 支持的定时元数据格式。自定义广告 SDK MediaSource 实现可以使用 Player.Listener.onMetadata 监听来自播放器的定时元数据事件。