Android Native Ads

Creating Native Ad Template

In this step, you will learn how to create your native ad XML template layout and how to bind your XML layout’s resources to the native ad assets.

1. Create Native ad XML layout

The native ad template consists of multiple Views; these Views are mapped to the native ad assets. You should include in the template only the native ad assets that are needed as per the desired design.

Some examples for native ad templates are shown below.

image005

You can state what native ad assets are requested by including them in the native ad template layout. AdFalcon will only return native ads that include the requested assets as per the below rules:

  • Required Assets

Your native ad must display AdChoices view and at least one of the assets below otherwise it will be considered as invalid template:

  • Icon
  • Title
  • MainAsset

AdFalcon will only return ads which contain all the required assets included in the native ad template

  • Optional Assets

All remaining native ad asset types are optional.

The template may include one or more of the optional assets or none at all as per the desired design.

The returned native ad may or may not include any of the requested optional assets; i.e. the optional native ad assets will only be returned when available.

If a native ad response does not contain any of the optional assets, the SDK will hide its associated view.

Refer to Native Ad Template Assets in the Appendix B  for all Native Ad Template Resources which can be included in the template layout.

In the following example, we will create a template that contains icon, title, (image or xhtml), description, rating bar, sponsored and CTA for the native ad:

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout 
    xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    android:padding="16dp">

    <RelativeLayout
        android:id="@+id/adchoices_view"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_alignParentRight="true" />

    <ImageView
        android:id="@+id/template_icon"
        android:layout_width="50dp"
        android:layout_height="50dp"
        android:layout_margin="10dp"
        android:src="@mipmap/ic_launcher"
        android:scaleType="fitXY" />

    <TextView
        android:id="@+id/template_title"
        style="?android:attr/textAppearanceLarge"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_marginTop="10dp"
        android:text="Native Ad Title"
        android:layout_toRightOf="@id/template_icon" />
	
    <TextView
        android:id="@+id/template_description"
        style="?android:attr/textAppearanceMedium"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_below="@id/template_title"
        android:layout_marginTop="10dp"
        android:text="Native Ad Description"
        android:layout_toRightOf="@id/template_icon" />

    <RelativeLayout
        android:id="@+id/template_main_asset"
        android:layout_width="match_parent"
        android:layout_height="100dp"
        android:layout_below="@id/template_description"
        android:layout_marginTop="10dp" />

    <RatingBar
        android:id="@+id/template_rating"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_below="@id/template_main_asset "
        android:layout_marginTop="10dp" />

    <TextView
        android:id="@+id/template_sponsored"
        style="?android:attr/textAppearanceMedium"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:layout_below="@id/template_rating "
        android:layout_marginTop="10dp" />

    <Button
        android:id="@+id/template_action_button"
        style="?android:attr/textAppearanceMedium"
        android:layout_width="200dp"
        android:layout_height="wrap_content"
        android:layout_below="@id/template_sponsored"
        android:layout_centerHorizontal="true"
        android:layout_marginTop="10dp"
        android:text="@string/app_name" />

</RelativeLayout>


2. Bind your XML template layout’s resources to native ad assets

This step shows how to connect your native ad XML template layout’s resources to their corresponding native ad assets (title view, main image, icon, etc.).

You should at minimum bind one of the mandatory native ad assets (Icon, Title or MainAsset) depending on the native ad template design in-place.

The binder requires setting parameters for each native ad asset, these parameters depend on the View type and its abilities. In case of TextView, the developer should pass the maximum text length that can be rendered in the TextView perfectly. In case of ImageView, the developer should pass the minimum width and height of the image which can be rendered clearly in the ImageView.

Binding views to native ad assets is achieved using the binder object of ADFAssetsBinder class by calling the appropriate binding method (addIconImageView, addTitleImageView, addMainAssetRelativeLayout, addDescriptionTextView, addActionButton, addStarRatingBar and addExtraDataTextView).

Please refer to the Appendix B  ADFAssetsBinder for more details.

Below is a sample bindViews method implementation:


ADFAssetsBinder binder = new ADFAssetsBinder.Builder(this, R.layout.template_layout).
addAdChoicesRelativeLayout(R.id.adchoices_view).
addIconImageView(R.id.icon_template, 50, 50).
addTitleTextView(R.id.title_template,25).
addDescriptionTextView(R.id. template_description, 100).
addMainAssetRelativeLayout(R.id. template_container, 50, 50).
addStarRatingBar(R.id.template _rating).
addExtraDataTextView(ADFAssetsBinder.DATA_ID_SPONSORED, R.id.template_sponsored, 20).
addActionButton(R.id.template_action_button, 10).
build();//this will build a binder which will bind an icon, title, MainAsset, sponsored extra data, and action button. 

Requesting and Handling Native Ad.

1. Create an instance of ADFNativeAd

ADFNativeAd nativeAd = new ADFNativeAd(this); //this refers to the current activity

2. Implement ADFNativeAdListener

ADFNativeAdListener provides ability to track native ad lifecycle events.

nativeAd.setListener(new ADFNativeAdListener(){

	public void onLoadAd(ADFNativeAd nativeAd) {
	//this method will be called once the ad has been loaded and ready to be shown.
	}

	public void onFail(ADFNativeAd ad, ADFErrorCode errorCode, String message) {
	//this method will be called once an error occurred while loading or showing ad.
	}

	public void renderExtraData(View view, Hashtable&amp;lt;Integer, String&amp;gt; hashtable) {
/* This method is used to allow the app to draw any extra data assets that were not bound explicitly in the ADFAssetsBinder. This is used if the app is willing to entirely take over the extra data display and presentation.*/
	}

		public void onPresentAdScreen(ADFNativeAd ad){
		//this method will be called once the ad action has been viewed.
	}

		public void onDismissAdScreen (ADFNativeAd ad){
		//this method will be called once the ad action view has been dismissed.
	}

		public void onLeaveApplication (){
		//this method will be called once the ad action has been viewed in another application.
	}

});

3. Load native ad

Call loadAd method to load a new native ad by passing your site ID and binder.

nativeAd.loadAd("your site ID", null, binder);

 

Note: It is highly recommended that you provide all available targeting information such as gender, location, content category to your ad request in order to receive the best ad that meets the criteria of your audience and maximize your return. This can be done by filling the params object in loadAd method. Please refer to the Appendix B  ADFTargetingParams for all the available targeting parameters.


4. Rendering the native ad

After loading the native ad successfully, onLoadAd method will be fired immediately.

Hence this method will be used to add the native ad to your ViewGroup.

public void onLoadAd(ADFNativeAd nativeAd) {
//this method will be called once the ad has been loaded and ready to be shown.
LinearLayout layout = (LinearLayout) findViewById(R.id.layout);
layout.addView(nativeAd);
}

5. Destroy the native ad

You should destroy the native ad once onDestroy lifecycle method is called.

protected void onDestroy() {
nativeAd.destroy();
super.onDestroy();
}

6. Test native ad code

Enable testing parameter to ensure your code and template during development to ensure everything is working as expected.

Add the below line of code before calling loadAd method.

nativeAd.setTesting(true);

 

Note: Ensure testing parameter is set to false before uploading your app to the market.

Advance Native Ad Options

ADFNativeAdStatus getStatus()

This method returns the current lifecycle status of the native ad. The below table illustrates the possible values of ADFNativeAdStatus

Enum Description
loading Native ad is loading currently.
loaded Native ad has finished loading.
shown Native ad has been shown.
failed An error occurred while loading or showing the native ad.

You can call getErrorMessage() to obtain more information.

clicked User has clicked on the native ad.

setLogging(boolean logging)

This method is used to enable or disable the logger of the SDK.