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.

NimbusAdManager

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(...) which has multiple signatures for different scenarios.

NimbusAdManager will not play video ads unless the ad is on screen. It will also pause a video ad if the app is backgrounded.

Make sure that the NimbusAdManager instance is long-lived for the delegate's callbacks to be triggered.

Show an inline ad attached to your layout

For the `containerView` param you can either pass a view that already exists in your layout or create a new view, which must be added to the layout hierarchy with its size and position defined.

// Class properties
var adManager: NimbusAdManager? // Please make sure Nimbus.shared.initialize is called before this

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

Show an inline ad that automatically refreshes

// Class properties
var adManager: NimbusAdManager? // Please make sure Nimbus.shared.initialize is called before this

// Rendering
let request = NimbusRequest.forBannerAd(position: "test_banner")
adManager = NimbusAdManager()
adManager.delegate = self

adManager.showAd(
   request: request, 
   container: containerView, 
   refreshInterval: 30, 
   adPresentingViewController: self
)

Show a full-screen blocking ad

Use the parameter `closeButtonDelay` to define the delay before showing the close button in seconds. Defaults to 5 seconds.

// Class properties
var adManager: NimbusAdManager? // Please make sure Nimbus.shared.initialize is called before this

// Rendering
let request = NimbusRequest.forInterstitialAd(position: "test_interstitial")
adManager = NimbusAdManager()
adManager.delegate = self

adManager.showBlockingAd(
   request: request,
   closeButtonDelay: 10,
   adPresentingViewController: self
)

Show a rewarded video ad

Rewarded ads work similarly to full-screen blocking ads with the difference that, for video ads, the close button will only appear after the ad completes.

// Class properties
var adManager: NimbusAdManager? // Please make sure Nimbus.shared.initialize is called before this

// Renderinglet request = NimbusRequest.forInterstitialAd(position: "test_rewarded_static")           
adManager = NimbusAdManager()
adManager.delegate = self

adManager.showRewardedAd(request: request, adPresentingViewController: self)

Controlling Playback

AdController is used to control ad behavior like starting and stopping ads or controlling the volume.

A delegate can be set on NimbusAdManager that will return an ad controller.

// Class properties
var adController: AdController?
var adManager: NimbusAdManager?

// Initialization
// Please make sure Nimbus.shared.initialize is called before this

adManager = NimbusAdManager()
adManager.delegate = self

// view: UIView

adManager.showAd(
  request: NimbusRequest.forInterstitialAd(position: "position"),
  container: view,
  adPresentingViewController: self
)

// MARK: NimbusAdManagerDelegate

func didCompleteNimbusRequest(request: NimbusRequest, ad: NimbusAd) {
    // Request completed with the given ad
}

func didFailNimbusRequest(request: NimbusRequest, error: NimbusError) {
    // Nimbus request failed due to an error or no bid
}

func didRenderAd(request: NimbusRequest, ad: NimbusAd, controller: AdController) {
    // Ad received and is ready to be shown. Optionally listen for ad events on the controller
    self.adController = controller
    self.adController.delegate = self
    self.adController.volume = 50
}

// MARK: AdControllerDelegate

func didReceiveNimbusEvent(controller: AdController, event: NimbusEvent) {
    // Receive events like `loaded`, `impression`, `clicked`
}

/// Received an error for the ad
func didReceiveNimbusError(controller: AdController, error: NimbusError) {
    // Errors thrown related to ad rendering
}

Events

AdControllers will fire events to its delegate. These events provide signals to the developer as the ad moves through its lifecycle. The delegate must be set in the callback `didRenderAd` from the NimbusAdManagerDelegate.

// Class properties
var adController: AdController?
var adManager: NimbusAdManager?

// Initializtion
// Please make sure Nimbus.shared.initialize is called before this
adManager = NimbusAdManager()
adManager.delegate = self

// Render function
adManager.showAd(
  request: NimbusRequest.forInterstitialAd(position: "position"),
  container: view,
  adPresentingViewController: self
)

// MARK: NimbusAdManagerDelegate

func didRenderAd(request: NimbusRequest, ad: NimbusAd, controller: AdController) {
    // Ad received and is ready to be shown. Optionally listen for ad events on the controller
    self.adController = controller
    self.adController.delegate = self
}

// MARK: AdControllerDelegate

func didReceiveNimbusEvent(controller: AdController, event: NimbusEvent) {
    // Receive events like `loaded`, `impression`, `clicked`
}

/// Received an error for the ad
func didReceiveNimbusError(controller: AdController, error: NimbusError) {
    // Errors thrown related to ad rendering
}

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
resumed - A Video ad has been resumed
firstQuartile - 25% of the video ad has been played
midpoint - 50% of the video ad has been played
thirdQuartile - 75% of the video ad has been played
completed - Video ad has been completed
destroyed - The ad has been destroyed

firstQuartile, midpoint, and thirdQuartile events will only fire for video ad units.

Destroying an Ad

There may be cases where you need to manually destroy the Ad. By default, ads are destroyed when their container view is deallocated.

// Please make sure Nimbus.shared.initialize is called before this
private let adManager = NimbusAdManager()
private var adController: AdController?

func showNimbusAd(_ request: NimbusRequest, with vc: UIViewController) {
   adManager.delegate = self
   adManager.showAd(
      request: request,
      container: contentView,
      adPresentingViewController: vc
   )
}
    
// To destroy the ad call the following line
adController?.destroy()

    
// MARK: NimbusAdManagerDelegate
    
func didRenderAd(request: NimbusRequest, ad: NimbusAd, controller: AdController) {
   print("didRenderAd")
   self.adController = controller
}
    
func didCompleteNimbusRequest(request: NimbusRequest, ad: NimbusAd) {
   print("didCompleteNimbusRequest")
}
    
func didFailNimbusRequest(request: NimbusRequest, error: NimbusError) {
   print("didFailNimbusRequest")
}

Customize Rendering

Mute button

Video ads can be configured to optionally include a mute button.

import NimbusRenderVideoKit

let videoRenderer = NimbusVideoAdRenderer()
videoRenderer.showMuteButton = true
Nimbus.shared.renderers = [.forAuctionType(.video): videoRenderer]

IMA SDK rendering

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

Currently supported IMA SDK version is 3.16.3 but other versions may work.

import NimbusKit
import GoogleInteractiveMediaAds

final class YourVideoSettingsProvider: NimbusVideoSettingsProvider {

    /// `IMAAdsLoader` used for rendering video ad
    override func adsLoader() -> IMAAdsLoader {
        let loader = super.adsLoader()
        // Configure loader as needed
        return loader
    }

    /// `IMAAdsRenderingSettings` used for rendering video ad
    override func adsRenderingSettings() -> IMAAdsRenderingSettings {
        let settings = super.adsRenderingSettings()
        // Configure settings as needed
        return settings
    }
}

var videoAdRenderer = NimbusVideoAdRenderer()
videoAdRenderer.videoAdSettingsProvider = YourVideoSettingsProvider()

Nimbus.shared.renderers[.forAuctionType(.video)] = videoAdRenderer

After completing the steps above, you have completed the basic Nimbus integration and your app will be able to render ads.

Last updated 3 months ago