此页面由 Cloud Translation API 翻译。

原生广告选项

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

前提条件

集成原生广告格式。

素材资源控件

首选媒体宽高比控件

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

使用 NativeAdOptions.MediaAspectRatio 值调用 NativeAdOptions.Builder.setMediaAspectRatio()。

如果未设置，则返回的广告可以采用任何媒体宽高比。
设置后，您可以通过指定首选宽高比类型来改善用户体验。

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

NativeAdOptions nativeAdOptions = new NativeAdOptions.Builder()
                              .setMediaAspectRatio(NativeAdOptions.NATIVE_MEDIA_ASPECT_RATIO_LANDSCAPE)
                              .build();

AdLoader loader = new AdLoader.Builder(this, 'ca-app-pub-3940256099942544/2247696110')
                              .withNativeAdOptions(nativeAdOptions)
                              .build();

图片下载控件

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

使用 boolean 值调用 NativeAdOptions.Builder.setReturnUrlsForImageAssets()。

图片下载控件默认处于停用状态。
停用后，Google 移动广告 SDK 会为您填充图片和 URI。
启用后，SDK 会仅填充 URI，从而允许您自行决定是否下载实际图片。

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

NativeAdOptions nativeAdOptions = new NativeAdOptions.Builder()
                                                     .setReturnUrlsForImageAssets(true)
                                                     .build();

AdLoader loader = new AdLoader.Builder(this, 'ca-app-pub-3940256099942544/2247696110')
                              .withNativeAdOptions(nativeAdOptions)
                              .forNativeAd(nativeAd -> {
                                List<Uri> imageUris = new ArrayList<>();
                                for (Image image : nativeAd.getImages()) {
                                  imageUris.add(image.getUri());
                                }
                              })
                              .build();

图片载荷控件

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

使用 boolean 值调用 NativeAdOptions.Builder.setRequestMultipleImages()。

图片载荷控件默认处于停用状态。
停用后，您的应用会指示 SDK 仅为包含一系列图片的任何素材资源提供第一张图片。
启用后，您的应用会指明它已做好准备，可以为任何包含多张图片的素材资源展示所有图片。

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

NativeAdOptions nativeAdOptions = new NativeAdOptions.Builder()
                                                     .setRequestMultipleImages(true)
                                                     .build();

AdLoader loader = new AdLoader.Builder(this, 'ca-app-pub-3940256099942544/2247696110')
                              .withNativeAdOptions(nativeAdOptions)
                              .build();

“广告选择”展示位置

AdChoices 位置控件

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

使用 NativeAdOption.AdChoicesPlacement 值调用 NativeAdOptions.Builder.setAdChoicesPlacement()。

如果未设置，则“广告选择”图标位置会设为右上角。
如果设置了此属性，AdChoices 会根据请求放置在自定义位置。

以下示例演示了如何设置自定义 AdChoices 图片位置。

NativeAdOptions nativeAdOptions = new NativeAdOptions.Builder()
                                                     .setAdChoicesPlacement(NativeAdOptions.ADCHOICES_BOTTOM_RIGHT)
                                                     .build();

AdLoader loader = new AdLoader.Builder(this, 'ca-app-pub-3940256099942544/2247696110')
                              .withNativeAdOptions(nativeAdOptions)
                              .build();

AdChoices 自定义视图

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

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

以下示例演示了如何设置自定义 AdChoices 视图，并在 AdChoicesView 中呈现 AdChoices 图标。


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

视频控件

开始静音行为

借助“开始静音”行为，您可以停用或启用视频的开始音频。

使用 boolean 值调用 VideoOptions.Builder.setStartMuted()。

默认情况下，系统会启用开始静音行为。
停用后，您的应用会请求视频应以音频开始。
启用此功能后，您的应用会请求视频在开始时静音播放。

以下示例展示了如何在未静音的情况下启动视频。

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

NativeAdOptions adOptions = new NativeAdOptions.Builder()
                                               .setVideoOptions(videoOptions)
                                               .build();

AdLoader loader = new AdLoader.Builder(this, 'ca-app-pub-3940256099942544/2247696110')
                              .withNativeAdOptions(adOptions).build();

自定义播放控件

这样，您就可以请求自定义视频输入控件来播放、暂停或静音视频。

使用 boolean 值调用 VideoOptions.Builder.setCustomControlsRequested()。

自定义播放控件默认处于停用状态。
停用后，您的视频将显示 SDK 呈现的输入控件。

如果广告包含视频内容且已启用自定义控件，那么您应随广告一起显示自定义控件，因为广告本身不会显示任何控件。然后，控件可以对 VideoController 调用相关方法。

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

VideoOptions videoOptions = new VideoOptions.Builder()
                                            .setCustomControlsRequested(true)
                                            .build();

NativeAdOptions adOptions = new NativeAdOptions.Builder()
                                               .setVideoOptions(videoOptions)
                                               .build();

AdLoader loader = new AdLoader.Builder(this, 'ca-app-pub-3940256099942544/2247696110')
                              .withNativeAdOptions(adOptions).build();

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

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

Java

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

Kotlin

NativeAd.OnNativeAdLoadedListener { ad ->
  val mediaContent = ad.mediaContent
  if (mediaContent != null) {
    val videoController = mediaContent.videoController
    val canShowCustomControls = videoController.isCustomControlsEnabled
  }
}

呈现自定义视频控件

请遵循以下最佳实践来呈现自定义视频控件：

将自定义控件视图呈现为原生广告视图的子视图。这种方法可确保 Open Measurement 可见度计算将自定义控件视为友好遮挡。
避免在整个媒体视图上渲染不可见的叠加层。叠加层会阻止用户点击媒体视图，从而对原生广告的效果产生不利影响。而是创建一个大小刚好足以容纳控件的较小叠加层。

自定义点击手势

自定义点击手势是一项原生广告功能，可将广告视图上的滑动操作注册为广告点击。它专为与使用滑动手势进行内容导航的应用搭配使用而设计。本指南介绍了如何在原生广告中启用自定义点击手势。

使用 NativeAdOptions.SwipeGestureDirection 和 boolean 调用 NativeAdOptions.Builder.enableCustomClickGestureDirection()，以指明是否允许将点按视为点击。

自定义点击手势默认处于停用状态。
停用后，您的应用将支持正常的点击行为。
启用后，您的应用将支持自定义滑动手势。

以下示例实现了向右的自定义滑动手势，并保留了正常的标签页行为。

NativeAdOptions adOptions = new NativeAdOptions
    .Builder()
    .enableCustomClickGestureDirection(NativeAdOptions.SWIPE_GESTURE_DIRECTION_RIGHT,
            /* tapsAllowed= */ true)
    .build();

// The following sample ad unit ID has been enabled for custom click gestures
// and can be used for testing.
AdLoader.Builder builder = new AdLoader
    .Builder(this, 'ca-app-pub-3940256099942544/2247696110')
    .withNativeAdOptions(adOptions);

监听滑动手势事件

记录滑动手势点击时，除了现有的 onAdClicked() 方法之外，Google 移动广告 SDK 还会在 AdListener 上调用 onAdSwipeGestureClicked() 方法。

AdLoader adLoader = builder
    .withAdListener(
      new AdListener() {
        // Called when a swipe gesture click is recorded.
        @Override
        public void onAdSwipeGestureClicked() {
          Log.d(TAG, "A swipe gesture click has occurred.")
        }

        // Called when a swipe gesture click or a tap click is recorded, as
        // configured in NativeAdOptions.
        @Override
        public void onAdClicked() {
          Log.d(TAG, "A swipe gesture click or a tap click has occurred.")
        }
      })
    .build();

中介

自定义点击手势仅适用于 Google 移动广告 SDK 呈现的原生广告。需要使用第三方 SDK 进行呈现的广告来源不会响应自定义点击方向设置。