Requesting

In this article, you will understand how to properly request ads for Nimbus, with details explaining all information that may be passed to the Nimbus SDK.

Now that you've configured the Nimbus SDK within your project, you can begin to request ads. Ad requests are made up of JSON objects generated using the NimbusRequest class and NimbusAdManager.

Configure global request information

The NimbusAdManager can be configured globally to send information that applies to every request. The information will be added to the NimbusRequest object when NimbusAdManager.showAd(...) is called.

Session ID

A random UUID is generated for the Session ID when Nimbus is first initialized. The Session ID can be overridden with any unique string by calling:

Nimbus.sessionId = "any_unique_session_id";

User Information

We recommend adding any available User information using NimbusAdManager.setUser(). Calling setUser() multiple times will replace the User object with the new value.

NimbusAdManager.setUser(User(
    age = 32,
    yob = 1990,
    gender = User.FEMALE,
))

Ad Blocking

Currently, the Android SDK is able to handle dynamically injected Blocked Advertisers (badv).

NimbusAdManager.setBlockedAdvertiserDomains()

The Nimbus Dashboard provides a fully functional ad blocking UI that can block by Categories, Advertisers, and Apps - we recommend that all blocks take place at this level instead of at both the SDK and UI level. The UI should ALWAYS be the source of truth. Double blocking may result in unwanted loss in revenue.

We recommend that only advanced publishing partners utilize the dynamic blocking functionality within the SDKs, as having blocks in multiple channels will increase complexity and complications.

Notes

• The UI does not allow for top level blocks, only IAB subcategories. If a top level block is sent through via the SDKs, we will respect that top level block and pass it through to our demand partners.

• The Nimbus system utilizes a unique merge and will merge both the SDK blocks as well as the UI blocks. This is why it’s important to only block in one location.

Create the NimbusRequest

The NimbusRequest class is an implementation of the OpenRTB BidRequest object that contains information about the type of ad that should be shown. We provide helper methods to automatically populate the request object with default values for a particular ad type.

Position

The first parameter of each helper method defines the name of the ad unit as it will appear on the Nimbus Dashboard. We recommend using a descriptive name for each ad unit / placement combination within your app to make it easier to measure the performance of different ad units. A best practice here is to ensure that the cardinality of this field remains low, so as too not generate too many unique position names.

Interstitial Ads

Nimbus supports multiple creative types for interstitial ad units. The helper method forInterstitialAd() will generate a request for both a video and static display ad.

val request = NimbusRequest.forInterstitialAd("interstitial_position_name")

Banner Ads

The helper method forBannerAd will generate a request for a static display / "banner" ad. The second parameter of the helper method defines the size of the requested ad while the third argument defines where it will appear on the screen. This is the recommended way to generate a request for 320 by 50 banner ads and can also be used for other static display ad sizes.

val request = NimbusRequest.forBannerAd("banner_position_name", Format.BANNER_320_50, Position.FOOTER)

Video Ads

The helper method NimbusRequest.forVideoAd(...) will generate a request for video ad.

val request = NimbusRequest.forVideoAd("video_ad_name")

Rewarded Video

The helper method NimbusRequest.forRewardedVideo(...) will generate a request for rewarded video ad.

val request = NimbusRequest.forRewardedVideo("video_ad_name")

Native Ads

Nimbus Android SDK (2.15.0+) comes with native ads support for some of our demand partners SDKs. We recommend you check out the demand partners documentation (e.g. Vungle # Native Ads ) before requesting a native ad. The following helpers should used to either create or enrich your requests to get a native ad.

Create a native ad request

The helper method NimbusRequest.forNativeAd(...)will generate a native ad request. Let's have a closer look at the first three parameters:

1. position: Position / identifier of the ad

2. size: Size of the native ad. Pass one of the NativeAdSize enum cases. Defaults to medium (300x250)

3. includeVideo: When set to true, the ad can optionally return a video as well. Defaults to false.

The following code would create a native ad request that supports both, a native banner and a native video:

NimbusRequest.forNativeAd(position: "native_hybrid_ad_name", size: NativeAdSize.
Medium, includeVideo: true)

Enrich an existing request

It's possible to request a native ad as part of an existing NimbusRequest. If your application can handle both a banner or a native ad, you can use addNativeAd(...) helper to have Nimbus automatically select the best available ad:

NimbusRequest.forBannerAd(position, Format.BANNER_300_250).addNativeAd(Medium)

Make the Request

Finally, call NimbusAdManager.showAd() with your NimbusRequest, ViewGroup, and Renderer.Listener

This will return an AdController on a successful request. See how to interact with the AdController in the next step.