Skip to main content

Banner / MREC Ads

Ad Request​

Placement​

Create a BannerRequest.Builder instance, set BannerSize, placement id and other parameters, if applicable.

val bannerRequestBuilder = BannerRequest.Builder()
        .setPlacementId(...) // Set placement id
        .setSize(...) // Set BannerSize. Required
        .setTargetingParams(...) // Set TargetingParams instance
        .setPriceFloorParams(...) // Set price floor parameters
        .setLoadingTimeOut(...) // Set loading timeout in milliseconds

BannerSize​

BannerSize is a required parameter:

TypeSizeDescription
Size_320x50320x50Regular banner size.
Size_728x90728x90Banner size for tablets.
Size_300x250300x250MREC banner size.

General Request​

Set the BannerRequest.AdRequestListener instance to theBannerRequest.Builder instance.

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

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

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

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

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

val bannerRequest = bannerRequestBuilder.build()
Keep Ad Request

You need to keep reference to BannerRequest before calling BannerRequest#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:

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

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

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

or

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 BannerRequest.Builder:

bannerRequestBuilder.setBidPayload(String?)

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

val bannerRequest = bannerRequestBuilder.build()
Keep Ad Request

You need to keep reference to BannerRequest before calling BannerRequest#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 BannerRequest instance.

bannerRequest.request(...)
note

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

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

bannerRequest.destroy()
warning

Don't destroy the BannerRequest instance, if it will be used for load the BannerView instance or if the BannerView instance loaded with the BannerRequest 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 executing load on the BannerView instance, set up the BannerListener instance:

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

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

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

    override fun onAdExpired(ad: BannerView) {
        // Called when Ad expired
    }
  
})
bannerView.load(bannerRequest)

Loading and presenting banner ads​

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

bannerRequest.auctionResult != null

Use onAdLoaded callback to determine the possibility of displaying

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

bannerView.canShow()

To display the BannerView instance, you just need to add it to the layout.

viewGroup.removeAllViews()
viewGroup.addView(bannerView)

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

bannerView.destroy()
info

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