Native Ads

Ad Request

Placement

Create a NativeRequest.Builder instance, set MediaAssetType list, placement id and other parameters, if applicable.

Java

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

Kotlin

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

MediaAssetType

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.

info

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

General Request

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

Java

nativeRequestBuilder.setListener(new NativeRequest.AdRequestListener() {
    
    @Override
    public void onRequestSuccess(@NonNull NativeRequest request,
                                 @NonNull AuctionResult auctionResult) {
        // Called when NativeRequest was requested successfully                            
    }

    @Override
    public void onRequestFailed(@NonNull NativeRequest request,
                                @NonNull BMError error) {
        // Called when NativeRequest request failed                            
    }

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

Kotlin

nativeRequestBuilder.setListener(object : NativeRequest.AdRequestListener {
    
    override fun onRequestSuccess(request: NativeRequest,
                                  auctionResult: AuctionResult) {
        // Called when NativeRequest was requested successfully                            
    }

    override fun onRequestFailed(request: NativeRequest,
                                 error: BMError) {
        // Called when NativeRequest request failed                          
    }

    override fun onRequestExpired(request: NativeRequest) {
        // Called when NativeRequest expired
    }
  
})

caution

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

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

Java

NativeRequest nativeRequest = nativeRequestBuilder.build();

Kotlin

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.

Client Bidding Request

Bid Token

With S2S integration, you will need a BidToken that you need to transfer in the request.

Define AdPlacementConfig:

Java

AdPlacementConfig adPlacementConfig = new AdPlacementConfig.Builder(AdsFormat)
  .withPlacementId(...) // Set placement id
  .build();

Kotlin

val adPlacementConfig = AdPlacementConfig.Builder(AdsFormat)
  .withPlacementId(...) // Set placement id
  .build()

To get a BidToken, you can use one of 2 methods:

Java

// Must be run on background thread
String bidToken = BidMachine.getBidToken(@NonNull Context, @NonNull AdPlacementConfig);

Kotlin

// Must be run on background thread
val bidToken = BidMachine.getBidToken(Context, AdPlacementConfig)

or

Java

BidMachine.getBidToken(@NonNull Context, @NonNull AdPlacementConfig, new BidTokenCallback() {
    @Override
    public void onCollected(@NonNull String bidToken) {
        // The BidToken will be returned on a background thread
    }
});

Kotlin

BidMachine.getBidToken(Context, AdPlacementConfig) { bidToken ->
    // The BidToken will be returned on a background thread
}

Bid Payload

After completing the server-side auction, you will receive a Base64-encoded payload string, which must be passed as a parameter to the NativeRequest.Builder:

Java

nativeRequestBuilder.setBidPayload(@Nullable String);

Kotlin

nativeRequestBuilder.setBidPayload(String?)

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

Java

NativeRequest nativeRequest = nativeRequestBuilder.build();

Kotlin

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.

Ad Display

Prepare the Ad Request object

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

Java

nativeRequest.request(...);

Kotlin

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 the NativeRequest instance if you don't need it anymore.

Java

nativeRequest.destroy();

Kotlin

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.

Define Ad Listener

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

Java

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

    @Override
    public void onAdLoadFailed(@NonNull NativeAd ad,
                               @NonNull BMError error) {
        // Called when Ad failed to load                          
    }

    @Override
    public void onAdImpression(@NonNull NativeAd ad) {
        // Called when Ad Impression has been tracked
    }
  
    @Override
    public void onAdShowFailed(@NonNull NativeAd ad,
                               @NonNull BMError error) {
        // Called when Ad show failed                        
    }
  
    @Override
    public void onAdClicked(@NonNull NativeAd ad) {
        // Called when Ad has been clicked
    }

    @Override
    public void onAdExpired(@NonNull NativeAd ad) {
        // Called when Ad expired
    }
  
});
nativeAd.load(nativeRequest);

Kotlin

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

    override fun onAdLoadFailed(ad: NativeAd,
                                error: BMError) {
        // Called when Ad failed to load                          
    }

    override fun onAdImpression(ad: NativeAd) {
        // Called when Ad Impression has been tracked
    }
    
    override fun onAdShowFailed(ad: NativeAd,
                                error: BMError) {
        // Called when Ad show failed                          
    }
    
    override fun onAdClicked(ad: NativeAd) {
        // Called when Ad has been clicked
    }

    override fun onAdExpired(ad: NativeAd) {
        // Called when Ad expired
    }
  
})
nativeAd.load(nativeRequest)

Define Layout

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>

Java

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

Kotlin

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.

Java

nativeAdContentLayout.bind(nativeAd);

Kotlin

nativeAdContentLayout.bind(nativeAd)

Register NativeAdContentLayout for interaction

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

Java

nativeAdContentLayout.registerViewForInteraction(nativeAd);

Kotlin

nativeAdContentLayout.registerViewForInteraction(nativeAd)

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

Java

nativeAdContentLayout.unregisterViewForInteraction();

Kotlin

nativeAdContentLayout.unregisterViewForInteraction()

Loading and presenting native ads

Make sure that the NativeRequest instance has AuctionResult. It means the ads have been requested successfully.

Java

nativeRequest.getAuctionResult() != null

Kotlin

nativeRequest.auctionResult != null

Use onAdLoaded callback to determine the possibility of displaying.

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

Java

nativeAd.canShow();

Kotlin

nativeAd.canShow()

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

Java

nativeAdContentLayout.destroy();

Kotlin

nativeAdContentLayout.destroy()

note

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