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 iOS 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 overwritten with any unique string by calling:

Nimbus.shared.sessionId = "any_unique_session_id"

User Information

We recommend adding any available User information using NimbusAdManager .

NimbusAdManager.user = NimbusUser(age: 20, gender: .male)

Ad Blocking

The SDK is able to handle dynamically injected Blocked Advertisers (badv).

NimbusAdManager.blockedAdvertisingDomains = [URL(string: "https://blockedDomain.com")!]

The Nimbus Dashboard also 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 struct 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

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

let request = NimbusRequest.forInterstitialAd(position: "interstitial_position_name")

Banner

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

let request = NimbusRequest.forBannerAd(position: "banner_position_name", format: .banner320x50, position: .footer)

Video

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

let request = NimbusRequest.forVideoAd(position: "video_ad_name")

Rewarded Video

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

let request = NimbusRequest.forRewardedVideo(position: "rewarded_video_position_name")

Native Ads

Nimbus iOS SDK (2.18.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 be 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 NimbusNativeSize enum cases. Defaults to medium (300x250)

3. includeVideo: If you're open to requesting a native video ad, you should set this parameter to true. Defaults to false.

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

let request = NimbusRequest.forNativeAd(position: "native_ad_position_name", size: .medium, includeVideo: true)

Enrich an existing request

It's possible to request a native ad as part of an existing NimbusRequest. Let's say you want to request a banner, but you're open to getting a native ad back as well, it's easily done using addNativeAd(...) helper:

let request = NimbusRequest.forBannerAd(position: "banner_ad_position_name", format: .letterbox).addNativeAd()

Perform the Request

Finally, call NimbusAdManager.showAd(...) with your NimbusRequest.

NimbusAdManagerDelegate.didShowNimbusAd(...) will return an AdController on a successful request which can be used to interact with the ad.

Point to your existing server

Nimbus iOS SDK can send bid requests to your existing server very easily.

NimbusAdManager.requestUrl = URL(string: "https://api.myserver.com")!

NimbusAdManager.showAd(...) will now send the requests to your server going forward.

After completing the steps above, your application will be able to start rendering ads.