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}");

📘
Note
The new fullscreen API supports multiple placement loads of the same placement. It is important to properly manage your ad instances if you are planning to create an Ad Queue system.

🚧
Warning
The new fullscreen API utilizes instance based callbacks to notify information regarding the advertisement life-cycle. You must take this into account when migrating from the old API static callbacks.

Creating Banner Ad Objects

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

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

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

private ChartboostMediationBannerAd _bannerAd;

if (_bannerAd != null)
  return;

/*
  The following Banner enum Sizes can be passed down:
  ChartboostMediationBannerAdSize.Standard
  ChartboostMediationBannerAdSize.MediumRect
  ChartboostMediationBannerAdSize.Leaderboard
*/
ChartboostMediationBannerAdSize BANNER_SIZE = ChartboostMediationBannerAdSize.Standard;
_bannerAd = ChartboostMediation.GetBannerAd(PLACEMENT_BANNER, BANNER_SIZE);

//Chartboost Mediation Banner Ad
private HeliumBannerAd _bannerAd;

// if null, create a new banner ad with desired parameters
if (_bannerAd == null) {
  var placement = "MY_BANNER_PLACEMENT"
  var size = HeliumBannerAdSize.Standard;
  bannerAd = HeliumSDK.GetBannerAd(placement, size);
}

Banners are shown automatically after load, as such you will need to pass a 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.

If you enable auto-refresh for banner placement in the dashboard, then the Chartboost Mediation Unity SDK will apply that setting when the placement is shown.

📘
Note
Any auto refresh changes made on the dashboard will take approximately one hour to take effect and the SDK must be rebooted in order to pick up the changes once they are available.

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

/* All possible banner locations
 * ChartboostMediationBannerAdScreenLocation.TopLeft,
 * ChartboostMediationBannerAdScreenLocation.TopCenter,
 * ChartboostMediationBannerAdScreenLocation.TopRight,
 * ChartboostMediationBannerAdScreenLocation.Center,
 * ChartboostMediationBannerAdScreenLocation.BottomLeft,
 * ChartboostMediationBannerAdScreenLocation.BottomCenter,
 * ChartboostMediationBannerAdScreenLocation.BottomRight,
 * ChartboostMediationBannerAdScreenLocation.TopCenter
 */

// Load a banner on the top center location
_bannerAd.Load(ChartboostMediationBannerAdScreenLocation.TopCenter);

if (_bannerAd != null) {
  // specify location on load
  _bannerAd.Load(HeliumBannerAdScreenLocation.BottomCenter)
}

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.

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();

// Old API
_interstitialAd.ClearLoaded();
_rewardedAd.ClearLoaded();
_bannerAd.ClearLoaded();

_interstitialAd.ClearLoaded();
_rewardedAd.ClearLoaded();
// This will clear the currently showing ad and any cached 
// ad that was loaded for auto refresh.
_bannerAd.ClearLoaded();

🚧
Warning
Invalidate behaves similarly like ClearLoaded and Destroy. As such, once called, you must free your ad reference to avoid any possible issues.