在 Android/Amazon 上集成原生广告 - 抢先体验

Vungle Agent

2023年04月10日 17:44

欢迎使用 Vungle 抢先体验原生广告！从 Vungle SDK v.6.11 开始，Vungle 支持原生广告。要参与抢先体验版，请联系您的客户经理。

了解原生广告

原生广告以这种方式命名，因为它们是应用内容格式的“原生”。 SDK 不是为您提供横幅广告或全屏广告，而是为您的应用程序提供广告的组件，并允许您的应用程序控制广告的排列和展示。因为您（发布商）控制着广告的格式，所以您可以使其与您的应用程序的外观和感觉保持一致。与其他广告格式相比，这为用户提供了更加无缝的广告体验。

当广告的一个像素出现在屏幕上时，就会触发并计算原生广告的展示次数。

步骤 1. 完成基本集成

要将横幅广告集成到您的 Android 或 Amazon 应用程序中，请按照基本集成文章中的说明开始。本原生广告文章包含补充信息，并假设您已完成基本集成。

步骤 2. 实现事件监听器

您可以通过为广告加载事件和播放事件实现NativeAdListener来使用通用回调，或者在调用loadAd时使用内联回调。

实现 NativeAdListener

private final NativeAdListener nativeAdListener = new NativeAdListener() {
    @Override
    public void onNativeAdLoaded(NativeAd nativeAd) {
        Log.e(TAG, "Native ad loaded.");
    }

    @Override
    public void onAdLoadError(String placementId, VungleException exception) {
        Log.e(TAG, "Native ad failed to load: " + exception.getLocalizedMessage());
    }

    @Override
    public void onAdPlayError(String placementId, VungleException exception) {
        Log.e(TAG, "Native ad failed to play: " + exception.getLocalizedMessage());
    }

    @Override
    public void onAdImpression(String placementId) {
    	Log.e(TAG, "Native ad impression logged.");
    }

    @Override
    public void onAdClick(String placementId) {
    	Log.e(TAG, "Native ad clicked.");
    }

    @Override
    public void onAdLeftApplication(String placementId) {
    	Log.e(TAG, "Native ad left application.");
    }

    @Override
    public void creativeId(String creativeId) {
        Log.e(TAG, "Receive creative Id:" + creativeId);
    }
};

可覆盖的方法	描述
`onNativeAdLoaded(NativeAd nativeAd)`	用于通知广告资源已下载并准备播放的回调。
`onAdLoadError(String placementId, VungleException exception)`	用于通知下载资产时发生错误的回调。这表示 SDK 中存在不可恢复的错误，例如网络不足或设备磁盘空间不足。
`onAdPlayError(String placementId, VungleException exception)`	调用 registerViewForInteraction 函数后发生的错误回调。如果调用此方法，则 SDK 无法恢复错误，错误处理应在应用程序层进行。这表明广告已经结束。
`onAdImpression(String placementId)`	在 Vungle SDK 成功启动广告并首次呈现广告时调用。
`onAdClick(String placementId)`	已点击广告的回调。当用户点击广告时发送。
`onAdLeftApplication(String placementId)`	用户离开应用时的回调。
`creativeId(String creativeId)`	在发出 registerViewForInteraction 之后和 onAdImpression 回调之前立即调用。要显示的 Vungle 广告素材 ID 将被传递以用于跟踪或报告目的。

第 3 步：加载、显示和关闭原生广告

加载原生广告

重要提示：请务必在加载新广告之前关闭最后一个原生广告。在加载的原生广告上使用destroy()函数可以释放已使用的资源并防止内存泄漏。

加载横幅广告的工作方式与加载其他广告格式不同。您可以使用特定的NativeAd API 来加载、播放和检查广告可用性。

创建原生广告对象：

NativeAd nativeAd = new NativeAd(context, "YOUR_PLACEMENT_ID");

通过调用loadAd方法加载原生广告：

AdConfig adConfig = new AdConfig();
nativeAd.loadAd(adConfig, nativeAdListener);

设置广告选项位置（可选）：默认情况下， AdOptionsView设置为右上角。应用程序可以通过将此属性设置为以下之一来更改此隐私图标视图在哪个角落呈现：
```
AdConfig adConfig = new AdConfig();
adConfig.setAdOptionsPosition();
AdConfig.TOP_LEFT
AdConfig.TOP_RIGHT
AdConfig.BOTTOM_LEFT
AdConfig.BOTTOM_RIGHT
```

检查广告可用性

通过调用canPlayAd方法检查原生广告的可用性：

nativeAd.canPlayAd();

展示原生广告

NativeAdLayout:包含所有其他原生广告组件的主视图
ImageView:显示图标图像的视图
MediaView:显示主图像的视图
TextView:显示广告标题的标签
TextView:显示应用评分的标签
TextView:显示“赞助者”文本的标签
NativeAdOptionsView:显示隐私图标的选项视图；因为这是一个私有类，请按照加载原生广告部分的第三步中的说明使用setAdOptionsPosition API
TextView:显示广告正文的标签
Button:显示号召性用语 (CTA) 文本的按钮

您可以将视图放置在屏幕上的任何位置。这个容器是一个布局。您可以将此布局放置在屏幕上的任何位置。

创建您的原生广告布局：

<com.vungle.warren.NativeAdLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/native_ad_container"
    android:layout_width="match_parent"
    android:layout_height="wrap_content">
    <LinearLayout
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:orientation="vertical">
        <LinearLayout
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:padding="5dp"
            android:gravity="center_vertical"
            android:orientation="horizontal"
            android:weightSum="1">
            <ImageView
                android:id="@+id/native_ad_icon"
                android:layout_width="48dp"
                android:layout_height="48dp" />
            <LinearLayout
                android:layout_width="0dp"
                android:layout_height="wrap_content"
                android:layout_marginLeft="5dp"
                android:layout_marginRight="5dp"
                android:orientation="vertical"
                android:layout_weight="0.7">
                <TextView
                    android:id="@+id/native_ad_title"
                    android:layout_width="match_parent"
                    android:layout_height="wrap_content"
                    android:ellipsize="end"
                    android:lines="1"
                    android:textColor="@android:color/black"
                    android:textSize="15sp" />
                <LinearLayout
                    android:layout_width="match_parent"
                    android:orientation="horizontal"
                    android:layout_height="wrap_content">
                    <TextView
                        android:id="@+id/rateTV"
                        android:layout_width="wrap_content"
                        android:layout_marginRight="10dp"
                        android:layout_height="wrap_content" />
                    <TextView
                        android:id="@+id/native_ad_body"
                        android:layout_width="wrap_content"
                        android:layout_height="wrap_content"
                        android:ellipsize="end"
                        android:gravity="center_vertical"
                        android:lines="2"
                        android:textColor="@android:color/black"
                        android:textSize="12sp" />
                </LinearLayout>
            </LinearLayout>
            <LinearLayout
                android:id="@+id/ad_choices_container"
                android:layout_width="48dp"
                android:layout_height="48dp"
                android:orientation="horizontal"
                android:layout_weight="0.3" />
        </LinearLayout>
        <com.vungle.warren.ui.view.MediaView
            android:id="@+id/native_ad_media"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:gravity="center" />
        <RelativeLayout
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:padding="5dp">
            <Button
                android:id="@+id/native_ad_call_to_action"
                android:layout_width="wrap_content"
                android:layout_height="50dp"
                android:layout_alignParentRight="true"
                android:background="#4286F4"
                android:textSize="12sp"
                android:textColor="@android:color/white"
                android:paddingLeft="3dp"
                android:paddingRight="3dp"
                android:visibility="visible" />
            <TextView
                android:id="@+id/native_ad_sponsored_label"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content"
                android:ellipsize="end"
                android:textSize="12sp" />
        </RelativeLayout>
    </LinearLayout>
</com.vungle.warren.NativeAdLayout>

使用广告的元数据填充您的布局：

private final NativeAdListener nativeAdListener = new NativeAdListener() {
    @Override
    public void onAdLoaded(NativeAd nativeAd) {
        if (nativeAd == null || !nativeAd.canPlayAd()) {
            return;
        }
        // Inflate Native Ad into Container
        inflateAd(nativeAd);
    }
    ...
};

private void inflateAd(NativeAd nativeAd) {
    NativeAdLayout nativeAdLayout = findViewById(R.id.native_ad_container);

    // Create native UI using the ad metadata.
    ImageView nativeAdIcon = nativeAdLayout.findViewById(R.id.native_ad_icon);
    TextView nativeAdTitle = nativeAdLayout.findViewById(R.id.native_ad_title);
    MediaView nativeAdMedia = nativeAdLayout.findViewById(R.id.native_ad_media);
    TextView rateView = nativeAdLayout.findViewById(R.id.rateTV);
    TextView nativeAdBody = nativeAdLayout.findViewById(R.id.native_ad_body);
    TextView sponsoredLabel = nativeAdLayout.findViewById(R.id.native_ad_sponsored_label);
    Button nativeAdCallToAction = nativeAdLayout.findViewById(R.id.native_ad_call_to_action);

    // Set the Text.
    nativeAdTitle.setText(nativeAd.getAdTitle());
    nativeAdBody.setText(nativeAd.getAdBodyText());
    rateView.setText(Double.toString(nativeAd.getAdStarRating()));
    nativeAdCallToAction.setVisibility(nativeAd.hasCallToAction() ? View.VISIBLE : View.INVISIBLE);
    nativeAdCallToAction.setText(nativeAd.getAdCallToActionText());
    sponsoredLabel.setText(nativeAd.getAdSponsoredText());

    // Create a list of clickable views
    List<View> clickableViews = new ArrayList<>();
    clickableViews.add(nativeAdTitle);
    clickableViews.add(nativeAdCallToAction);

    // Register the Title and CTA button to listen for clicks.
    nativeAd.registerViewForInteraction(
            nativeAdLayout, nativeAdMedia, nativeAdIcon, clickableViews);
}

控制可点击区域：我们使用clickableViews来控制哪些视图可以点击。在上面的示例中，只有标题和 CTA 按钮是可点击的。默认情况下，如果您将 null 传递给clickableViews ， NativeAd MediaView是可点击的。
控制可点击区域
```
nativeAd.registerViewForInteraction(
            nativeAdLayout, nativeAdMedia, nativeAdIcon, null);
```

关闭原生广告

按如下方式关闭原生广告：

nativeAd.destroy();

第 4 步：使用我们的 NativeAdLayout API 进行高级控制（可选）

大多数情况下，上述的集成就足够了， NativeAdLayout是托管的。但是，如果NativeAdLayout视图位于列表或RecyclerView中，则托管的NativeAdLayout将无法正常工作。用户将广告滚动到屏幕外并向后滚动的那一刻，广告将完成并且不再显示。对于这种情况，我们提供了一个高级 API 来更好地控制NativeAdLayout 。

NativeAdLayout 类 API

这些 API 让开发人员可以很好地控制如何在开发人员应用程序中处理各种生命周期事件中的NativeAdLayout 。在大多数用例中，开发人员不需要调用这些方法。只需将NativeAdLayout添加到父视图中就足够了。然而，在极少数情况下，视图会被回收（例如 RecyclerView、ListView 等）。

在使用此 API 之前，您必须调用nativeAdLayout.disableLifeCycleManagement(true) 。

姓名	功能	笔记
`disableLifeCycleManagement()`	调用以禁用原生广告的自动管理	必须设置为“true”才能使`renderNativeAd`和`finishNativeAd`工作
`renderNativeAd()`	开始播放原生广告
`finishNativeAd()`	销毁原生广告	释放原生广告资源

第 5 步：测试原生广告

您可以通过以下两种方式之一测试原生广告：将您的应用状态设置为测试模式，以便 Vungle 可以向您的应用投放测试广告，或者通过向您的应用添加测试设备，以便 Vungle 可以专门向测试装置。按照测试您的集成：测试模式和测试设备中的说明进行操作。