Integrate Native Ads on Android/Amazon - Early Access

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

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. 

  1. Create a native ad object:
    NativeAd nativeAd = new NativeAd(context, "YOUR_PLACEMENT_ID");
  2. Load a native ad by calling the loadAd method:
    AdConfig adConfig = new AdConfig();
    nativeAd.loadAd(adConfig, nativeAdListener);
  3. 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

VungleNativeAd_sample_guide.png

  1. NativeAdLayout: A main view that contains all other Native Ad components
  2. ImageView: A view to display an icon image
  3. MediaView: A view to display a main image
  4. TextView: A label to display the ad title
  5. TextView: A label to display app rating
  6. TextView: A label to display "Sponsored By" text
  7. 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
  8. TextView: A label to display ad body text
  9. Button: A button to display Call to Action (CTA) text

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

  1. Create your native ad Layout:
    Create Your 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>
  2. Populate your Layout using the ad's metadata:
    Populate Your Layout
    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);
    }
    
  3. 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:

Close a Native Ad
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' forrenderNativeAd andfinishNativeAd 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.

Powered by Creativity Driven by Performance Sign Up Here

Questions?

Need further assistance, feel free to reach out to us, we’re here to help!

Was this article helpful?