Rendering

In this article, you will understand how to properly render ads into your app, with details explaining how to show ads, control its playback, listen to events, and destroy ads.

Rendering

The Nimbus SDK provides out of the box support for rendering static WebView and native video ad units in a unified auction. This is made possible using the AdController interface which can be obtained from the NimbusAdManager class.

NimbusAdManager

The NimbusAdManager combines the requesting and the rendering components of the Nimbus SDK into a single entry point to request an ad. To start a request for a new Ad, call NimbusAdManager.showAd() by passing in a NimbusRequest, a ViewGroup, and NimbusAdManager.Listener which will receive callbacks when an AdController is ready and the ad has been attached to the view hierarchy. The error callback on the NimbusAdManager.Listener will be called if there was no bid on the request or an error occurred during the rendering of the ad.

To show an inline ad attached to your layout

manager.showAd(NimbusRequest.forBannerAd("test_banner", Format.BANNER_320_50, Position.FOOTER), layout,
    object : NimbusAdManager.Listener {
        override fun onAdResponse(nimbusResponse: NimbusResponse) {
            TODO("Ad response successfully received")
        }

        override fun onAdRendered(controller: AdController) {
            TODO("Ad successfully loaded, attach an event listener to listen to ad events")
        }

        override fun onError(error: NimbusError) {
            TODO("Handle error")
        }
    })

To show an inline ad that automatically refreshes

val refreshIntervalSeconds: Int = 30
manager.showAd(NimbusRequest.forBannerAd("test_banner", Format.BANNER_320_50, Position.FOOTER),
    refreshIntervalSeconds, layout, object : NimbusAdManager.Listener {
        override fun onAdRendered(controller: AdController) {
            TODO("Refreshing successfully loaded, attach an event listener to listen to ad events")
        }

        override fun onAdResponse(nimbusResponse: NimbusResponse) {
            TODO("Ad has received the next winning bid")
        }

        override fun onError(error: NimbusError) {
            if (error.errorType == ErrorType.NO_BID) {
                TODO("Nimbus did not bid")
            } else TODO("Handle errors")
        }
    })

To show a full-screen blocking ad

manager.showBlockingAd(NimbusRequest.forInterstitialAd("position"), activity, object : NimbusAdManager.Listener {
    override fun onAdResponse(nimbusResponse: NimbusResponse) {
        TODO("Ad response successfully received")
    }

    override fun onAdRendered(controller: AdController) {
        TODO("Ad successfully loaded, attach an event listener to listen to ad events")
    }

    override fun onError(error: NimbusError) {
        TODO("Handle error")
    }
})

To show a rewarded video ad

val closeButtonDelayInSeconds = 15
manager.showRewardedAd(NimbusRequest.forRewardedVideoAd("position"), closeButtonDelayInSeconds, activity,
    object : NimbusAdManager.Listener {

        override fun onAdResponse(nimbusResponse: NimbusResponse) {
            TODO("Ad response successfully received")
        }

        override fun onAdRendered(controller: AdController) {
            TODO("Ad successfully loaded, attach an event listener to listen to ad events")
        }

        override fun onError(error: NimbusError) {
            TODO("Handle error")
        }
    })

Blocking Ad Rendering Options

To configure settings for blocking ads, see the documentation for BlockingAdRenderer

Interacting with Ad Controllers

AdControllers returned by the showAd() method will attach to the view hierarchy after a successful response from Nimbus is rendered. By default, AdControllers manage the playback of ads, starting and stopping playback based on the visibility of the ad and the app transitioning from the foreground to the background and vice versa. Full screen interstitial ads will immediately begin playback when the ad has rendered; ads displayed in a scrolling container will start playback as the ad is moving on the screen and stop playback as the ad scrolls away.

Events

AdControllers will fire events to any AdController.Listener objects attached to the controller. These events provide signals to the developer as the ad moves through its lifecycle. To add a listener to a controller, use the AdController.listeners() method to add and remove listeners.

controller.listeners().add(object : AdController.Listener {
    override fun onAdEvent(adEvent: AdEvent) {
        TODO("Listen to ad events")
    }

    override fun onError(error: NimbusError) {
        TODO("An error was thrown, the AdController should be destroyed after this")
    }
})

It fires events like this:

• LOADED - the ad has loaded and returned an AdController

• IMPRESSION - the ad has registered an impression

• CLICKED - User clicked through on an ad

• PAUSED - A video ad has been paused

• RESUME - A Video ad has been resumed

• FIRST_QUARTILE - 25% of the video ad has been played

• MIDPOINT - 50% of the video ad has been played

• THIRD_QUARTILE - 75% of the video ad has been played

• COMPLETED - Video ad has completed

• VOLUME_CHANGED - Volume has changed in the ad, call getVolume() for current volume

• DESTROYED - The ad has been destroyed

Note: the FIRST_QUARTILE, MIDPOINT, and THIRD_QUARTILE events will only fire for video ad units.

Controlling Playback

To stop the playback of an ad, call AdControlller.stop() which will fire a PAUSED event if the ad had already started playback; to resume playback of an ad, call AdController.start() which will fire a RESUMED event.

It is safe to call start() and stop() multiple times as the AdController will internally manage the state of the ad; however, this is not ideal and should be avoided.

Destroying an Ad

When an ad is no longer needed, call AdController.destroy() to destroy the ad. This will remove all listeners from the AdController and any attached views from the View hierarchy. While it is safe to call this method multiple times, subsequent calls will be ignored.

Customize Rendering

IMA SDK rendering

Additionally, IMA SDK video settings can be configured to render video ads.

val videoRenderer = Renderer.INLINE.get("video") as? VideoAdRenderer
videoRenderer?.renderingSettings?.apply {
  // Edit settings here.
}