Load Ads

Creating Fullscreen Ads 🔗

The new Fullscreen APIs combine the existing Rewarded and Interstitial ad formats with the new Rewarded Interstitial ad format into a single integration experience. The older APIs have been marked deprecated, but are still functional until the 5.0.0 SDK release.

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

  • let request = ChartboostMediationAdLoadRequest(placement: "<placement>", keywords: <keywords>)
    Helium.shared().loadFullscreenAd(with: request) { result in
        if let ad = result.ad {
            // The ad is ready to show
        } else if let error = result.error {
            // Handle the error
  • ChartboostMediationAdLoadRequest *request = [[ChartboostMediationAdLoadRequest alloc] initWithPlacement:@"<placement" keywords:<keywords>];
    [[Helium sharedHelium] loadFullscreenAdWithRequest:request completion:^(ChartboostMediationFullscreenAdLoadResult *result) {
        if (result.ad != nil) {
            // The ad is ready to show
        } else if (result.error != nil) {
            // Handle the 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
    // 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.
    // 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()`

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:

  • Publishers can choose whether to use Adaptive Ads or Fixed Ads in a given placement.
  • Fixed Ads are supported in Adaptive Ad placements (backwards compatible).
  • Publishers should know whether an ad is fixed or flexible and receive the dimensions of fixed ads.
  • Publishers can align the ad horizontally and/or vertically.
  • Publishers can resize the ad container to fit the ad or optionally discard oversized ads that are rendered in the container.
  • The 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:

Field Description
static standard: ChartboostMediationBannerSize Static constant that returns a fixed STANDARD banner with a size of 320x50.
static medium: ChartboostMediationBannerSize Static constant that returns a fixed MREC MEDIUM banner with a size of 300x250.
static leaderboard: ChartboostMediationBannerSize Static constant that returns a fixed LEADERBOARD banner with a size of 728x90.
let type: ChartboostMediationBannerType An enum specifying that the ad size is fixed (size cannot change), or adaptive (size can change but must maintain aspectRatio). This is an integer based enum.
let size: CGSize The size of the ad.
var aspectRatio: CGFloat The aspect ratio of the ad. This can be derived from the size. Will be 0 if either the width or the height are <= 0.
static func adaptive(width: CGFloat) Creates a flexible/adaptive banner size with 0 height.
static func adaptive(width: CGFloat, maxHeight: CGFloat) Creates a flexible/adaptive banner size with a width and max height. Used either when the height of an inline ad should be capped, or when requesting an anchored banner.
<additional conveniences>
  • static func adaptive2x1(width: CGFloat) -> ChartboostMediationBannerSize
  • static func adaptive4x1(width: CGFloat) -> ChartboostMediationBannerSize
  • static func adaptive6x1(width: CGFloat) -> ChartboostMediationBannerSize
  • static func adaptive8x1(width: CGFloat) -> ChartboostMediationBannerSize
  • static func adaptive10x1(width: CGFloat) -> ChartboostMediationBannerSize
  • static func adaptive1x2(width: CGFloat) -> ChartboostMediationBannerSize
  • static func adaptive1x3(width: CGFloat) -> ChartboostMediationBannerSize
  • static func adaptive1x4(width: CGFloat) -> ChartboostMediationBannerSize
  • static func adaptive9x16(width: CGFloat) -> ChartboostMediationBannerSize
  • static func adaptive1x1(width: CGFloat) -> ChartboostMediationBannerSize
  • This provides 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.
    • let banner = ChartboostMediationBannerView()
      banner.delegate = self
      // Determine the max size of ad to load.
      let size = ChartboostMediationBannerSize.adaptive(width: <MAX_WIDTH>, maxHeight: <MAX_HEIGHT>)
      // Create a request with the size and your placement name.
      let request = ChartboostMediationBannerLoadRequest(
      placement: "<PLACEMENT_NAME>",
      size: size
      // Load the banner ad.        
      banner.load(with: request, viewController: self) { [weak self] result in
      // Handle result

    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.

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

    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.

    Creating Banner Ads 🔗

    To show a banner ad, declare a variable to hold a reference to the Banner Mediation Ad and supply the corresponding Placement Name and Banner Size.

    • var bannerAd: HeliumBannerView?
    • @property (nonatomic) MediationBannerView *bannerAd;
    Banner Enum Dimensions (Width x Height)
    Standard (320 x 50)
    Medium (300 x 250)
    Leaderboard (728 x 90)
    • /*
           The following Banner enum Sizes can be passed down:
      /// Mediation banner ad instance must be retained for the lifetime of the ad.
      var bannerAd: HeliumBannerView?
      if bannerAd == nil {
          let bannerSize = CHBHBannerSize.standard
          self.bannerAd = Helium.shared().bannerProvider(with: self, andPlacementName: "MY_BANNER_PLACEMENT", andSize: bannerSize)
    • /*
           The following Banner enum Sizes can be passed down:
      /// Helium banner ad instance must be retained for the lifetime of the ad.
      @property (nonatomic, strong) HeliumBannerView *bannerAd;
      if (self.bannerAd == nil) {
        CHBHBannerSize bannerSize = CHBHBannerSize_Standard;
        self.bannerAd = [HeliumSdk.sharedHelium bannerProviderWithDelegate:self andPlacementName:@"MY_BANNER_PLACEMENT" andSize:bannerSize];

    Loading Banner Ads 🔗

    To create an instance for each Placement Name you want to use make the following call to load the ad:

    • if let bannerAd = bannerAd {
          bannerAd.load(with: viewControllerForModalContent)
    • if (self.bannerAd != nil) {
        [self.bannerAd loadAdWithViewController:viewControllerForModalContent];

    Clearing Loaded Ads 🔗

    Clearing loaded ads may be necessary on existing placements to request another ad (i.e. for an in-house programmatic auction).

    Clearing Interstitial and Rewarded Ads 🔗

    • interstitialAd?.clearLoadedAd()
    • [self.interstitialAd clearLoadedAd];
      [self.rewardedAd clearLoadedAd];

    Clearing Banner Ads 🔗

    This will clear the currently displayed ad and any cached ad loaded for an auto refresh.

    • bannerAd?.clear()
    • [self.bannerAd clearAd];