Nimbus Dynamic Unit

How to set up the Nimbus Dynamic Unit for inline ads

Creating hybrid ad request (Static & Video)

As described in the Android and iOS documentation, the SDK provides a helper method NimbusRequest.forInterstitialAd(...) that will generate a request for both a static and video ad.

// Class attribute
val nimbusAdManager: NimbusAdManager

// Rendering Ad
val request = NimbusRequest.forInterstitialAd("dynamic_unit_position")
manager.showAd(request, 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")
        }
    })

// Class properties
var adManager: NimbusAdManager?

// Rendering
let request = NimbusRequest.forInterstitialAd(position: "dynamic_unit_position")
adManager = NimbusAdManager()
adManager.delegate = self
            
adManager.showAd(
   request: request,
   container: containerView,
   adPresentingViewController: self
)

///////

// NimbusRequestManagerDelegate
extension YourViewController: NimbusRequestManagerDelegate {    
    func didCompleteNimbusRequest(request: NimbusRequest, ad: NimbusAd) {
        print("didCompleteNimbusRequest")
    }

    func didFailNimbusRequest(request: NimbusRequest, error: NimbusError) {
        print("didFailNimbusRequest: \(error.localizedDescription)")
    }
}

How to specify more ad sizes

The helper method above NimbusRequest.forInterstitialAd(...), facilitates the process of requesting and rendering an ad at the most common sizes for interstitial ads. It automatically uses the following ad sizes in its request:

Static Ads
- Portrait: 320x480
- Landscape: 480x320
Video Ads
- Device's width and height

Adding more ad sizes

When using the helper method above NimbusRequest.forInterstitialAd(...), ad sizes can be added to the request by accessing the banner object in the impression and adding additional sizes to the format array.

Any size smaller than 300x250 is invalid for this type of unit.

val params = forInterstitialAd("position").apply {
    request.imp[0].banner?.format = arrayOf(Format(350, 350))
}

let request = NimbusRequest.forInterstitialAd(position: "position")
request.impressions[0].banner?.formats = [NimbusAdFormat(width: 350, height: 350)]

Creative Scaling

The Nimbus Renderer has the ability to resize ads to fit their container. This happens automatically when rendering static display ads and video ads. Different rules may apply for each ad type, depending on its size and constraints.

Nimbus will attempt to scale ads to fully occupy the closest dimension of an ad’s container. For example, a 320x250 ad, rendered inside a 640x640 container, will be resized to 640x500 in order to maintain its aspect ratio. The ad will be rendered to fill all available width, resulting in a margin of 70 at the top and 70 at the bottom, centered vertically.

Static Display ads can be placed anywhere on the screen. They can be positioned absolutely at the top or bottom of the screen, or placed inside a container within a scrolling view between other native content (see above image). Some publishers prefer that the ad’s width matches native content above & below it. Others prefer the ad to fit the width of the screen. With Creative Scaling, the choice is yours.

The container in which an ad unit is placed will constrain the limits to which creative scaling is possible. Setting the size of the container to match one of the ad’s natural dimensions will prevent the ad from scaling in any direction. It’s also important to ensure that the container does not exceed the dimensions of the visible area on a device's screen. In order to count as a viewable impression, 100% of the ad must be visible on the screen.

Nimbus will never change the Ads aspect ratio or crop the ad creative. Keeping the aspect ratio is extremely important to guarantee that the quality of the ad is maintained and all pixels are in-view.

Troubleshooting

Static Display ads look straightforward, but include far more than the image visible in the campaign. They can often contain complex HTML markup created using templates on the buy-side of a programmatic advertising supply chain. There may be nested levels of divs, iframes, and rich media involved, or rigidly defined CSS styles that may lock the size and of a given component.

As a result, not every static display ad is guaranteed to scale successfully. Even the same ad campaign that scaled successfully from one demand source may appear in a campaign from a different demand source and not scale correctly. We would advise notifying the demand source from which the ad was served in order to correct the issue.

Companion End Cards

When using the helper method NimbusRequest.forInterstitialAd(...) the Nimbus SDK will automatically format the ad request to specify that an end card should be included for video ads. Therefore, if a video ad wins the auction, an end card will be present at the end of the video ad.

End cards do not apply to static ads.

The iOS SDK does not support end cards when using the helper method 'forInterstitialAd'.

Pre-Caching Ads

The only way to pre-cache an ad is by performing a manual request and rendering. This will load and render the ad before it is visible on-screen. Examples of how to do manual requesting and rendering can be found in our Sample Apps. An Android example and an iOS example can be found in our Sample App.

The best way to precache an ad would be to load it into a container that is added to the view hierarchy and mark it as invisible, and then wait for the AdController listener to fire the loaded event.

When the ad should be shown the view should be marked visible which will start the playback.

For non-MRAID Ads, it is recommended to set the Customizable Viewable Container (CVC) to zero. More details are in the section below.

Customizable Viewable Container

The Customizable Viewable Container feature only applies to non-MRAID static display ads. MRAID ads will automatically render when as defined by the MRAID spec implementation of each MRAID static display ad.

When loading static ads off-screen, you may define the percentage of the ad container that must be visible on-screen before the creative is rendered. This only applies for non-MRAID static creatives. The point of setting this value is to prevent "pop-in" or empty ad containers appearing on screen as the ad creative is downloaded during the rendering process.

The value ranges between 0% and 100% of the ad visible on-screen. The Nimbus SDK sets the default value at 25%. When using 0%, the ad will be rendered even when the ad container is not visible on screen at all. As a minimum value, we recommend using 1%, to at least guarantee that the container is visible when rendering is to start.

Nimbus.adVisibilityMinPercentage = <percentage value>

Nimbus.shared.adVisibilityMinPercentage = <percentage value>

Controls

Buttons, Timers

Only the Video Renderer will allow the following customizations

Using the AdsRenderingSettings/IMAAdsRenderingSettings from the IMA SDK you will be able to customize the items listed in their documentation. Instructions are available for Android and iOS.

In order to define some custom settings in the IMA player, you must create your own AdSettings following our Android and iOS documentation.

Volume

In order to manage ads' audio, please refer to our Android and iOS documentation.

Customization Options

Colors

Nimbus doesn't offer ways to set background colors or frames. To achieve that Publishers can define a container view with some internal padding, and define the color that they want as the background color. Remember that ads are going to be automatically scaled to fill in the container view, so the ad may not fill in the entire width or height as pointed out in the Section "Creative Scaling".

Last updated 3 months ago