插入广告

ExoPlayer 既可用于客户端广告插播，也可用于服务器端广告插播。

客户端广告插播

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

使用 ExoPlayer 的 AdsMediaSource 进行客户端广告植入时，播放器会获取要播放的广告的相关信息。这样做有几个好处：

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

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

在准备内容视频和广告代码以用于客户端广告插播时，广告最好位于内容视频中的同步样本（关键帧）处，以便播放器可以无缝恢复内容播放。

声明式广告支持

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

Kotlin

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

Java

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

如需为指定广告代码的媒体文件启用播放器支持，必须在创建播放器时构建并注入配置了 AdsLoader.Provider 和 AdViewProvider 的 DefaultMediaSourceFactory：

Kotlin

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

Java

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

在内部，DefaultMediaSourceFactory 会将内容媒体来源封装在 AdsMediaSource 中。AdsMediaSource 将从 AdsLoader.Provider 获取 AdsLoader，并使用它来插入媒体文件的广告代码所定义的广告。

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

包含广告的播放列表

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

您可以通过传递不透明的广告标识符来自定义此行为，该标识符会根据对象相等性与给定媒体文件的广告播放状态相关联。在以下示例中，通过将广告代码 URI 作为广告标识符传递，广告播放状态仅与广告代码 URI 相关联，而不是与媒体 ID 和广告代码 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)
AdInsertion.kt

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);
AdInsertion.java

服务器引导的客户端广告插播

ExoPlayer 附带 HlsInterstitialsAdsLoader，支持在客户端自动插入 HLS 播放列表中定义的广告。请参阅 HLS 页面上关于 HlsInterstitialsAdsLoader 的部分。

ExoPlayer IMA 库

ExoPlayer IMA 库提供 ImaAdsLoader，用于将客户端广告植入集成到您的应用中。它封装了客户端 IMA SDK 的功能，以支持植入 VAST/VMAP 广告。如需了解如何使用该库（包括如何处理后台播放和恢复播放），请参阅自述文件。

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

重要提示： 为了缩短 IMA 加载时间，请在应用生命周期中尽早调用 ImaSdkFactory.initialize() 方法。尽早调用该方法可最大限度地延长 IMA 在发出第一个广告请求之前加载必要资源的时间。ImaSdkFactory.initialize() 方法调用接受 ImaSdkSettings 实例。请确保在此处以及创建 ImaAdsLoader 实例时使用相同的设置值。如需了解详情，请参阅优化 IMA 加载时间指南。

界面注意事项

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

注意 ：由于广告客户希望在各种应用中获得一致的体验，因此 IMA SDK 不允许自定义广告播放时显示的视图。因此，您无法移除或重新定位跳过按钮、更改字体或对这些视图的外观进行其他自定义。

IMA SDK 可能会报告广告是否被应用提供的在播放器顶部呈现的视图遮挡。如果应用需要叠加对控制播放至关重要的视图，则必须向 IMA SDK 注册这些视图，以便在可见度计算中忽略它们。使用 PlayerView 作为 AdViewProvider 时，它会自动注册其控件叠加层。使用自定义播放器界面的应用必须通过从 AdViewProvider.getAdOverlayInfos 返回叠加视图来注册这些视图。

如需详细了解叠加视图，请参阅 IMA SDK 中的 Open Measurement。

随播广告

某些广告代码包含可在应用界面中的“广告位”内展示的其他随播广告。这些槽可以使用 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(
      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)
AdInsertion.kt

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);
AdInsertion.java

服务器端广告插播

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

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

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

Kotlin

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

Java

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

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)
AdInsertion.kt

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);
AdInsertion.java

通过使用 ImaServerSideAdInsertionUriBuilder 构建网址，加载 IMA 素材资源密钥或内容来源 ID 和视频 ID：

Kotlin

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

Java

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

最后，在不再使用广告加载器时将其释放：

Kotlin

adsLoader.release()
AdInsertion.kt

Java

adsLoader.release();
AdInsertion.java

注意： 目前，同一播放列表中仅支持单个 IMA 服务器端广告插播视频流。您可以将该视频流与其他媒体结合使用，但不能与其他 IMA 服务器端广告插播视频流结合使用。

界面注意事项

与客户端广告植入相同的界面注意事项也适用于服务器端广告植入。

随播广告

某些广告代码包含可在应用界面中的“广告位”内展示的其他随播广告。这些槽可以使用 ImaServerSideAdInsertionMediaSource.AdsLoader.Builder.setCompanionAdSlots(slots) 传递。 如需了解详情，请参阅添加随播广告。

使用第三方广告 SDK

如果您需要使用第三方广告 SDK 加载广告，不妨检查一下它是否已提供 ExoPlayer 集成。否则，建议提供一个自定义 MediaSource，用于接受具有类似于 ImaServerSideAdInsertionMediaSource 的 ssai:// 架构的 URI。

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

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