设置原生广告的高级功能

请选择平台： Android（Beta 版） Android iOS

原生广告有很多高级功能，让您可进行更多自定义，打造出尽可能出色的广告体验。本指南介绍了如何使用原生广告的高级功能。

前提条件

• 集成原生广告格式。

素材资源控件

本部分详细介绍了如何自定义原生广告中的广告素材资源。您可以选择指定偏好的媒体素材资源宽高比，以及图片素材资源的下载和显示方式。

首选媒体宽高比控件

借助媒体宽高比控件，您可以指定对广告素材宽高比的偏好。

重要提示： 使用此 API 并不保证所有广告素材都会满足指定的偏好设置。

使用 NativeAd.NativeMediaAspectRatio 值调用 NativeAdRequest.Builder.setMediaAspectRatio()。

• 如果未设置此控件，则返回的广告可以采用任意媒体宽高比。

• 如果设置了此控件，您将能够指定首选的宽高比类型来改善用户体验。

以下示例指示 SDK 优先返回采用特定宽高比的图片或视频。

Kotlin

val adRequest = NativeAdRequest.Builder(
  "ca-app-pub-3940256099942544/2247696110",
  listOf(NativeAd.NativeAdType.NATIVE))
  .setMediaAspectRatio(NativeAd.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE)
  .build()

Java

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "ca-app-pub-3940256099942544/2247696110",
  List.of(NativeAd.NativeAdType.NATIVE))
  .setMediaAspectRatio(NativeAd.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE)
  .build();

图片下载控件

借助图片下载控件，您可以决定 SDK 是返回图片素材资源还是仅返回 URI。

调用 NativeAdRequest.Builder.disableImageDownloading()。

• 图片下载控件默认处于停用状态。

• 停用后，GMA Next-Gen SDK 会为您填充图片和 URI。

• 此控件处于启用状态时，SDK 则仅填充 URI，让您可自行决定是否下载实际图片。

以下示例指示 SDK 仅返回 URI。

Kotlin

val adRequest = NativeAdRequest.Builder(
    "ca-app-pub-3940256099942544/2247696110",
    listOf(NativeAd.NativeAdType.NATIVE))
    .setMediaAspectRatio(NativeAd.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE)
    .disableImageDownloading()
    .build()

val adCallback: NativeAdLoaderCallback =
  object : NativeAdLoaderCallback {
    override fun onNativeAdLoaded(nativeAd: NativeAd) {
      // Get the image uri.
      val imageUri = nativeAd.image?.uri
    }
  };

// Load the native ad with the ad request and callback.
NativeAdLoader.load(adRequest, adLoaderCallback);

Java

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "ca-app-pub-3940256099942544/2247696110",
  List.of(NativeAd.NativeAdType.NATIVE))
  .disableImageDownloading()
  .build();

NativeAdLoaderCallback adLoaderCallback =
  new NativeAdLoaderCallback() {
    @Override
    public void onNativeAdLoaded(@NonNull NativeAd nativeAd) {
      // Get the image uri.
      Uri imageUri = nativeAd.getImage().getUri();
    }
  };

// Load the native ad with the ad request and callback.
NativeAdLoader.load(adRequest, adLoaderCallback);

图片载荷控件

有些广告包含一系列图片，而不只是一张图片。使用此功能，可指明您的应用是已准备好展示所有图片，还是只能展示一张图片。

• 图片载荷控件默认处于停用状态。

• 此控件处于停用状态时，您的应用会指示 SDK，对于包含一系列图片的任何素材资源，仅提供第一张图片。

• 此控件处于启用状态时，您的应用会指示其已做好准备，可为包含多张图片的任何素材资源展示所有图片。

以下示例指示 SDK 返回多个图片素材资源。

“广告选项”图标位置

本部分详细介绍了如何确定“广告选项”叠加层的位置。您可以选择将其放置在四个角中的任意一个，也可以在自定义视图中呈现它。

“广告选项”位置控件

借助“广告选项”位置控件，您可以选择在哪个角落呈现“广告选项”图标。

使用 NativeAdRequest.AdChoicesPlacement 值调用 NativeAdRequest.Builder.setAdChoicesPlacement()。

• 如果未设置此控件，“广告选项”图标位置会设置为右上角。

• 如果设置了此控件，“广告选项”图标会放置在所请求的自定义位置。

以下示例演示了如何设置自定义“广告选项”图标位置。

Kotlin

val adRequest = NativeAdRequest.Builder(
  "ca-app-pub-3940256099942544/2247696110",
  listOf(NativeAd.NativeAdType.NATIVE))
  .setAdChoicesPlacement(NativeAdOptions.ADCHOICES_BOTTOM_RIGHT)
  .build()

Java

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "ca-app-pub-3940256099942544/2247696110",
  List.of(NativeAd.NativeAdType.NATIVE))
  .setAdChoicesPlacement(NativeAdOptions.ADCHOICES_BOTTOM_RIGHT)
  .build();

“广告选项”自定义视图

警告：此功能的开放范围有限。如需申请访问权限，请与您的客户经理联系。

借助“广告选项”自定义视图功能，您可以将“广告选项”图标放置在自定义位置。这与“广告选项”位置控件不同，后者仅允许指定放置在四个角之一。

使用 AdChoicesView 值调用 NativeAdView.setAdChoicesView()。

以下示例演示了如何设置自定义“广告选项”视图，其中“广告选项”图标显示在 AdChoicesView 内。

Kotlin

override fun onNativeAdLoaded(nativeAd: NativeAd) {
  val nativeAdView = NativeAdView(applicationContext)
  val adChoicesView = AdChoicesView(this)
  nativeAdView.adChoicesView = adChoicesView
}

Java

public void onNativeAdLoaded(@NonNull NativeAd nativeAd) {
  NativeAdView nativeAdView = new NativeAdView(getApplicationContext());
  AdChoicesView adChoicesView = new AdChoicesView(this);
  nativeAdView.setAdChoicesView(adChoicesView);
}

视频控件

本部分详细介绍了如何自定义视频广告的播放体验。您可以选择设置初始静音状态并实现自定义播放控件。

开始播放时静音

借助“开始播放时静音”选项，您可以指定在开始播放视频时停用或启用音频。

使用 boolean 值调用 VideoOptions.Builder.setStartMuted()，并调用 NativeAdOptions.Builder.setVideoOptions()。

• “开始播放时静音”选项默认处于启用状态。

• 此选项处于停用状态时，您的应用会请求视频在开始播放时也播放音频。

• 此选项处于启用状态时，您的应用会请求视频在开始播放时静音。

以下示例展示了如何在开始播放视频时取消静音。

Kotlin

val videoOptions = VideoOptions.Builder()
  .setStartMuted(false)
  .build()

val adRequest = NativeAdRequest.Builder(
  "ca-app-pub-3940256099942544/2247696110",
  listOf(NativeAd.NativeAdType.NATIVE))
  .setVideoOptions(videoOptions)
  .build()

Java

VideoOptions videoOptions = VideoOptions.Builder()
  .setStartMuted(false)
  .build()

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "ca-app-pub-3940256099942544/2247696110",
  List.of(NativeAd.NativeAdType.NATIVE))
  .setVideoOptions(videoOptions)
  .build()

自定义播放控件

警告：此功能的开放范围有限。如需申请访问权限，请与您的客户经理联系。

借助此功能，您可以请求自定义视频输入控件播放、暂停视频或将其静音。

如需设置广告开始时的静音状态，请调用 VideoOptions.Builder.setCustomControlsRequested()。

• 自定义播放控件默认处于停用状态。

• 此控件处于停用状态时，您的视频将显示由 SDK 呈现的输入控件。

如果广告确实包含视频内容，并且已启用自定义控件，那么您应在展示广告的同时显示自定义控件，因为广告本身不会显示任何控件。这样，控件就可以调用

VideoOptions.Builder.setCustomControlsRequested()。

以下示例展示了如何请求包含自定义播放控件的视频。

Kotlin

val videoOptions: VideoOptions.Builder()
  .setCustomControlsRequested(true)
  .build()

val adRequest = new NativeAdRequest.Builder(
  "ca-app-pub-3940256099942544/2247696110",
  listOf(NativeAd.NativeAdType.NATIVE))
  .setVideoOptions(videoOptions)
  .build()

Java

VideoOptions VideoOptions = VideoOptions.Builder()
  .setCustomControlsRequested(true)
  .build()

NativeAdRequest adRequest = new NativeAdRequest.Builder(
  "ca-app-pub-3940256099942544/2247696110",
  List.of(NativeAd.NativeAdType.NATIVE))
  .setVideoOptions(videoOptions)
  .build()

检查是否已启用自定义控件

由于在请求时无法知道返回的广告是否允许使用自定义视频控件，因此您必须检查它是否已启用自定义控件。

Kotlin

  val adCallback: NativeAdLoaderCallback =
    object : NativeAdLoaderCallback {
      override fun onNativeAdLoaded(nativeAd: NativeAd) {
        val mediaContent = nativeAd.mediaContent;
        if (mediaContent != null) {
          val videoController = mediaContent.videoController;
          val canShowCustomControls = videoController?.isCustomControlsEnabled();
        }
      }
    };

Java

NativeAdLoaderCallback adCallback =
  new NativeAdLoaderCallback() {
    @Override
    public void onNativeAdLoaded(@NonNull NativeAd nativeAd) {
      MediaContent mediaContent = nativeAd.getMediaContent();
      if (mediaContent != null) {
        VideoController videoController = mediaContent.getVideoController();
        if (videoController != null) {
          boolean canShowCustomControls = videoController.isCustomControlsEnabled();
        }
      }
    }
  };

呈现自定义视频控件

按照以下最佳实践呈现自定义视频控件：

1. 将自定义控件视图作为原生广告视图的子视图呈现。采用这种做法后，按照开放式衡量标准计算可见度时，会将自定义控件视为一种友好遮挡。
2. 避免在整个媒体视图上呈现不可见的叠加层。叠加层会妨碍媒体视图上的点击，从而对原生广告效果产生负面影响。请改为创建一个仅够容纳控件的小叠加层。

注意： 如需了解已承诺制定开放式衡量可见度标准的衡量和验证服务提供商，请参阅开放式衡量工作组。