Mediation

Load Ads

Creating Fullscreen Ads πŸ”—

The fullscreen APIs combine the existing Rewarded and Interstitial ad formats into a single integration experience.

To show a fullscreen ad, create a fullscreen ad load request using the Placement Name you set up on your Chartboost platform.

import ChartboostMediationSDK

// Fullscreen Ads

// Create the load request
let request = FullscreenAdLoadRequest(
    placement: "YOUR_FULLSCREEN_MEDIATION_PLACEMENT"
)

// Load the ad with the request
FullscreenAd.load(with: request) { result in
    if let error = result.error {
        // Handle error
    } else if let ad = result.ad {
        // Success
       ad.customData = "Y3VzdG9tIGRhdGE=" // base 64 encoded string for rewarded fullscreen ads
    } else {
        // Handle no ad error
    }
}

Ad Queueing πŸ”—

Ad queueing is a new feature for SDK 4.9.0+ that allows queueing up multiple fullscreen ads to show in succession. This can reduce and potentially eliminate latency for ad experiences that require showing fullscreen ads back to back.

Banners and adaptive banners cannot be queued.

// Define a delegate if you would like to be notified of ads being loaded/expiring
class QueueDelegate: FullscreenAdQueueDelegate {
    func fullscreenAdQueue(
        _ adQueue: FullscreenAdQueue,
        didFinishLoadingWithResult: ChartboostMediationAdLoadResult,
        numberOfAdsReady: Int
        ) {
        print("Queue for \(adQueue.placement) finished loading an ad.")
        print("There are now \(numberOfAdsReady) ads queued.")
    }

    func fullscreenAdQueueDidRemoveExpiredAd(
        _ adQueue: FullscreenAdQueue,
        numberOfAdsReady: Int
        ) {
        print("Queue for \(adQueue.placement) removed an expired ad.")
        print("\(numberOfAdsReady) ads remain queued.")
    }
}

// To get the queue for a specific placement
let queue = FullscreenAdQueue.queue(forPlacement: "YourPlacementID")

// Set the delegate
let queueDelegate = QueueDelegate()
queue.delegate = queueDelegate

// To start queueing ads, use the `start()` method
queue.start()

// After some time has elapsed or the delegate has
// notified of ads loaded into the queue, 
// use the `getNextAd()` method to get an ad from the queue
if let ad = queue.getNextAd() {
    ad.show(with: vc, completion: completion)
}

// Keywords can be set at any time, whether the queue is stopped or running.
// The next ad request sent by the running queue will use the keywords set here.
queue.keywords = ["key": "value"]

// The dashboard's queue size settings can be overridden at runtime.
// If this placement has a Queue Size setting of 2 and Max Queue Size
// is 4 or 5, this line of code will increase this queue's size to
// 4. But if Max Queue Size is smaller than the number passed to
// setQueueCapacity, the queue size will only be increased up to the
// allowed maximum. So if Max Queue Size is 3 then an error message
// will be logged and this queue's size will be changed to 3.
queue.setQueueCapacity(4)


// A running queue stops loading ads once it is full, but
// will load more ads to replace those that are removed.
// To stop requesting new ads, call `.stop()`
queue.stop()

Mediation SDK 4.6.0 introduces a new Adaptive Banner ad format, capable of serving flexible and fixed sized ads in the placement. The new Adaptive Banner ad format has the following features:

  • Choose whether to use Adaptive Ads or Fixed Ads in a given placement.
  • Fixed Ads are supported in Adaptive Ad placements (backwards compatible).
  • Know whether an ad is fixed or flexible and receive the dimensions of fixed ads.
  • Align the ad horizontally and/or vertically.
  • Resize the ad container to fit the ad or optionally discard oversized ads that are rendered in the container.
  • Ad container can be in-line or on top of publisher content.

To use this new ad format, Publishers will need to create a new Adaptive Banner placement in their platform and integrate with the new Adaptive Banner APIs.

Loading Banner ads πŸ”—

The API class ChartboostMediationBannerSize will support both fixed and adaptive banners.

The load call will provide the creative size of successfully loaded ads. If the returned width is -1, then it is a flexible width returned by the partner.

Field Description
standard Static constant that returns a fixed standard banner with a size of 320x50.
medium Static constant that returns a fixed medium/MREC banner with a size of 300x250.
leaderboard Static constant that returns a fixed leaderboard banner with a size of 728x90.
  • adaptive2x1(width: CGFloat)
  • adaptive4x1(width: CGFloat)
  • adaptive6x1(width: CGFloat)
  • adaptive8x1(width: CGFloat)
  • adaptive10x1(width: CGFloat)
  • adaptive1x2(width: CGFloat)
  • adaptive1x3(width: CGFloat)
  • adaptive1x4(width: CGFloat)
  • adaptive9x16(width: CGFloat)
  • adaptive1x1(width: CGFloat)
  • Additional conveniences to create sizes based on the IAB ratios (e.g. 6:1, 1:1) with a width. For example, using the 6:1 convenience with a 600 width would return a size of 600x100. Note that these are max sizes, therefore smaller sizes or other aspect ratios may be served.

    Loading Adaptive Banner Ads πŸ”—

    import ChartboostMediationSDK
    
    // Create the banner ad instance
    let bannerAd = BannerAdView()
    
    
    // Create the load request
    let request = BannerAdLoadRequest(
        placement: "YOUR_MEDIATION_PLACEMENT",
        size: .adaptive(width: SOME_WIDTH)  // see BannerSize for other options
    )
    
    // Load the ad with the request
    bannerAd.load(with: request, viewController: self) { result in
        if let error = result.error {
            // Handle error
        } else {
            // Success
        }
    }
    

    Loading Fixed Banner Ads πŸ”—

    import ChartboostMediationSDK
    
    // Create the banner ad instance
    let bannerAd = BannerAdView()
    
    
    // Create the load request with the desired fixed size
    // Fixed 320x50 standard banner
    let request = BannerAdLoadRequest(
        placement: "YOUR_MEDIATION_PLACEMENT",
        size: .standard
    )
    // Fixed 300x250 medium rectangle banner
    // let request = BannerAdLoadRequest(
    //     placement: "YOUR_MEDIATION_PLACEMENT",
    //     size: .medium
    // )
    // Fixed 720x90 leaderboard banner
    // let request = BannerAdLoadRequest(
    //     placement: "YOUR_MEDIATION_PLACEMENT",
    //     size: .leaderboard
    // )
    
    // Load the ad with the request
    bannerAd.load(with: request, viewController: self) { result in
        if let error = result.error {
            // Handle error
        } else {
            // Success
        }
    }
    

    Obtaining Winning Bid from Loaded Ads πŸ”—

    To obtain winning bid results from loaded ads, add a load call to BannerAdView. The BannerAdView.load() completion will provide a BannerAdLoadResult, which has an optional winning bid dictionary property @objc public var winningBidInfo: [String: Any]?. The completion is only triggered for the first manual load. Auto refresh loads do not trigger the completion.

    public func load(
        with request: BannerAdLoadRequest,
        viewController: UIViewController,
        completion: @escaping (BannerAdLoadResult) -> Void
    ) {
    

    To obtain winning bid results with each auto refresh load, utilize the banner ad delegate and query BannerAdView.winingBidInfo.

    Resizing Adaptive Banner Container πŸ”—

    func willAppear(bannerView: ChartboostMediationBannerView) {
    // Manual layout
    bannerView.frame.size = bannerView.size?.size ?? .zero
    
    // The alignment of the ad can be changed if the frame of the bannerView is larger than the ad.
    bannerView.horizontalAlignment = .left
    bannerView.verticalAlignment = .top
    
        // Auto-layout will automatically resize the bannerView based on the set constraints.
    }
    

    Receiving Creative Size πŸ”—

    To receive the creative size of successfully loaded ads, call the following. If the returned size is -1, then it is a flexible width returned by the partner.

    //ios
    bannerAd.load(with: request, viewController: self) { [weak self] result in
        let size = result.size
        // Do something with the size
    }
    

    Clearing Loaded Ads πŸ”—

    For any unused ads, we recommend invalidating them to free memory space.

    Note:

    • Calling reset will clear the loaded ad, remove the currently presented ad if any, and stop the auto-refresh process.
    • Calling reset after calling load, but before the load’s completion has been called, will result in completion not being called.
    FullscreenAd.invalidate()
    BannerAdView.reset()