Native Ads

InMobi Native Ads support both video and static ads. You can opt for In-Feed, Splash or Pre-Roll formats. The steps for creating a native ad placement are given below:

Set up a Native Ad

  1. Create a Native Content placement.
  2. In-Feed Video Ad Placement

    Select FEED as the Native Ad Layout. For In-Feed Video, select either of the aspect ratio 256:135 or 16:9. Both the aspect ratios will have default static native fallback enabled with similar aspect ratio.

  1. Static Feed Ad Placement

    Select FEED as the Native Ad Layout.

    In the integration code, please ensure nativeAd.getPrimaryViewOfWidth(context,convertView, parent, width); Specify width = 25 while fetching your primaryView. It will just show the AdChoices icon and fire the ad render events.

  2. Splash Video Ad Placement

    Select SPLASH as the Native Ad Layout.


Select the desired aspect ratio. Default value for the aspect ratio will be 9:16.
    

  1. Others (China only)

    Select Others as the Native Ad Layout.


    Select aspect ratio 16:9. This will have default static native fallback enabled with similar aspect ratio. A new sub field is added in Others layout called Native Layout Type. It has the following values: “Native Interstitial”, “Native Page”, “Native Banner”, “Native Focus”, “Native Lock Screen”, “Native Other”. Default value will be Native Interstitial in Native layout type field.
     
  2. Pre-Roll Ad Integration

    Select Pre-roll as the Native Ad Layout. 
 

Add the Native Ad to your App

Creating a Native Ad

To create a native ad, create an InMobiNative instance:

public class NativeAdsActivity extends Activity { 
    …………………… 
    private final List<InMobiNative> mNativeAds = new ArrayList<>(); 
    …………………… 
    InMobiNative nativeAd = new InMobiNative(NativeAdsActivity.this, YOUR_PLACEMENT_ID, nativeAdEventListener); 
    nativeAd.load(); 
    mNativeAds.add(nativeAd); 
    …………………… 
}

Here nativeAdEventListener is an implementation of the NativeAdEventListener abstract class. It is mandatory to supply an implementation of this interface to create a native ad. Creating an InMobiNative object without SDK Initialization will throw an exception.

Mandatory

You must supply a Context implementation to the InMobiNative constructor. Please make sure your implementation holds a strong reference of InMobiNative otherwise you will not be able to get any callback from SDK for this reference. This can be achieved by making it a member variable of a class or storing it in collection, which lives through your application life cycle.

  • inMobiNative should always be strong reference otherwise you may not receive any callback (load success, load failure etc.) for this reference.
  • If inMobiNative is referenced by any variable please ensure that it is a strong reference.
  • Use android profiler to ensure that inMobiNative is not removed due to garbage collection.

NativeAdEventListener abstract class allows you to listen to key lifecycle events for a native ad.

/** 
 * A listener for receiving notifications during the lifecycle of a Native ad. 
 */
public abstract class NativeAdEventListener {
    /** 
     * Called to indicate that an ad is available in response to a request for an ad (by calling 
     * {@link InMobiNative#load()}. Note: This does not 
     * indicate that the ad can be shown yet. Your code should show an ad after the 
     * {@link #onAdLoadSucceeded(InMobiNative)} method is called. Alternately, if you do not 
     * want to handle this event, you must test if the ad is ready to be shown by checking the 
     * result of calling the {@link InMobiNative#isReady()} method.
     * 
     * @param ad Represents the {@link InMobiNative} ad for which ad content was received 
     */
    public void onAdReceived(InMobiNative ad) {}
    /** 
     * Called to indicate that an ad was loaded and it can now be shown. This will always be called 
     * after the {@link #onAdReceived(InMobiNative)} callback. 
     * 
     * @param ad Represents the {@link InMobiNative} ad which was loaded 
     */
    public void onAdLoadSucceeded(InMobiNative ad) {}
    /** 
     * Called to notify that a native ad failed to load. 
     * 
     * @param ad  Represents the {@link InMobiNative} ad which failed to load 
     * @param requestStatus Represents the {@link InMobiAdRequestStatus} status containing error reason 
     */
    public void onAdLoadFailed(InMobiNative ad, InMobiAdRequestStatus requestStatus) {}
    /** 
     * 
     * @param ad  Represents the {@link InMobiNative} ad whose fullscreen was dismissed 
     */
    public void onAdFullScreenDismissed(InMobiNative ad) {}
    /** 
     * Called to notify that the ad will open an overlay that covers the screen. 
     * 
     * @param ad Represents the {@link InMobiNative} ad which will go fullscreen 
     */
    public void onAdFullScreenWillDisplay(InMobiNative ad) {}
    /** 
     * Called to notify that the ad opened an overlay that covers the screen. 
     * 
     * @param ad Represents the {@link InMobiNative} ad whose fullscreen will be displayed 
     */
    public void onAdFullScreenDisplayed(InMobiNative ad) {}
    /** 
     * Called to notify that the user is about to leave the application as a result of interacting with it. 
     * 
     * @param ad Represents the {@link InMobiNative} ad 
     */
    public void onUserWillLeaveApplication(InMobiNative ad) {}
    /** 
     * Called to notify impression has been recorded for this ad. Note:Override this method to notify 
     * viewable impression to the Mediation Adapter. 
     * 
     * @param ad Represents the {@link InMobiNative} ad for which impression is recorded. 
     */
    public void onAdImpressed(InMobiNative ad) {}
    /** 
     * Called to notify ad was clicked. Note:Override this method to notify click to the Mediation Adapter. 
     * 
     * @param ad Represents the {@link InMobiNative} ad which was clicked 
     */
    public void onAdClicked(InMobiNative ad) {}
    /** 
     * Called to notify that the ad status has changed. 
     * 
     * @param nativeAd Represents the {@link InMobiNative} ad 
     */
    public void onAdStatusChanged(InMobiNative nativeAd) {}
}

VideoEventListener abstract class allows you to listen to video lifecycle events for a native ad.

/** 
 * A listener for receiving notifications during the lifecycle of a Native ad. 
 */
public abstract class VideoEventListener {
    /** 
     * Called to notify that the video has finished playing. 
     * 
     * @param ad Represents the {@link InMobiNative} ad 
     */
    public void onVideoCompleted(InMobiNative ad) {}
    /** 
     * Called to notify that the user has skipped video play. 
     * 
     * @param ad Represents the {@link InMobiNative} ad 
     */
    public void onVideoSkipped(InMobiNative ad) {}
    /** 
     * Called to notify when media audio state changes. 
     * 
     * @param isMuted Represents whether media is muted or not. 
     */
    public void onAudioStateChanged(InMobiNative inMobiNative, boolean isMuted) {}
}

Loading a Native Ad

To request for a native ad, call the load() method on the InMobiNative instance you created above:

nativeAd.load(); 

The NativeAdEventListener abstract class notifies the result of this method. If the ad request was successful, the onAdReceived(InMobiNative) event is generated. This is followed by either the onAdLoadSucceeded or the onAdLoadFailed event. If the onAdLoadFailed event is generated, the reason is indicated by the InMobiAdRequestStatus object passed in this event.


Listening to video events

To receive video events register videoEventListener using method setVideoEventListener (VideoEventListener videoEventListener) on the InMobiNative instance you created above:

nativeAd.setVideoEventListener (videoEventListener);

The VideoEventListener abstract class notifies you about video events for native ads.

Native Ad APIs

Following are the important APIs in InMobiNative that will help to stitch the ads:

  • View getPrimaryViewOfWidth(context, convertView, parent, width) - Returns a View of specified width (specified in actual pixels). This is the main ad content in your native ad. It will return a view of the same aspect ratio that you selected on the InMobi dashboard while creating the native placement. All impression render events are also fired automatically when this primary view is displayed on the screen.

    If you have selected Feed Layout while creating your placement, specify width = 25 while fetching your primaryView. It will just show the AdChoices icon and fire the ad render events.

    getPrimaryViewOfWidth(..) takes in four parameters:

    • context - The context in which ad is going to be rendered.
    • convertView - This is the complete view of a row of the ListView. You should not provide this as NULL because we use this parameter to recycle our ads effectively. This will allow for a smooth scroll performance.
    • parentView - This is the parent view inside which you will place the primaryView (which is returned by getPrimaryViewOfWidth() function). We need it for determining the layout parameters of Primary View.
    • adViewWidthInPixels - This is the width (in pixels) that you want the primaryView to take up.
  • String getAdTitle() - returns the string title for the ad.
  • String getAdDescription() - returns the string description for the ad.
  • String getAdIconUrl() - returns icon Image String URL for the ad.
  • String getAdCtaText() - returns Click to action string for the ad.
  • String getAdRating() - returns rating for the ad (optional).
  • String getAdLandingPageUrl() - returns landing URL for the ad.
  • boolean isAppDownload - returns true when the featured ad is from an app install advertiser.
  • boolean isReady() - True means the ad is ready to be displayed.
  • Boolean isVideo() - returns a Boolean if the ad returned contains a video or not, returns null if it is called in a wrong state.
  • void reportAdClickAndOpenLandingPage() - This function fires the click events and opens the landing page. You need not open landing page on your own while using this function.
  • JSONObject getCustomAdContent() - This function returns the JSONObject. This json have additional information (description, image URL, etc.), which can be used to create custom UI around the primary view of the ad.

Stitching a Native Ad

A native ad can be stitched in your app in three formats:

  • In-Feed ads
  • Splash ads
  • Pre-Roll ads

In-Feed Ad Integration

  1. Declare an ad position in your feed where you want to show ad.

    For example, to show ad at 4th position:

    private static final int AD_POSITION = 4; 
  2. If the ad load is successful, you will get a callback onAdLoadSucceeded(InMobiNative).You should then add the InMobiNativeAd object to your data source within this listener. If your feed in the app is a ListView, a sample implementation for ListView is shown below:

    @Override
    public void onAdLoadSucceeded(@NonNull InMobiNative nativeAd) {
        AdFeedItem nativeAdFeedItem = new AdFeedItem(nativeAd);
        mFeedItems.add(AD_POSITION, nativeAdFeedItem);
        mFeedAdapter.notifyDataSetChanged();
    }
    

    In the step above, AdFeedItem is an extension class of your FeedItem class, where FeedItem is the class which powers each row of your ListView. Also mItems is the ArrayList, which powers the Adapter of this ListView.
  3. So far, we have loaded an ad and added it to your data source. Now, it’s time to display the ad. The sample implementation for ListView is as follows:

    @Override
    public View getView(int position, View convertView, ViewGroup parent) {
        final int itemViewType = getItemViewType(position);
        if (itemViewType == VIEW_TYPE_CONTENT_FEED) {
            //Your app code 
        } else {
            //Since this content type is InMobi Ad, you need to get native Ad view 
            final InMobiNative nativeAd = ((AdFeedItem) feedItem).mNativeAd;
            View primaryView = nativeAd.getPrimaryViewOfWidth(context, convertView, parent, parent.getWidth());
            if (convertView == null) {
                convertView = mLayoutInflater.inflate(R.layout.ad_item, parent, false);
            }
            ((RelativeLayout) convertView.findViewById(R.id.primaryView)).addView(primaryView);
            ((TextView) convertView.findViewById(R.id.title)).setText(nativeAd.getTitle());
            ((TextView) convertView.findViewById(R.id.desc)).setText(nativeAd.getDescription());
            ((TextView) convertView.findViewById(R.id.cta)).setText(nativeAd.getCtaText());
            return convertView;
        }
    }
    

    The function getItemViewType(position) checks whether the content type is FEED OR AD as given below:

    @Override
    public int getItemViewType(int position) {
        FeedItem feedItem = getItem(position);
        if (feedItem instanceof AdFeedItem) {
            return VIEW_TYPE_INMOBI_STRAND;
        }
        return VIEW_TYPE_CONTENT_FEED;
    }
    

    We have used some of the APIs described in the section above to show the title, description, and CTA text of the ad. Similarly, the other APIs can be used to show the corresponding parts of the ad.


Splash Integration

Splash experience can be implemented using the same InMobiNative class. However, there are a few things to be noted:

  • You should use InMobiNativeAd.isReady() function to determine if the ad is ready to be shown. Sometimes, your main thread may be occupied and hence you may not receive onAdLoadSucceeded in time. Hence, it is better to proactively check if the ad is ready just after your cut-off time has elapsed.
  • IMPORTANT: You should NOT destroy or refresh the ad if the second screen of the ad is in display. You can check this in the onAdFullScreenDisplayed and not dismiss the ad if this callback is fired.

Sample implementation is as follows:

@Override
public void onAdFullScreenDisplayed(InMobiNative nativeAd) {
    isSecondScreenDisplayed = YES;
}
public void dismissAd() {
    if (isSecondScreenDisplayed) {
        Log.d(TAG, "DO NOT DISMISS THE AD WHILE THE SCREEN IS BEING DISPLAYED");
    } else {
        splashAdView.setVisibility(View.GONE);
        nativeAd.destroy();
    }
}

Pre-Roll Integration

Pre-Roll Video experience can be implemented using the same InMobiNative Class. You need to register videoEventListener and need to dismiss the ad view in the following callback:

@Override 
public void onVideoCompleted(@NonNull InMobiNative nativeAd) { 
    Log.d (TAG, "Media playback complete " + mPosition); 
}

The Pre-Roll ad can be dismissed as follows:

public void dismissAd() { 
    plashAdView.setVisibility(View.GONE); 
    nativeAd.destroy(); 
}

Refreshing the Native Ad

You will need to refresh the ad at various points to optimize ad exposure to your users. To refresh the ad, you will need to call the following functions in the exact order.

Note

It is important to remove the adFeedItem object from your data source and destroying it before refreshing. You will then need to create a new object and call load as shown in the following code:

private void refreshAd() {
    Iterator < FeedItems > feedItemIterator = mFeedItems.iterator();
    while (feedItemIterator.hasNext()) {
        final FeedItem feedItem = feedItemIterator.next();
        if (feedItem instanceof AdFeedItem) {
            feedItemIterator.remove();
        }
    }

    // refresh feed 
    mFeedAdapter.notifyDataSetChanged();
    // destroy InMobiNative object 
    inMobiNativeAd.destroy();
    // create InMobiNative object again 
    InMobiNative inMobiNativeAd = new InMobiNative( 
        << Activity Instance >> , 
        << Your Placement ID >> , 
        << InMobiNativeAdListener created in step 1 >> );
    inMobiNativeAd.load();
}

Managing the InMobiNative Instances

  1. Every instance of InMobiNative represents exactly one ad.
  2. If you want to place ad at multiple positions within a content feed, create as many instances of InMobiNative as the number of ad positions.
  3. You should create instances of InMobiNative in onCreate() callback of Activity or in onActivityCreated() callback of Fragment.
  4. You should destroy the InMobiNative instances in onDestroy() callback of Activity or in OnDestroyView() callback of Fragment.
  5. An InMobiNativeAd object must always be destroyed once you remove it from the data source. All user interactions with the ad view will not be honored after InMobiNativeAd is destroyed. So, you will have to definitely discard the ad view before destroying the InMobiNativeAd.
  6. All InMobiNativeAd instances must also be destroyed, when the component hosting them (your activity in this case) is getting destroyed using the destroy() API.

Click Tracking on the Ad Views

To have the InMobi SDK open the landing URL in addition to reporting a click, call the reportAdClickAndOpenLandingPage() method on the native ad instance:

nativeAd.reportAdClickAndOpenLandingPage(); 

Implementing Backfill

InMobi's SDK can run both HTML and native units against your native placement. You can run the following ad sizes depending on the real-estate reserved for your native placement.

  • 320x50 HTML Banner
  • 300x250 HTML Banner
  • 320x480 HTML Full screen Banner
  • 320x568 HTML Full screen Banner

To switch this on, you need to reach out to your respective partner manager with the preferred backfill size. Also, you will need to handle this in your code as follows:

@Override
public View getView(int position, View convertView, ViewGroup parent) {
    final int itemViewType = getItemViewType(position);
    if (itemViewType == VIEW_TYPE_CONTENT_FEED) {
        //Your app code 
    } else {
        //Since this content type is InMobi Ad, you need to get native Ad view 
        final InMobiNative nativeAd = ((AdFeedItem) feedItem).mNativeAd;
        //Detect whether its a backfill response or normal native 
        JSONObject customContent = currentNativeAd.getCustomAdContent();
        boolean isBackFillBanner = false;
        try {
            isBackFillBanner = customContent.getBoolean("isHTMLResponse");
        } catch (JSONException e) {
            isBackFillBanner = false;
        }
        if (isBackFillBanner) {
            View primaryView = nativeAd.getPrimaryViewOfWidth(context, convertView, parent, Math.round(getResources().getDisplayMetrics().density * 250));
            if (convertView == null) {
                convertView = mLayoutInflater.inflate(R.layout.ad_item, parent, false);
            }
            ((RelativeLayout) convertView.findViewById(R.id.primaryView)).addView(primaryView);
            return convertView;
        } else {
            View primaryView = nativeAd.getPrimaryViewOfWidth(context, convertView, parent, parent.getWidth());
            if (convertView == null) {
                convertView = mLayoutInflater.inflate(R.layout.ad_item, parent, false);
            }
            ((RelativeLayout) convertView.findViewById(R.id.primaryView)).addView(primaryView);
            ((TextView) convertView.findViewById(R.id.title)).setText(nativeAd.getTitle());
            ((TextView) convertView.findViewById(R.id.desc)).setText(nativeAd.getDescription());
            ((TextView) convertView.findViewById(R.id.cta)).setText(nativeAd.getCtaText());
            return convertView;
        }
    }
}

Note

  • To detect if the response is backfill, the customAdContent will contain the string isHTMLResponse.
  • Do NOT scale the width of the HTML banner response. For e.g. if you selected backfill of 300x250, make sure the provided width is hardcoded 250.
  • Do NOT add the CTA button in case of backfill response. The clicks will not be monetized in case you add this button alongside the ad.

On This Page

Last Updated on: 17 Feb, 2021