Interstitial Ads

Ad Request

Placement

Create a InterstitialRequest.Builder instance, set AdContentType, placement id and other parameters, if applicable.

Java

InterstitialRequest.Builder interstitialRequestBuilder = new InterstitialRequest.Builder()
        .setPlacementId(...) // Set placement id
        .setAdContentType(...) // Set AdContentType
        .setTargetingParams(...) // Set TargatingParams instance
        .setPriceFloorParams(...) // Set price floor parameters
        .setLoadingTimeOut(...) // Set loading timeout in milliseconds

Kotlin

val interstitialRequestBuilder = InterstitialRequest.Builder()
        .setPlacementId(...) // Set placement id
        .setAdContentType(...) // Set AdContentType
        .setTargetingParams(...) // Set TargatingParams instance
        .setPriceFloorParams(...) // Set price floor parameters
        .setLoadingTimeOut(...) // Set loading timeout in milliseconds

AdContentType

Type	Description
AdContentType.All	Flag to request both Video and Static ad content types.
AdContentType.Static	Flag to request Static ad content type only.
AdContentType.Video	Flag to request Video ad content type only.

info

By default AdContentType is AdContentType.All

General Request

Set the InterstitialRequest.AdRequestListener instance to the InterstitialRequest.Builder instance.

Java

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

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

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

Kotlin

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

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

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

note

AdRequestListener callbacks run on a background thread, not on the main thread.

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

Java

InterstitialRequest interstitialRequest = interstitialRequestBuilder.build();

Kotlin

val interstitialRequest = interstitialRequestBuilder.build()

Keep ad request

You need to keep reference to InterstitialRequest before calling InterstitialRequest.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 InterstitialRequest.Builder:

Java

interstitialRequestBuilder.setBidPayload(@Nullable String);

Kotlin

interstitialRequestBuilder.setBidPayload(String?)

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

Java

InterstitialRequest interstitialRequest = interstitialRequestBuilder.build();

Kotlin

val interstitialRequest = interstitialRequestBuilder.build()

Keep ad request

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

Java

interstitialRequest.request(...);

Kotlin

interstitialRequest.request(...)

info

When you made an in-house meditation and you decided that an advertisement from BidMachine will be shown - call interstitialRequest.notifyMediationWin, if BidMachine lost in mediation - call interstitialRequest.notifyMediationLoss

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

Java

interstitialRequest.destroy();

Kotlin

interstitialRequest.destroy()

caution

Don't destroy the InterstitialRequest instance, if it will be used for load the InterstitialAd instance or if the InterstitialAd instance loaded with the InterstitialRequest 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 InterstitialAd instance set the InterstitialListener instance:

Java

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

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

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

    @Override
    public void onAdClicked(@NonNull InterstitialAd ad) {
        // Called when Ad has been clicked
    }
  
    @Override
    public void onAdClosed(@NonNull InterstitialAd ad,
                           boolean finished) {
        // Called when Ad was closed (e.g - user clicked the close button)
        // finished indicates if the ad was finished (e.g - video playing completed)
    }

    @Override
    public void onAdExpired(@NonNull InterstitialAd ad) {
        // Called when Ad expired
    }
  
});
interstitialAd.load(interstitialRequest);

Kotlin

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

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

    override fun onAdImpression(ad: InterstitialAd) {
        // Called when Ad Impression has been tracked
    }
    
    override fun onAdShowFailed(ad: InterstitialAd,
                                error: BMError) {
        // Called when Ad show failed
    }
      
    override fun onAdClicked(ad: InterstitialAd) {
        // Called when Ad has been clicked
    }
  
    override fun onAdClosed(ad: InterstitialAd,
                            finished: Boolean) {
        // Called when Ad was closed (e.g - user clicked the close button)
        // finished indicates if the ad was finished (e.g - video playing completed)        
    }

    override fun onAdExpired(ad: InterstitialAd) {
        // Called when Ad expired
    }
  
})
interstitialAd.load(interstitialRequest)

Loading and presenting interstitial ads

Make sure that the InterstitialRequest instance have AuctionResult. It's mean ads requested successfully.

Java

interstitialRequest.getAuctionResult() != null

Kotlin

interstitialRequest.auctionResult != null

Use onAdLoaded callback to determine the possibility of displaying.

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

Java

interstitialAd.canShow();

Kotlin

interstitialAd.canShow()

To display the InterstitialAd instance, you just need to execute show.

Java

interstitialAd.show();

Kotlin

interstitialAd.show()

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

Java

interstitialAd.destroy();

Kotlin

interstitialAd.destroy()

info

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