Integrate Native Ads on Vungle SDK v.6 for Android/Amazon

Vungle Agent

September 17, 2024 17:36

Welcome to Vungle's early access to Native Ads! Starting with Vungle SDK v.6.11, Vungle supports native ads. To participate in the early access release, contact your account manager.

Understand Native Ads

Native ads are named this way because they are “native” to your app’s content format. Instead of giving you a banner or fullscreen ad, the SDK provides your application the components of the ad and allows your application to control the arrangement and presentation of the ad. Because you, the publisher, control the ad’s format, you can keep it consistent with the look and feel of your app. This gives the user a more seamless advertising experience than do other ad formats.

Impressions for native ads are fired and counted when one pixel of the ad is on screen.

Step 1. Complete Basic Integration

To integrate banner ads in your Android or Amazon app, begin by following the instructions in the basic integration article. This Native Ads article contains supplementary information and assumes you have completed basic integration.

Step 2. Implement Event Listeners

You can use generic callbacks, by implementing NativeAdListener for ad load events and play events, or use inline callbacks when you invoke loadAd.

Implement 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);
    }
};

Overridable Methods	Description
`onNativeAdLoaded(NativeAd nativeAd)`	Callback used to notify that the advertisement assets have been downloaded and are ready to play.
`onAdLoadError(String placementId, VungleException exception)`	Callback used to notify that an error has occurred while downloading assets. This indicates an unrecoverable error within the SDK, such as lack of network or out of disk space on the device.
`onAdPlayError(String placementId, VungleException exception)`	Callback for an error that has occurred after calling the registerViewForInteraction function. If this is called, the error was unrecoverable by the SDK and error handling should happen at the application layer. This indicates that the advertisement has finished.
`onAdImpression(String placementId)`	Called when the Vungle SDK has successfully launched the advertisement and the advertisement is first rendered.
`onAdClick(String placementId)`	Callback for an advertisement tapped. Sent when the user has tapped on an ad.
`onAdLeftApplication(String placementId)`	Callback when the user has left the app.
`creativeId(String creativeId)`	Invoked immediately after registerViewForInteraction has been issued and prior to onAdImpression callback. Vungle creative ID to be shown will be passed to be used for tracking or reporting purpose.

Step 3. Load, Display, and Close a Native Ad

Load a Native Ad

IMPORTANT: Be sure to close the last native ad before loading a new one. Using the destroy() function on loaded native ads frees up utilized resources and prevents memory leaks.

Loading a banner ad works differently than it does for other ad formats. There is a specific NativeAd API that you use to load, play, and check for ad availability.

Create a native ad object:

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

Load a native ad by calling the loadAd method:

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

Set Ad Options Position (Optional): The AdOptionsView is set to the top right corner by default. Apps can change which corner this privacy icon view is rendered in by setting this property to one of the following:
```
AdConfig adConfig = new AdConfig();
adConfig.setAdOptionsPosition();
AdConfig.TOP_LEFT
AdConfig.TOP_RIGHT
AdConfig.BOTTOM_LEFT
AdConfig.BOTTOM_RIGHT
```

Check Ad Availability

Check for native ad availability by calling the canPlayAd method:

nativeAd.canPlayAd();

Display a Native Ad

NativeAdLayout: A main view that contains all other Native Ad components
ImageView: A view to display an icon image
MediaView: A view to display a main image
TextView: A label to display the ad title
TextView: A label to display app rating
TextView: A label to display "Sponsored By" text
NativeAdOptionsView: An option view to display privacy icon; because this is a private class, use the setAdOptionsPosition API as instructed in the third step of the Load a Native Ad section
TextView: A label to display ad body text
Button: A button to display Call to Action (CTA) text

Item 1 NativeAdLayout and Item 3 MediaView are required. Other items are optional.

You can place the view anywhere on the screen. This container is a Layout. You can place this Layout anywhere on the screen.

Create your native ad Layout:

<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>

Populate your Layout using the ad's metadata:

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);
}

Control the clickable area: We use clickableViews to control which views can be clicked. In the example above, only the title and CTA button are clickable. By default the NativeAd MediaView is clickable if you pass null to the clickableViews.
Control the Clickable Area
```
nativeAd.registerViewForInteraction(
            nativeAdLayout, nativeAdMedia, nativeAdIcon, null);
```

Close a Native Ad

Close a native ad as follows:

nativeAd.destroy();

Step 4. Use Our NativeAdLayout API for Advanced Control (Optional)

In most cases, the integration described above is sufficient, and NativeAdLayout is managed. However, if the NativeAdLayout view is inside a list or a RecyclerView, the managed NativeAdLayout will not work correctly. The moment the user scrolls the ad offscreen and scrolls back, the ad will be finished and will no longer display. For such cases, we provide an advanced API for finer control of the NativeAdLayout.

NativeAdLayout Class API

These APIs give developers fine control over how to treat the NativeAdLayout across various life cycle events in the developer application. In most use cases, developers do not need to invoke these methods. Simply adding a NativeAdLayout into a parent view suffices. In rare cases, however, a view will be recycled (such as a RecyclerView, ListView, etc.).

You must invoke nativeAdLayout.disableLifeCycleManagement(true) before using this API.

Name	Function	Notes
`disableLifeCycleManagement()`	Invoke to disable automatic management of native ad	Must be set to 'true' for`renderNativeAd` and`finishNativeAd` to work
`renderNativeAd()`	Start playing native ad
`finishNativeAd()`	Destroy native ad	Frees native ad resources

Step 5. Test a Native Ad

You can test a Native Ad in one of two ways: by setting your app status to Test Mode so that Vungle can deliver test ads to your app, or by adding a test device to your app so that Vungle can deliver test ads specifically to the test device. Follow the instructions in Test Your Integration: Test Mode and Test Devices.