Native

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.

Type	Description
MediaAssetType.All	Combination of Icon, Image and Video
MediaAssetType.Icon	Only icon assets will be downloaded and displayed
MediaAssetType.Image	Only image assets will be downloaded and displayed
MediaAssetType.Video	Only video assets will be downloaded and displayed

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

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

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

val nativeRequestBuilder = NativeRequest.Builder()
        .setMediaAssetTypes(...) // Set MediaAssetTypes
        .setTargetingParams(...) // Set TargatingParams 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(new NativeRequest.AdRequestListener() {
    
    /**
     * Called when NativeRequest was requested successfully
     *
     * @param request       - NativeRequest instance
     * @param auctionResult - AuctionResult info
     */
    @Override
    public void onRequestSuccess(@NonNull NativeRequest request,
                                 @NonNull AuctionResult auctionResult) {

    }

    /**
     * Called when NativeRequest request failed
     *
     * @param request - NativeRequest instance
     * @param error   - BMError with additional info about error
     */
    @Override
    public void onRequestFailed(@NonNull NativeRequest request,
                                @NonNull BMError error) {
        
    }

    /**
     * Called when NativeRequest expired
     *
     * @param request - NativeRequest instance
     */
    @Override
    public void onRequestExpired(@NonNull NativeRequest request) {
        
    }
  
});

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

    }
  
})

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

NativeRequest nativeRequest = nativeRequestBuilder.build();

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(...);

nativeRequest.request(...)

📘
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();

nativeRequest.destroy()

❗️
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.getAuctionResult() != null

nativeRequest.auctionResult != null

Make sure that theNativeRequest instance not expired.

!nativeRequest.isExpired()

!nativeRequest.isExpired

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

NativeAd nativeAd = new NativeAd(...);
nativeAd.setListener(new NativeListener() {
    
    /**
     * Called when Ad was loaded and ready to be displayed
     *
     * @param ad - NativeAd instance
     */
    @Override
    public void onAdLoaded(@NonNull NativeAd ad) {

    }

    /**
     * Called when Ad failed to load
     *
     * @param ad    - NativeAd instance
     * @param error - BMError with additional info about error
     */
    @Override
    public void onAdLoadFailed(@NonNull NativeAd ad,
                               @NonNull BMError error) {

    }

    /**
     * Called when Ad Impression has been tracked
     *
     * @param ad - NativeAd instance
     */
    @Override
    public void onAdImpression(@NonNull NativeAd ad) {

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

    }

    /**
     * Called when Ad expired
     *
     * @param ad - NativeAd instance
     */
    @Override
    public void onAdExpired(@NonNull NativeAd ad) {

    }
  
});
nativeAd.load(nativeRequest);

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

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.

Attribute	Description
titleViewId	Reference to the view that will contain the title data
descriptionViewId	Reference to the view that will contain the description data
ratingViewId	Reference to the view that will contain the rating data
callToActionViewId	Reference to the view that will contain the CTA data
iconViewId	Reference to the view that will contain the icon
providerViewId	Reference to the view that will contain the view that provides DAA
mediaViewId	Reference 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>

NativeAdContentLayout nativeAdContentLayout = (NativeAdContentLayout) LayoutInflater.from(this)
        .inflate(R.layout.include_native_ads, nativeAdParent, false);

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

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

nativeAdContentLayout.registerViewForInteraction(nativeAd)

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

nativeAdContentLayout.unregisterViewForInteraction();

nativeAdContentLayout.unregisterViewForInteraction()

Destroy NativeAd

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

nativeAdContentLayout.destroy();

nativeAdContentLayout.destroy()

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

Native

NativeRequest

Setup NativeRequest builder

📘

Set AdRequestListener

🚧

Build NativeRequest

❗️
Keep ad request

Request NativeRequest

📘

Destroy NativeRequest

❗️

NativeAd

Load NativeAd

Show NativeAd

Create layout

Fill NativeAdContentLayout by NativeAd

Register NativeAdContentLayout for interaction

Destroy NativeAd

📘
Sample

NativeRequest

Setup NativeRequest builder

📘

Set AdRequestListener

🚧

Build NativeRequest

❗️Keep ad request

Request NativeRequest

📘

Destroy NativeRequest

❗️

NativeAd

Load NativeAd

Show NativeAd

Create layout

Fill NativeAdContentLayout by NativeAd

Register NativeAdContentLayout for interaction

Destroy NativeAd

📘Sample

❗️
Keep ad request

📘
Sample