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.

  • // While in a coroutine
    val adRequest = ChartboostMediationAdLoadRequest(
       placementName = [Your Placement Name],
       keywords = Keywords(),
    )
    
    val loadResult = HeliumSdk.loadFullscreenAd(
           context,
           adRequest,
           object : ChartboostMediationFullscreenAdListener {
               override fun onAdImpressionRecorded(ad: ChartboostMediationFullscreenAd) {
                   // Impression
               }
    
               override fun onAdClicked(ad: ChartboostMediationFullscreenAd) {
                   // Clicked
               }
    
               override fun onAdRewarded(ad: ChartboostMediationFullscreenAd) {
                   // Rewarded
               }
    
               override fun onAdExpired(ad: ChartboostMediationFullscreenAd) {
                   // Expired
               }
    
               override fun onAdClosed(
                   ad: ChartboostMediationFullscreenAd,
                   error: ChartboostMediationAdException?
               ) {
                   // Closed
               }
           }
       )
    }
    
    
  • ChartboostMediationAdLoadRequest adRequest = new ChartboostMediationAdLoadRequest([Your Placement Name], new Keywords());
    
    HeliumSdk.loadFullscreenAdFromJava(
           context,
           adRequest,
           new ChartboostMediationFullscreenAdListener() {
               public void onAdImpressionRecorded(@NonNull ChartboostMediationFullscreenAd ad) {
                   // Impression
               }
    
               public void onAdClicked(@NonNull ChartboostMediationFullscreenAd ad) {
                   // Clicked
               }
    
               public void onAdRewarded(@NonNull ChartboostMediationFullscreenAd ad) {
                   // Rewarded
               }
    
               public void onAdExpired(@NonNull ChartboostMediationFullscreenAd ad) {
                   // Expired
               }
    
               public void onAdClosed(
                   @NonNull ChartboostMediationFullscreenAd ad,
                   @Nullable ChartboostMediationAdException error) {
                   // Closed
               }
           },
           new ChartboostMediationFullscreenAdLoadListener() {
               public void onAdLoaded(@NonNull ChartboostMediationFullscreenAd ad) {
                   // Loaded
               }
           }
       )
    }
    
    

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.

  • // Create a Chartboost Mediation fullscreen ad queue with the ad queue manager. The manager returns a ChartboostMediationFullscreenAdQueue.
    val queue: ChartboostMediationFullscreenAdQueue = ChartboostMediationFullscreenAdQueueManager.queue(context, placementName)
    
    // To listen to ad queue events, you can use the ChartboostMediationFullscreenAdQueueListener
    queue.adQueueListener = object : ChartboostMediationFullscreenAdQueueListener {
        override fun onFullScreenAdQueueUpdated(
            adQueue: ChartboostMediationFullscreenAdQueue,
            result: AdLoadResult,
            numberOfAdsReady: Int,
        ) {
            println(
                "Fullscreen ad queue updated${
                    if (result.error != null) {
                        " with error: ${result.error?.cause}"
                    } else {
                        ""
                    }
                }. Number of ads ready: $numberOfAdsReady",
            )
        }
    
        override fun onFullscreenAdQueueExpiredAdRemoved(
            adQueue: ChartboostMediationFullscreenAdQueue,
            numberOfAdsReady: Int,
        ) {
            println("Fullscreen ad queue removed an expired ad. Number of ads ready: $numberOfAdsReady")
        }
    }
    
    // To start queueing ads, use the `start()` method.
    queue.start()
    
    // To check if the queue is running, query the read-only `isRunning` property.
    queue.isRunning
    
    // To check if there's an ad in the queue, use the `hasNextAd()` method.
    // To get an ad from the queue, use the `getNextAd()` method.
    CoroutineScope(Main).launch {
      if (queue.hasNextAd) {
        val ad = queue.nextAd()
        // Showing an ad needs to be in a suspend function.
        // Be mindful that ads will need to be reattached to your ChartboostMediationFullscreenAdListener if you are listening to ad cycle events.
        ad?.listener = fullscreenAdListener()
        ad?.show(context)
      }
    }
    
    // To stop the queue, use the `stop()` method.
    queue.stop()
    
    // To set a queue capacity, use the queueCapacity property.
    queue.queueCapacity = 3
    
  • // Create a Chartboost Mediation fullscreen ad queue with the ad queue manager. The manager returns a ChartboostMediationFullscreenAdQueue.
    ChartboostMediationFullscreenAdQueue queue = ChartboostMediationFullscreenAdQueueManager.queue(context, placementName)
    
    // To listen to ad queue events, you can use the ChartboostMediationFullscreenAdQueueListener
    final ChartboostMediationFullscreenAdQueueListener fullscreenAdQueueListener = new ChartboostMediationFullscreenAdQueueListener() {
        @Override
        public void onFullScreenAdQueueUpdated(@NonNull ChartboostMediationFullscreenAdQueue adQueue, @NonNull AdLoadResult result, int numberOfAdsReady) {
            System.out.println("Fullscreen ad queue has been updated for placement " + placementName + ". Number of ads ready to show: " + numberOfAdsReady);
        }
    
        @Override
        public void onFullscreenAdQueueExpiredAdRemoved(@NonNull ChartboostMediationFullscreenAdQueue adQueue, int numberOfAdsReady) {
            System.out.println("Fullscreen ad queue expired ad has been removed for placement " + placementName + ". Number of ads ready to show: " + numberOfAdsReady);
        }
    };
    
    // Attach the created ChartboostMediationFullscreenAdQueueListener with the setAdQueueListener() method.
    queue.setAdQueueListener(fullscreenAdQueueListener);
    
    // To start queueing ads, use the `start()` method.
    queue.start()
    
    // To check if the queue is running, query the `isRunning()` method.
    queue.isRunning()
    
    // To check if there's an ad in the queue, use the `hasNextAd()` method.
    // To get an ad from the queue, use the `getNextAd()` method.
    if (queue.hasNextAd()) {
      ChartboostMediationFullscreenAd ad = queue.getNextAd()
      if (ad != null) {
        // Be mindful that ads will need to be reattached to your ChartboostMediationFullscreenAdListener if you are listening to ad cycle events.
        ad.setListener(fullscreenAdListener())  
        ad.showFullscreenAdFromJava(context, result -> {});
      } else {
        System.out.println("Fullscreen ad is null. Load an ad first.");
      }
    }
    
    // To stop the queue, use the `stop()` method.
    queue.stop()
    
    // To set a queue capacity, use the `setQueueCapacity(int value)` method.
    // 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(3)
    

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 HeliumBannerSize will support both fixed and adaptive banners:

Field Description
HeliumBannerAd.HeliumBannerSize.Companion.STANDARD Static constant that returns a fixed STANDARD banner with a size of 320x50.
HeliumBannerAd.HeliumBannerSize.Companion.MEDIUM Static constant that returns a fixed MREC MEDIUM banner with a size of 300x250.
HeliumBannerAd.HeliumBannerSize.Companion.LEADERBOARD Static constant that returns a fixed LEADERBOARD banner with a size of 728x90.
fun getAdType(): Int An enum specifying that the ad size is either fixed (size cannot change) or adaptive (size can change but must maintain aspectRatio). This is an integer based enum.
fun getSize(): HeliumBannerSize Get the size of the ad.
val aspectRatio: Double 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.
fun bannerSize(width: Int) Creates a flexible/adaptive banner size with 0 height.
fun bannerSize(width: Int, height: Int): HeliumBannerSize 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>
  • fun adaptive2x1(width: Int): HeliumBannerSize
  • fun adaptive4x1(width: Int): HeliumBannerSize
  • fun adaptive6x1(width: Int): HeliumBannerSize
  • fun adaptive8x1(width: Int): HeliumBannerSize
  • fun adaptive10x1(width: Int): HeliumBannerSize
  • fun adaptive1x2(width: Int): HeliumBannerSize
  • fun adaptive1x3(width: Int): HeliumBannerSize
  • fun adaptive1x4(width: Int): HeliumBannerSize
  • fun adaptive9x16(width: Int): HeliumBannerSize
  • fun adaptive1x1(width: Int): HeliumBannerSize
  • 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.
    • // To load an adaptive 6x1 ad (with width 300dp)
      heliumBannerAd.load(placement, HeliumBannerSize.adaptive6x1(300))
          // You can pass in another size or the old non-adaptive sizes such as HeliumBannerSize.STANDARD
      
      // To listen for refreshes
      val listener: HeliumBannerAdListener = object : HeliumBannerAdListener {
          fun onAdViewAdded(placementName: String, child: View?) {
              // notified that a view is added.
          }
          // other callbacks didn't change
      }
      heliumBannerAd.heliumBannerAdListener = listener
      

    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.

    • val listener: HeliumBannerAdListener = object : HeliumBannerAdListener {
      
      // An overload for the existing onAdCached function that provides an 
      // additional parameter, the banner size. By default this calls the 
      // currently implemented onAdCached
      fun onAdCached(
              placementName: String,
              loadId: String,
              winningBidInfo: Map<String, String>,
              error: ChartboostMediationAdException?,
              bannerSize: Size
      )
      // the other callbacks have not changed
      }
      

    Resizing Adaptive Banner Container πŸ”—

    • val density = context.resources.displayMetrics.density
      heliumBannerAd.layoutParams = ViewGroup.LayoutParams(
                          300 * density,
                          50 * density
                      )
      // If you want this to be automatic, just use WRAP_CONTENT for
      // both width and height.
      heliumBannerAd.layoutParams = ViewGroup.LayoutParams(
                          ViewGroup.LayoutParams.WRAP_CONTENT,
                          ViewGroup.LayoutParams.WRAP_CONTENT
                      )
      // You can change this anytime. The next ad will use these sizes.
      
      // To get the size of the currently showing creative, see:
      heliumBannerAd.getCreativeSizeDips()
      

    Discarding Oversized Ads πŸ”—

    The setShouldDiscardOversizedAds will allow you the option to discard or allow ads larger than what is set for HeliumBannerSize.

    • // To drop oversized ads
      HeliumSdk.setShouldDiscardOversizedAds(true)
      
      // To allow oversized ads
      HeliumSdk.setShouldDiscardOversizedAds(false)
      

    Creating Banner Ads πŸ”—

    There are two ways to create banners on Android:

    • programmatically
    • XML

    The following banner sizes can be passed down. Some partners may not fill for some banner sizes.

    Banner Enum Dimensions (Width & Height)
    Standard 320 x 50
    Medium 300 x 250
    Leaderboard 728 x 90

    Create Banner Ads Programmatically πŸ”—

    The following Fixed Ad Size APIs are deprecated starting SDK 4.6.0 but are still supported

    1. Declare a variable to hold a reference to the Banner Mediation Ad.
    2. Supply the corresponding Placement Name and Banner Size
    • /*
        The following Banner enum Sizes can be passed down:
        HeliumBannerAd.HeliumBannerSize.STANDARD
        HeliumBannerAd.HeliumBannerSize.MEDIUM
        HeliumBannerAd.HeliumBannerSize.LEADERBOARD
      */
      val bannerSize = HeliumBannerAd.HeliumBannerSize.STANDARD
      val heliumBannerAd = new HeliumBannerAd(context, placementName, bannerSize, bannerListener)
      
    • ...
        <com.chartboost.heliumsdk.ad.HeliumBannerAd
            android:id="@+id/bannerAd"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            tools:layout_height="50dp"
            app:heliumBannerSize="STANDARD"
            app:heliumPlacementName="PlacementName" />
      ...
      

    Loading Banner Ads πŸ”—

    For Mediation SDK 3.0.0:

    • load() returns a String representing the load request identifier. This return value is optional to consume.
    • Banners are now automatically shown. Add this banner view to the view hierarchy and the ads will automatically be shown.

    You will need to create an ad instance for each placement name you want to use. Finally, make the call to load the ad:

    • // load() returns a String representing the load request identifier.
      heliumBannerAd.load()
      
    • // load() returns a String representing the load request identifier.
      heliumBannerAd.load();
      

    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 πŸ”—

    • heliumInterstitialAd.clearLoaded()
      heliumRewardedAd.clearLoaded()
      
    • heliumInterstitialAd.clearLoaded();
      heliumRewardedAd.clearLoaded();
      

    Clearing Banner Ads πŸ”—

    For Mediation SDK 3.0.0 on banners:

    • Call clearAd() to clear the currently displayed and cached banner ad.
    • // To clear currently showing and any cached ad loaded for auto refresh.
      heliumBannerAd.clearAd()
      
    • // To clear currently showing and any cached ad loaded for auto refresh.
      heliumBannerAd.clearAd();
      

    The 3.x.x clearAd and 2.x.x clearLoaded API returns a boolean and indicates if the ad object has been cleared and is ready for another load call.