目录

原生广告是创建与应用内容融于一体的广告形式，支持开发者自由定制界面。

1. 添加原生广告

原生广告需要通过NativeAdLoader类获取。

步骤一：构建AdLoader

NativeAdLoader类提供了NativeAdLoader.Builder类，可用于设置广告位ID、设置自定义选项和构建NativeAdLoader对象。

示例代码如下所示：

  1. // "testy63txaom86"为专用的测试广告位ID。
  2. NativeAdLoader.Builder builder = new NativeAdLoader.Builder(this, "testy63txaom86");
  3. builder.setNativeAdLoadedListener(new NativeAd.NativeAdLoadedListener() {
  4.     @Override
  5.     public void onNativeAdLoaded(NativeAd nativeAd) {
  6.         // 广告获取完成后调用
  7.         ...
  8.     }
  9. }).setAdListener(new AdListener() {
  10.     @Override
  11.     public void onAdFailed(int errorCode) {
  12.         // 广告获取失败时调用
  13.         ...
  14.     }
  15. });

  17. NativeAdLoader nativeAdLoader = builder.build();

当获取广告成功后，SDK会调用NativeAd.NativeAdLoadedListener监听器的onNativeAdLoaded()方法返回NativeAd对象。

当获取广告失败后，SDK会调用AdListener监听器的onAdFailed()方法。

步骤二：获取广告

NativeAdLoader提供loadAd()和loadAds()两种方法获取广告。

AdParam是唯一的参数，代码如下所示：

  1. nativeAdLoader.loadAd(new AdParam.Builder().build());

调用loadAd()后，SDK将对添加的监听器方法进行一次成功或失败的回调。

loadAds()请求有两个参数，除AdParam外，还有请求加载的广告数量，最大为5。SDK返回的广告数量将会小于等于所请求的广告数量，并且广告皆不相同。

代码如下所示：

  1. nativeAdLoader.loadAds(new AdParam.Builder().build(), 5);

调用loadAds()后，监听器将会根据返回的广告个数进行多次回调。请求多个广告时，可以在回调代码中使用NativeAdLoader.isLoading()方法来判断广告是否已获取完成。代码如下所示：

  1. // "testy63txaom86"为专用的测试广告位ID。
  2. NativeAdLoader.Builder builder = new NativeAdLoader.Builder(this, "testy63txaom86");
  3. NativeAdLoader nativeAdLoader = builder.setNativeAdLoadedListener(new NativeAd.NativeAdLoadedListener() {
  4.     @Override
  5.     public void onNativeAdLoaded(NativeAd nativeAd) {
  6.         if (nativeAdLoader.isLoading()) {
  7.             // nativeAdLoader仍在获取广告
  8.             ...
  9.         } else {
  10.             // nativeAdLoader完成广告获取
  11.             ...
  12.         }
  13.     }
  14. }).build();
  15. nativeAdLoader.loadAds(new AdParam.Builder().build(), 5);
注意：
再次使用NativeAdLoader获取广告前，请确保先前的请求已经完成。

步骤三：展示原生广告

获取到广告后在监听器的回调方法中展示原生广告，需要在每个广告视图的一角展示“为什么看到此广告”的图标，并且必须展示广告标识。

以下是展示原生广告的步骤：

    1. 定义原生广告布局

需要自定义一个布局用于展示NativeAd中的素材。

注意：
必须将NativeView作为原生广告的根布局，否则会影响广告收益。

对于使用RelativeLayout来展示素材视图的原生广告，其视图层次结构示例如下：

  1. <com.huawei.hms.ads.nativead.NativeView xmlns:android="http://schemas.android.com/apk/res/android"
  2.     android:orientation="vertical"
  3.     android:layout_width="match_parent"
  4.     android:layout_height="wrap_content"
  5.     ... >
  6.     <RelativeLayout
  7.         ... >
  8.         <com.huawei.hms.ads.nativead.MediaView
  9.             android:id="@+id/ad_media"
  10.             ... />
  11.         <RelativeLayout
  12.             ... >
  13.         <TextView
  14.             android:id="@+id/ad_title"
  15.             ...  />
  16.         // 其他素材
  17.         ...
  18.         </RelativeLayout>
  19.         // 其他素材
  20.         ...
  21.     </RelativeLayout>
  22. </com.huawei.hms.ads.nativead.NativeView>

    2. 注册和填充素材视图

获取到NativeView对象后，需要注册和填充素材。

注册和填充标题、多媒体的示例代码如下：

  1. // ad_native为定义的原生广告布局XML文件名
  2. NativeView nativeView = (NativeView) getLayoutInflater().inflate(R.layout.ad_native, null);
  3. nativeView.setTitleView(nativeView.findViewById(R.id.ad_title));
  4. ((TextView) nativeView.getTitleView()).setText(nativeAd.getTitle());
  5. nativeView.setMediaView((MediaView) nativeView.findViewById(R.id.ad_media));
  6. nativeView.getMediaView().setMediaContent(nativeAd.getMediaContent());

依次设置其他要展示的广告素材。

MediaView用于展示多媒体素材。如果获取的广告含有视频素材，则视频会在MediaView内播放。否则MediaView会显示一个图片素材。

    3. 向NativeView注册原生广告对象

示例代码如下：

  1. nativeView.setNativeAd(nativeAd);

    4. 展示NativeView

将NativeView添加到界面即可展示原生广告。示例代码如下：

  1. private void loadAd() {
  2.     NativeAdLoader.Builder builder = new NativeAdLoader.Builder(this, "testy63txaom86");
  3.     builder.setNativeAdLoadedListener(new NativeAd.NativeAdLoadedListener() {
  4.         @Override
  5.         public void onNativeAdLoaded(NativeAd nativeAd) {
  6.             // TODO
  7.             ...
  8.             // 获取NativeView视图
  9.             NativeView nativeView = (NativeView) getLayoutInflater().inflate(R.layout.ad_native, null);
  10.             // 注册和填充原生广告素材视图
  11.             initNativeAdView(nativeAd, nativeView);
  12.             // 将NativeView添加到界面
  13.             FrameLayout adFrameLayout = findViewById(R.id.frame_layout_ad);
  14.             adFrameLayout.removeAllViews();
  15.             adFrameLayout.addView(nativeView);
  16.             // TODO
  17.             ...
  18.         }
  19.     });
  20.     ...
  21. }
  22. private void initNativeView(NativeAd nativeAd, NativeView nativeView) {
  23.     // 注册和填充标题素材视图
  24.     nativeView.setTitleView(nativeView.findViewById(R.id.ad_title));
  25.     ((TextView) nativeView.getTitleView()).setText(nativeAd.getTitle());
  26.     // 注册和填充多媒体素材视图
  27.     nativeView.setMediaView((MediaView) nativeView.findViewById(R.id.ad_media));
  28.     nativeView.getMediaView().setMediaContent(nativeAd.getMediaContent());
  29.     // 注册和填充其他素材视图
  30.     ...
  31.     // 注册原生广告对象
  32.     nativeView.setNativeAd(nativeAd);
  33. }

步骤四：监听广告事件（可选）

为原生广告添加事件监听器的示例代码如下：

  1. NativeAdLoader nativeAdLoader = builder.setAdListener(new AdListener() {
  2.     @Override
  3.     public void onAdClicked() {
  4.         // TODO
  5.         ...
  6.     }
  7.     ...
  8. }).build();

2. 销毁广告

当原生广告不再展示时，应将其销毁。

  1. nativeAd.destroy();

3. 原生视频广告

原生广告除了包含图片、文字外，还可能会包含视频素材。HUAWEI Ads SDK还提供了以下两个类用于视频的配置和控制。

通过VideoConfiguration类，可以对原生视频进行相关配置。示例代码如下：

  1. // "testy63txaom86"为专用的测试广告位ID。
  2. NativeAdLoader.Builder builder = new NativeAdLoader.Builder(this, "testy63txaom86");
  3. VideoConfiguration videoConfiguration = new VideoConfiguration.Builder()
  4.         // 设置是否在静音状态下开始播放视频素材。其默认值为true。
  5.         .setStartMuted(true)
  6.         .build();
  7. NativeAdConfiguration adConfiguration = new NativeAdConfiguration.Builder()
  8.         .setVideoConfiguration(videoConfiguration)
  9.         .build();
  10. builder.setNativeAdOptions(adConfiguration);

VideoOperator类用于视频信息获取和视频控制。控制器实例需要通过调用NativeAd.getVideoOperator()方法获得。当广告中没有视频素材时，此方法也会返回VideoOperator对象。

  1. VideoOperator videoOperator = nativeAd.getVideoOperator();

VideoOperator提供hasVideo()方法判断广告中是否有视频素材。

通过实现VideoOperator.VideoLifecycleListener类可以监听视频播放过程中的事件。

  1. videoOperator.setVideoLifecycleListener(new VideoOperator.VideoLifecycleListener() {
  2.     @Override
  3.     public void onVideoEnd() {
  4.         // TODO
  5.         ...
  6.         super.onVideoEnd();
  7.     }
  8. });

4. 原生广告模板

为了方便开发者可以快速实现原生广告的展示，我们提供了一套原生广告模板，可以集成到应用中使用。

原生广告模板提供了两种尺寸，并且都会按比例缩放以适应其父视图的宽度，你也可以随意改变模板的布局或样式。

展示形式如下图所示：

布局XML文件内容如下：

  1. <com.huawei.hms.ads.nativead.NativeView xmlns:android="http://schemas.android.com/apk/res/android"
  2.     android:id="@+id/native_small_view"
  3.     android:layout_width="match_parent"
  4.     android:layout_height="wrap_content"
  5.     android:layout_centerInParent="true"
  6.     android:layout_marginTop="10dp"
  7.     android:background="#FFFFFF"
  8.     android:orientation="vertical">
  9.     <RelativeLayout
  10.         android:id="@+id/background"
  11.         android:layout_width="match_parent"
  12.         android:layout_height="wrap_content"
  13.         android:layout_alignParentTop="true"
  14.         android:orientation="vertical">
  15.         <com.huawei.hms.ads.nativead.MediaView
  16.             android:id="@+id/ad_media"
  17.             android:layout_width="75dp"
  18.             android:layout_height="50dp"
  19.             android:layout_marginStart="24dp"
  20.             android:layout_marginTop="8dp"
  21.             android:layout_marginBottom="8dp"
  22.             android:background="#8BC34A" />
  23.         <RelativeLayout
  24.             android:id="@+id/center_view"
  25.             android:layout_width="wrap_content"
  26.             android:layout_height="wrap_content"
  27.             android:layout_marginStart="107dp"
  28.             android:layout_marginTop="8dp"
  29.             android:layout_marginEnd="48dp"
  30.             android:layout_marginBottom="8dp"
  31.             android:background="#FFFFFF">
  32.             <TextView
  33.                 android:id="@+id/ad_title"
  34.                 android:layout_width="match_parent"
  35.                 android:layout_height="34dp"
  36.                 android:layout_marginBottom="16dp"
  37.                 android:alpha="1"
  38.                 android:textColor="#000000"
  39.                 android:textSize="@dimen/hiad_text_13_sp" />
  40.             <TextView
  41.                 android:id="@+id/ad_source"
  42.                 android:layout_width="wrap_content"
  43.                 android:layout_height="14dp"
  44.                 android:layout_marginTop="36dp"
  45.                 android:alpha="0.6"
  46.                 android:maxWidth="132dp"
  47.                 android:textColor="#666666"
  48.                 android:textSize="@dimen/hiad_text_9_sp" />
  49.             <TextView
  50.                 android:id="@+id/ad_flag"
  51.                 android:layout_width="16dp"
  52.                 android:layout_height="14dp"
  53.                 android:layout_marginStart="8dp"
  54.                 android:layout_marginTop="36dp"
  55.                 android:layout_toEndOf="@+id/ad_source"
  56.                 android:background="@drawable/native_flag_rounded_corners_shape"
  57.                 android:gravity="center"
  58.                 android:text="@string/ad_flag"
  59.                 android:textColor="#FFFFFF"
  60.                 android:textSize="8sp"
  61.                 android:textStyle="bold" />
  62.             <Button
  63.                 android:id="@+id/ad_call_to_action"
  64.                 android:layout_width="44dp"
  65.                 android:layout_height="@dimen/hiad_16_dp"
  66.                 android:layout_alignParentEnd="true"
  67.                 android:layout_marginTop="34dp"
  68.                 android:background="@drawable/native_button_rounded_corners_shape"
  69.                 android:textColor="#FFFFFF"
  70.                 android:textSize="6sp" />
  71.         </RelativeLayout>
  72.     </RelativeLayout>
  73. </com.huawei.hms.ads.nativead.NativeView>

展示形式如下图所示：

布局XML文件内容如下：

  1. <com.huawei.hms.ads.nativead.NativeView xmlns:android="http://schemas.android.com/apk/res/android"
  2.     android:id="@+id/native_video_view"
  3.     android:layout_width="match_parent"
  4.     android:layout_height="wrap_content"
  5.     android:layout_centerInParent="true"
  6.     android:background="#FFFFFF"
  7.     android:orientation="vertical">
  8.     <RelativeLayout
  9.         android:id="@+id/background"
  10.         android:layout_width="match_parent"
  11.         android:layout_height="wrap_content">
  12.         <com.huawei.hms.ads.nativead.MediaView
  13.             android:id="@+id/ad_media"
  14.             android:layout_width="match_parent"
  15.             android:layout_height="wrap_content" />
  16.         <RelativeLayout
  17.             android:id="@+id/left_bottom_view"
  18.             android:layout_width="wrap_content"
  19.             android:layout_height="wrap_content"
  20.             android:layout_below="@id/ad_media">
  21.             <TextView
  22.                 android:id="@+id/ad_title"
  23.                 android:layout_width="180dp"
  24.                 android:layout_height="19dp"
  25.                 android:layout_marginStart="24dp"
  26.                 android:layout_marginTop="16dp"
  27.                 android:alpha="1"
  28.                 android:textColor="#000000"
  29.                 android:textSize="@dimen/hiad_text_13_sp" />
  30.             <TextView
  31.                 android:id="@+id/ad_source"
  32.                 android:layout_width="wrap_content"
  33.                 android:layout_height="19dp"
  34.                 android:layout_below="@id/ad_title"
  35.                 android:layout_marginStart="24dp"
  36.                 android:layout_marginTop="2dp"
  37.                 android:layout_marginBottom="16dp"
  38.                 android:alpha="0.6"
  39.                 android:maxWidth="158dp"
  40.                 android:textColor="#666666"
  41.                 android:textSize="@dimen/hiad_text_12_sp" />
  42.             <TextView
  43.                 android:id="@+id/ad_flag"
  44.                 android:layout_width="20dp"
  45.                 android:layout_height="14dp"
  46.                 android:layout_marginStart="8dp"
  47.                 android:layout_marginTop="40dp"
  48.                 android:layout_toEndOf="@+id/ad_source"
  49.                 android:background="@drawable/native_flag_rounded_corners_shape"
  50.                 android:gravity="center"
  51.                 android:text="@string/ad_flag"
  52.                 android:textColor="#FFFFFF"
  53.                 android:textSize="8sp"
  54.                 android:textStyle="bold" />
  55.         </RelativeLayout>
  56.         <RelativeLayout
  57.             android:id="@+id/right_bottom_view"
  58.             android:layout_width="wrap_content"
  59.             android:layout_height="wrap_content"
  60.             android:layout_below="@id/ad_media"
  61.             android:layout_alignParentEnd="true">
  62.             <Button
  63.                 android:id="@+id/ad_call_to_action"
  64.                 android:layout_width="72dp"
  65.                 android:layout_height="26dp"
  66.                 android:layout_alignParentEnd="true"
  67.                 android:layout_marginTop="23dp"
  68.                 android:layout_marginEnd="52dp"
  69.                 android:layout_marginBottom="23dp"
  70.                 android:background="@drawable/native_button_rounded_corners_shape"
  71.                 android:textColor="#FFFFFF"
  72.                 android:textSize="10sp" />
  73.         </RelativeLayout>
  74.     </RelativeLayout>
  75. </com.huawei.hms.ads.nativead.NativeView>

其中drawable/native_flag_rounded_corners_shape.xml文件内容如下：

  1. <shape xmlns:android="http://schemas.android.com/apk/res/android">
  2.     <solid android:color="#CCCCCC" />
  3.     <padding
  4.         android:bottom="1dp"
  5.         android:left="1dp"
  6.         android:right="1dp"
  7.         android:top="1dp" />
  8.     <corners
  9.         android:bottomLeftRadius="2dp"
  10.         android:bottomRightRadius="2dp"
  11.         android:topLeftRadius="2dp"
  12.         android:topRightRadius="2dp" />
  13. </shape>

其中drawable/native_button_rounded_corners_shape.xml文件内容如下：

  1. <shape xmlns:android="http://schemas.android.com/apk/res/android">
  2.     <solid android:color="#214EF3" />
  3.     <padding
  4.         android:bottom="1dp"
  5.         android:left="1dp"
  6.         android:right="1dp"
  7.         android:top="1dp" />
  8.     <corners
  9.         android:bottomLeftRadius="20dp"
  10.         android:bottomRightRadius="20dp"
  11.         android:topLeftRadius="20dp"
  12.         android:topRightRadius="20dp" />
  13. </shape>

5. 原生广告设置选项

通过NativeAdConfiguration对象可以实现对原生广告的自定义设置。示例代码如下：

  1. // "testy63txaom86"为专用的测试广告位ID。
  2. NativeAdLoader.Builder builder = new NativeAdLoader.Builder(this, "testy63txaom86");
  3. NativeAdConfiguration adConfiguration = new NativeAdConfiguration.Builder()
  4.         .setVideoConfiguration(videoConfiguration) // 设置视频选项
  5.         .setRequestCustomDislikeThisAd(true) // 是否要自定义“不再显示该广告”
  6.         .build();
  7. builder.setNativeAdOptions(adConfiguration);

了解详细方法，请参见API文档中的NativeAdConfiguration.Builder类。

6. 不再显示该广告

通过“不再显示该广告”功能，用户可以自行关闭不感兴趣的广告。

样例如下所示：

            

图1.原生广告展示视图                                              图2.广告选项展示视图


            

图3.不显示该广告原因选项视图                                 图4.原生广告已关闭视图


如果不想展示“广告已关闭”的视图，可调用NativeAd类中的setDislikeAdListener()方法为原生广告对象设置关闭广告事件监听器，并在监听器中的onAdDisliked()方法中添加自定义实现。当广告关闭时，SDK会回调监听器中的onAdDisliked()方法。

示例代码如下：

  1. NativeAdLoader.Builder builder = new NativeAdLoader.Builder(this, "testy63txaom86");
  2. builder.setNativeAdLoadedListener(new NativeAd.NativeAdLoadedListener() {
  3.     @Override
  4.     public void onNativeAdLoaded(NativeAd nativeAd) {
  5.         ...
  6.         nativeAd.setDislikeAdListener(new DislikeAdListener() {
  7.             @Override
  8.             public void onAdDisliked() {
  9.                 // TODO 广告关闭时调用
  10.             }
  11.         });
  12.     }
  13. });

通过NativeAdConfiguration.Builder类中的setRequestCustomDislikeThisAd()方法可以设置是否要自定义“不再显示该广告”。当设置为自定义版“不再显示该广告”时，原生广告将会显示“为什么看到此广告”图标。如果需要隐藏“为什么看到此广告”图标，可调用NativeAdConfiguration.Builder类中的setChoicesPosition()方法将其设置为不可见。

示例代码如下：

  1. NativeAdConfiguration adConfiguration = new NativeAdConfiguration.Builder()
  2.         .setRequestCustomDislikeThisAd(true) // 需要自定义“不再显示该广告”
  3.         .setChoicesPosition(NativeAdConfiguration.ChoicesPosition.INVISIBLE) // 隐藏“为什么看到此广告”图标
  4.         .build();
  5. NativeAdLoader nativeAdLoader = builder.setNativeAdOptions(adConfiguration).build();
注意：
若要隐藏“为什么看到此广告”图标，则需要在自定义广告选项列表中添加“为什么看到此广告”选项。当点击“为什么看到此广告”选项时，调用NativeView类中的gotoWhyThisAdPage()方法即可跳转到为什么看到此广告的页面。

当原生广告加载完成时，可调用NativeAd.isCustomDislikeThisAdEnabled()判断是否已设置为要自定义“不再显示该广告”。另外，可通过NativeAd.getDislikeAdReasons()方法获取“不再显示该广告”的信息列表，然后将其显示在开发者自定义界面中。

示例代码如下：

  1. if (nativeAd.isCustomDislikeThisAdEnabled()) {
  2.     List<DislikeAdReason> dislikeAdReasons = nativeAd.getDislikeAdReasons();
  3. }

通过NativeAd.dislikeAd()方法可以将被选中的“不再显示该广告”选项信息反馈给SDK。

示例代码如下：

  1. nativeAd.dislikeAd(dislikeAdReason);

7. 测试原生广告

原生广告测试广告位ID，仅可用于调测原生广告功能，不可用于广告变现，在应用正式发布前需替换为正式的原生广告位ID，开发者应在应用发布前申请真实的广告位ID并替换测试广告位ID。

原生广告测试广告位ID列表如下：

广告形式

展示形式

尺寸

比例

测试广告位ID

原生广告

大图文

1080*607

16:9

testu7m3hc4gvm

原生广告

小图文

225*150

3:2

testb65czjivt9

原生广告

视频文

640*360

16:9

testy63txaom86


具体实现可以参考示例代码，运行示例代码可以看到如下效果图：