Skip to main content

Native Ads

NativeRequest​

Setup NativeRequest builder​

To create a NativeRequest instance, you need to create a NativeRequest.Builder instance, set all the necessary parameters and call build on it.

TypeDescription
MediaAssetType.AllCombination of Icon, Image and Video
MediaAssetType.IconOnly icon assets will be downloaded and displayed
MediaAssetType.ImageOnly image assets will be downloaded and displayed
MediaAssetType.VideoOnly video assets will be downloaded and displayed

You can also combine MediaAssetType by listing the list of required assets.

info

By default required assets are MediaAssetType.Icon and MediaAssetType.Image

val nativeRequestBuilder = NativeRequest.Builder()
        .setMediaAssetTypes(...) // Set MediaAssetTypes
        .setTargetingParams(...) // Set TargetingParams instance
        .setPriceFloorParams(...) // Set price floor parameters
        .setSessionAdParams(...) // Set SessionAdParams instance
        .setLoadingTimeOut(...) // Set loading timeout in milliseconds
        .setPlacementId(...) // Set placement id

Set AdRequestListener​

Set the NativeRequest.AdRequestListener instance to theNativeRequest.Builder instance.

nativeRequestBuilder.setListener(object : NativeRequest.AdRequestListener {
    
    /**
     * Called when NativeRequest was requested successfully
     *
     * @param request       - NativeRequest instance
     * @param auctionResult - AuctionResult info
     */
    override fun onRequestSuccess(request: NativeRequest,
                                  auctionResult: AuctionResult) {

    }

    /**
     * Called when NativeRequest request failed
     *
     * @param request - NativeRequest instance
     * @param error   - BMError with additional info about error
     */
    override fun onRequestFailed(request: NativeRequest,
                                 error: BMError) {

    }

    /**
     * Called when NativeRequest expired
     *
     * @param request - NativeRequest instance
     */
    override fun onRequestExpired(request: NativeRequest) {

    }
  
})
caution

AdRequestListener callbacks are delivered on the background thread, not the main one.

Build NativeRequest​

When all the necessary parameters are set, call build on the NativeRequest.Builder instance:

val nativeRequest = nativeRequestBuilder.build()
Keep ad request

You need to keep reference to NativeRequest before calling NativeRequest.request, otherwise it is possible it will be cleared by Garbage Collector and callbacks won’t be triggered.

Request NativeRequest​

When you need to request an ad and get an AuctionResult, call request on the NativeRequest instance.

nativeRequest.request(...)
info

If you have an in-house meditation and you decide that an advertisement from BidMachine will be shown - call nativeRequest.notifyMediationWin, if BidMachine loses the mediation - call nativeRequest.notifyMediationLoss

Destroy NativeRequest​

Destroy the NativeRequest instance if you don't need it anymore.

nativeRequest.destroy()
caution

Don't destroy the NativeRequest instance, if it will be used for load the NativeAd instance or if the NativeAd instance loaded with the NativeRequest instance has not been shown yet. Otherwise, ad will not work correctly, which can affect a lower display rate, fill rate, rendering errors, and as a result - lower revenue.

NativeAd​

Load NativeAd​

When you would like to load and display requested Ads:

  • Make sure that the NativeRequest instance has AuctionResult. It means the ads have been requested successfully.
nativeRequest.auctionResult != null
  • Make sure that theNativeRequest instance not expired.
!nativeRequest.isExpired

Before execute load on the NativeAd instance set the NativeListener instance:

val nativeAd = NativeAd(...)
nativeAd.setListener(object : NativeListener {
    
    /**
     * Called when Ad was loaded and ready to be displayed
     *
     * @param ad - NativeAd instance
     */
    override fun onAdLoaded(ad: NativeAd) {

    }

    /**
     * Called when Ad failed to load
     *
     * @param ad    - NativeAd instance
     * @param error - BMError with additional info about error
     */
    override fun onAdLoadFailed(ad: NativeAd,
                                error: BMError) {

    }

    /**
     * Called when Ad Impression has been tracked
     *
     * @param ad - NativeAd instance
     */
    override fun onAdImpression(ad: NativeAd) {

    }
    
    /**
     * Called when Ad show failed
     *
     * @param ad    - NativeAd instance
     * @param error - BMError with additional info about error
     */
    override fun onAdShowFailed(ad: NativeAd,
                                error: BMError) {
    
    }
    
    /**
     * Called when Ad has been clicked
     *
     * @param ad - NativeAd instance
     */
    override fun onAdClicked(ad: NativeAd) {

    }

    /**
     * Called when Ad expired
     *
     * @param ad - NativeAd instance
     */
    override fun onAdExpired(ad: NativeAd) {

    }
  
})
nativeAd.load(nativeRequest)

Use onAdLoaded callback to determine the possibility of displaying.

Show NativeAd​

Before displaying, check if the NativeAd instance can be displayed:

nativeAd.canShow()

To display the NativeAd instance, you need:

  • Create layout
  • Fill NativeAdContentLayout by NativeAd
  • Register NativeAdContentLayout for interaction

Create layout​

Create layout which should be contain NativeAdContentLayout with filled attributes, which contains views IDs. These IDs are required to identify and fill views with an ad.

AttributeDescription
titleViewIdReference to the view that will contain the title data
descriptionViewIdReference to the view that will contain the description data
ratingViewIdReference to the view that will contain the rating data
callToActionViewIdReference to the view that will contain the CTA data
iconViewIdReference to the view that will contain the icon
providerViewIdReference to the view that will contain the view that provides DAA
mediaViewIdReference to the view that will contain the main image or video

Example of NativeAdContentLayout layout:

<?xml version="1.0" encoding="utf-8"?>
<io.bidmachine.nativead.view.NativeAdContentLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:id="@+id/native_item"
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:callToActionViewId="@+id/btnCta"
    app:descriptionViewId="@+id/txtDescription"
    app:iconViewId="@+id/icon"
    app:mediaViewId="@+id/mediaView"
    app:providerViewId="@+id/providerView"
    app:ratingViewId="@+id/ratingBar"
    app:titleViewId="@+id/txtTitle">
 
    <RelativeLayout
        android:layout_width="match_parent"
        android:layout_height="match_parent">
 
        <LinearLayout
            android:id="@+id/native_ad"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:orientation="horizontal">
 
            <ImageView
                android:id="@+id/icon"
                android:layout_width="90dp"
                android:layout_height="90dp"
                android:layout_gravity="center_vertical"
                android:layout_margin="5dp" />
 
            <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:orientation="horizontal">
 
                    <TextView
                        android:id="@+id/txtTitle"
                        android:layout_width="0dp"
                        android:layout_height="wrap_content"
                        android:layout_margin="5dp"
                        android:layout_weight="1"
                        android:ellipsize="end"
                        android:textSize="16sp" />
 
                    <TextView
                        android:id="@+id/tv_ad"
                        android:layout_width="wrap_content"
                        android:layout_height="wrap_content"
                        android:layout_gravity="center_vertical"
                        android:layout_margin="5dp"
                        android:text="Ad"
                        android:textSize="14sp" />
 
                </LinearLayout>
 
                <TextView
                    android:id="@+id/txtDescription"
                    android:layout_width="match_parent"
                    android:layout_height="wrap_content"
                    android:layout_margin="5dp"
                    android:ellipsize="end"
                    android:maxLines="3" />
 
                <LinearLayout
                    android:layout_width="match_parent"
                    android:layout_height="wrap_content"
                    android:orientation="horizontal">
 
                    <LinearLayout
                        android:layout_width="0dp"
                        android:layout_height="wrap_content"
                        android:layout_gravity="center_vertical"
                        android:layout_weight="1"
                        android:orientation="horizontal">
 
                        <RatingBar
                            android:id="@+id/ratingBar"
                            style="?android:attr/ratingBarStyleSmall"
                            android:layout_width="wrap_content"
                            android:layout_height="wrap_content"
                            android:isIndicator="true" />
                    </LinearLayout>
 
                    <Button
                        android:id="@+id/btnCta"
                        android:layout_width="wrap_content"
                        android:layout_height="wrap_content"
                        android:minHeight="30dp" />
 
                </LinearLayout>
 
            </LinearLayout>
 
        </LinearLayout>
 
        <FrameLayout
            android:id="@+id/providerView"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:layout_alignStart="@id/native_ad"
            android:layout_alignLeft="@id/native_ad"
            android:layout_alignBottom="@id/native_ad" />
 
        <io.bidmachine.nativead.view.NativeMediaView
            android:id="@+id/mediaView"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:layout_below="@+id/native_ad" />
 
    </RelativeLayout>
 
</io.bidmachine.nativead.view.NativeAdContentLayout>
val nativeAdContentLayout = LayoutInflater.from(this)
    .inflate(android.R.layout.include_native_ads, nativeAdParent, false) as NativeAdContentLayout

Fill NativeAdContentLayout by NativeAd​

After creation NativeAdContentLayout, you need to fill the views with data from NativeAd.

nativeAdContentLayout.bind(nativeAd)

Register NativeAdContentLayout for interaction​

In order to prepare the NativeAdContentLayout for display, you need to call registerViewForInteraction on it.

nativeAdContentLayout.registerViewForInteraction(nativeAd)

You can unregister view if view is out of screen now.

nativeAdContentLayout.unregisterViewForInteraction()

Destroy NativeAd​

After ad was successful shown and no longer needed, it can be destroyed.

nativeAdContentLayout.destroy()
note

You can find code examples written in Java and Kotlin: Github Native