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, 
    new NimbusAdManager.Listener() {

    @Override
    public void onAdResponse(NimbusResponse nimbusResponse) {
        // Ad Response successfully received
    }

    @Override
    public void onAdRendered(AdController controller) {
        // Ad successfully loaded, attach an event listener to listen to ad events
    }

    @Override
    public void onError(NimbusError error) {
        // Handle error
    }
});

// To show an inline ad that automatically refreshes; the minimum refresh interval is 20 seconds
int refreshIntervalSeconds = 20;
manager.showAd(NimbusRequest.forBannerAd("test_banner", Format.BANNER_320_50, Position.FOOTER), refreshIntervalSeconds, 
    layout, new NimbusAdManager.Listener() {

    @Override
    public void onAdResponse(NimbusResponse nimbusResponse) {
        // Ad Response successfully received
    }

    @Override
    public void onAdRendered(AdController controller) {
        // Ad successfully loaded, attach an event listener to listen to ad events
    }

    @Override
    public void onError(NimbusError error) {
        // Handle error
    }
});

// To show a blocking ad
manager.showBlockingAd(NimbusRequest.forInterstitialAd("position"), activity, new NimbusAdManager.Listener() {

    @Override
    public void onAdResponse(NimbusResponse nimbusResponse) {
        // Ad Response successfully received
    }

    @Override
    public void onAdRendered(AdController controller) {
        // Ad successfully loaded, attach an event listener to listen to ad events
    }

    @Override
    public void onError(NimbusError error) {
        // Handle error
    }
})

// To show a rewarded video ad
manager.showRewardedAd(NimbusRequest.forRewardedVideoAd("position"), 15 /* Close button delay in seconds */,
    activity, new NimbusAdManager.Listener() {

    @Override
    public void onAdResponse(NimbusResponse nimbusResponse) {
       // Ad Response successfully received
    }

    @Override
    public void onAdRendered(AdController controller) {
       // Ad successfully loaded, attach an event listener to listen to ad events
    }

    @Override
    public void onError(NimbusError error) {
       // 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(new AdController.Listener() { 

     @Override
    public void onAdEvent(AdEvent adEvent) {
        // Handle events
    }

    @Override
    public void onError(NimbusError error) {
        // Handle errors
    }
})

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.