Load Ads

Loading Fullscreen Ads πŸ”—

Starting in Chartboost Mediation Unity SDK 4.3.X, we have deprecated the previous approach for loading fullscreen placement ads. A new Fullscreen API has been provided for interstitials, rewarded videos and rewarded interstitials. The new API makes use of C# asycn/await methods in order to await for load and show.

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

// Strong reference to cached ad.
private IChartboostMediationFullscreenAd _fullscreenPlacement;

...
// keywords are optional
var keywords = new Dictionary<string, string> { { "i12_keyword1", "i12_value1" } };

// Create a Fullscreen Ad Load Request
var loadRequest = new ChartboostMediationFullscreenAdLoadRequest(FULLSCREEN_PLACEMENT, keywords);

// Subscribing Instance Delegates
loadRequest.DidClick += fullscreenAd => Log($"DidClick Name: {fullscreenAd.Request.PlacementName}");

loadRequest.DidClose += (fullscreenAd, error) => 
Debug.Log(!error.HasValue ? $"DidClose Name: {fullscreenAd.Request.PlacementName}"
: $"DidClose with Error. Name: {fullscreenAd.Request.PlacementName}, Code: {error?.Code}, Message: {error?.Message}");

loadRequest.DidReward += fullscreenAd => Log($"DidReward Name: {fullscreenAd.Request.PlacementName}");

loadRequest.DidRecordImpression += fullscreenAd => Log($"DidImpressionRecorded Name: {fullscreenAd.Request.PlacementName}");

loadRequest.DidExpire += fullscreenAd => Log($"DidExpire Name: {fullscreenAd.Request.PlacementName}");

// Await on FullscreenAd Load
var loadResult = await ChartboostMediation.LoadFullscreenAd(loadRequest);


// Failed to Load
if (loadResult.Error.HasValue)
{
    Debug.Log($"Fullscreen Failed to Load: {loadResult.Error?.Code}, message: {loadResult.Error?.Message}");
    return;
}

// Successful Load!

// Set strong reference to cached ad
_fullscreenAd = loadResult.AD;

// Set custom data before show
_fullscreenAd.CustomData = "CUSTOM DATA HERE!";

// DidLoad
var customData = _fullscreenAd.CustomData;
var adLoadId = _fullscreenAd.LoadId;
var bidInfo = _fullscreenAd.WinningBidInfo;
var placementName = _fullscreenAd?.Request?.PlacementName;
var loadId = loadResult.LoadId;
var metrics = loadResult.Metrics;
Log($"Fullscreen: {placementName} Loaded with: \nAdRequestId {adLoadId} \nRequestID {loadId} \nBidInfo: {JsonConvert.SerializeObject(bidInfo, Formatting.Indented)} \n Metrics:{JsonConvert.SerializeObject(metrics, Formatting.Indented)} \n Custom Data: {customData}");

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.

// Get Queue
var queue = ChartboostMediationFullscreenAdQueue.Queue("placementName");
Debug.Log($"Queue capacity : {queue.QueueCapacity}");

// Monitor Queue
queue.DidUpdate += (adQueue, adLoadResult, numberOfAdsReady)
     => Debug.Log($"Queue Updated. NumberOfAdsReady : {numberOfAdsReady}");
 queue.DidRemoveExpiredAd += (adQueue, numberOfAdsReady)
     => Debug.Log($"Removed expired ad. NumberOfAdsReady : {numberOfAdsReady}");

 // Start queue
 queue.Start();

// Wait for some time for the queue to load an ad or subscribe to `DidUpdate` 
// event as shown above to be notified when an ad is loaded into queue

// Load an ad from queue
if (queue.HasNextAd())
{
    // removes and returns the oldest ad in the queue 
    // and starts a new load request
    var fullscreenAd = queue.GetNextAd();   
 }

// 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.SetCapacity(4);
  
// Stop queue
queue.Stop();

// 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 = new Dictionary<string, string>()
{
    { "key", "value" }
};

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.

We have added a new Banner API ChartboostMedaitionBannerView to allow usage of adaptive banners. The previous ChartboostMedaitionBannerAd API has now been deprecated.

Another API ChartboostMediationUnityBannerAd is also provided which allows usage of unity gameobjects to load a banner ad within it.

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

Field Description
static ChartboostMediationBannerSize Standard Static constant that returns a fixed STANDARD banner with a size of 320x50.
static ChartboostMediationBannerSize MediumRect Static constant that returns a fixed MREC MEDIUM banner with a size of 300x250.
static ChartboostMediationBannerSize Leaderboard Static constant that returns a fixed LEADERBOARD banner with a size of 728x90.
ChartboostMediationBannerType BannerType 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.
float Width The width of the ad.
float Height The height of the ad.
float AspectRatio 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 ChartboostMediationBannerSize Adaptive(float width) Creates a flexible/adaptive banner size with 0 height.
static ChartboostMediationBannerSize Adaptive(float width, float height) 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 ChartboostMediationBannerSize Adaptive2X1(float width)
  • static ChartboostMediationBannerSize Adaptive4X1(float width)
  • static ChartboostMediationBannerSize Adaptive6X1(float width)
  • static ChartboostMediationBannerSize Adaptive8X1(float width)
  • static ChartboostMediationBannerSize Adaptive10X1(float width)
  • static ChartboostMediationBannerSize Adaptive1X2(float width)
  • static ChartboostMediationBannerSize Adaptive1X3(float width)
  • static ChartboostMediationBannerSize Adaptive1X4(float width)
  • static ChartboostMediationBannerSize Adaptive9X16(float width)
  • 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.

    Loading Banner ads πŸ”—

    A detailed example on the load logic for both of these APIs can be found below:

    Using ChartboostMediationBannerView API πŸ”—

    // Get a bannerView
    IChartboostMediationBannerView bannerView = ChartboostMediation.GetBannerView();
    
    // Determine the maximum size to load using width and height
    var size = ChartboostMediationBannerSize.Adaptive(width, height);
    
    // create a load request with size and your placementName
    var loadRequest = new ChartboostMediationBannerAdLoadRequest(placementName, size)
    
    // Determine where on the screen you want to place this bannerView
    var screenLocation = ChartboostMediationBannerAdScreenLocation.TopRight;
    
    // Load the banner ad
    var loadResult = await bannerView.Load(loadRequest, screenLocation);
    if(!loadResult.Error.HasValue)
    {
        // loaded successfullly
    }
    

    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.

    var adLoadResult = await  bannerAd.Load(adLoadRequest, screenLocation);
    var size = adLoadResult.Size;
    // Do something with the size
    

    Banners are shown automatically after load. You may choose to use a different ChartboostMediationBannerAdScreenLocation position when calling the load method:

    Banner Ad Location Enum Enum Value Position
    ChartboostMediationBannerAdScreenLocation.TopLeft 0 Positions the banner to the top-left screen of the device.
    ChartboostMediationBannerAdScreenLocation.TopCenter 1 Positions the banner to the top-center screen of the device.
    ChartboostMediationBannerAdScreenLocation.TopRight 2 Positions the banner to the top-right screen of the device.
    ChartboostMediationBannerAdScreenLocation.Center 3 Positions the banner to the center screen of the device.
    ChartboostMediationBannerAdScreenLocation.BottomLeft 4 Positions the banner to the bottom-left screen of the device.
    ChartboostMediationBannerAdScreenLocation.BottomCenter 5 Positions the banner to the bottom-center screen of the device.
    ChartboostMediationBannerAdScreenLocation.BottomRight 6 Positions the banner to the bottom-right screen of the device.

    To place the bannerView using a custom screen location, provide a screen coordinate (x, y) which denotes where the top-left corner of this bannerView will be placed.

    // 400 pixels from left
    float x = ChartboostMediationConverters.PixelsToNative(400); 
    // 200 pixels from bottom
    float y = ChartboostMediationConverters.PixelsToNative(200); 
    
    // Load the banner ad
    await bannerView.Load(loadRequest, x, y);
    

    Using ChartboostMediationUnityBannerAd API πŸ”—

    ChartboostMediationUnityBannerAd API enables loading of a bannerAd within a unity gameobject. To create this gameobject, right-click in the hierarchy window and select Chartboost Mediation/UnityBannerAd.

    Creating UnityBannerAd

    // Get reference to ChartboostMediationUnityBannerAd created in Editor
    public ChartboostMediationUnityBannerAd unityBannerAd;
    
    // Load the banner ad inside this gameobject
    var loadResult = await unityBannerAd.Load();
    
    if(!loadResult.Error.HasValue)
    {
        // loaded successfullly
    }
    

    If you want to create this gameobject at runtime you can make use of ChartboostMediation.GetUnityBannerAd().

    // Get new unityBannerAd created as a child of provided canvas
    var canvas = FindObjectOfType<Canvas>(); 
    ChartboostMediationUnityBannerAd unityBannerAd = ChartboostMediation.GetUnityBannerAd(placementName, canvas.transform);
    
    // Load the banner ad inside this gameobject
    var loadResult = await unityBannerAd.Load();
    
    if(!loadResult.Error.HasValue)
    {
        // loaded successfullly
    }
    
    

    You can implement delegates in your class to receive notifications about the success or failure of the ad loading process for Banner formats. See section Delegate Usage for more details.

    Resizing Adaptive Banner Container πŸ”—

    Using ChartboostMediationBannerView API πŸ”—

    bannerView.DidLoad += (banner) => 
    {
        // Determine the axis on which you want the bannerView to resize
        var resizeAxis = ChartboostMediationBannerResizeAxis.Vertical; 
    
        // Make the resize call
        bannerView.ResizeToFit(resizeAxis);
    }
    
    

    Using ChartboostMediationUnityBannerAd API πŸ”—

    // Determine the resizeOption you want to set on this gameobject
    ResizeOption resizeOption = ResizeOption.FitVertical;
    
    // Update the resizeOption 
    unityBannerAd.ResizeOption = resizeOption
    
    

    Discarding Oversized Ads πŸ”—

    // To drop oversized ads
    ChartboostMediation.DiscardOversizedAds(true)
    
    // To allow oversized ads
    ChartboostMediation.DiscardOversizedAds(false)
    
    

    Clearing Loaded Ads πŸ”—

    You may need to clear loaded ads on existing placements to request another ad (i.e. for an in-house programmatic auction). To do this:

    • /// New fullscreen API
      _fullscreenPlacement.Invalidate();
      
      /// New bannerView API
      _bannerView.Reset();
      
      /// New unityBannerAd API
      _unityBannerAd.Reset()
      
      
    • // Old API
      _interstitialAd.ClearLoaded();
      _rewardedAd.ClearLoaded();
      _bannerAd.ClearLoaded();