# Banner Ad

Chartboost Mediation SDK 4.6.0 introduced an Adaptive Banner ad format, capable of serving flexible and fixed sized ads. This ad format provides 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.
* The ad container can be in-line or on top of publisher content.

To use this new ad format, create a new Adaptive Banner placement in your [platform](https://platform.chartboost.com/){:target="_blank"} and integrate with the Adaptive Banner APIs.

The [`UnityBannerAd`](/en/mediation/integrate/unity/unity-banner-ad/) API is provided to allow usage of Unity Gameobjects for loading a banner ad within it.


## `BannerAdLoadRequest`

`BannerAdLoadRequest` objects contains publisher provided configurations for `IBannerAd` objects. It is used when calling `IBannerAd.Load`, as seen in the examples below:

```csharp
// Determine the maximum size to load using width and height
BannerSize size = BannerSize.Adaptive(100, 100);
BannerAdLoadRequest loadRequest = new BannerAdLoadRequest("BANNER_PLACEMENT_NAME", size);
```


## Keywords

Keywords are set after obtaining the `IBannerAd` object when calling `ChartboostMediation.GetBannerAd`. To remove keywords, pass a new set without those keywords. The list will be overridden. This is to facilitate the wrapping process between Unity and native platforms.

<div class="alert alert-info" role="alert">
  <b>Note:</b> Keywords has restrictions for setting keys and values. The maximum characters allowed for keys is 64 characters. The maximum characters for values is 256 characters.
</div>

```csharp
// Keywords to pass for banner ad
var keywords = new Dictionary<string, string>
{
    { "key", "value" },
    { "key_2", "value_2" }
};

// Get banner ad
IBannerAd bannerAd = ChartboostMediation.GetBannerAd();

// Set keywords
bannerAd.Keywords = keywords;
```


## Loading `IBannerAd` Objects

A detailed example on the load logic for this API can be found below:

```csharp
// Get a bannerAd
IBannerAd bannerAd = ChartboostMediation.GetBannerAd();

// Place it at the center of screen
bannerAd.Position = new Vector2(
    DensityConverters.PixelsToNative(Screen.width/2f),
    DensityConverters.PixelsToNative(Screen.height/2f)
);

// Set pivot
bannerAd.Pivot = new Vector2(0.5f, 0.5f);

// Set banner ad callbacks
bannerAd.WillAppear += ad => Debug.Log($"BannerAd: {ad.LoadId} will appear.");
bannerAd.DidClick += ad => Debug.Log($"BannerAd: {ad.LoadId} was clicked.");
bannerAd.DidDrag += (ad,x,y) => Debug.Log($"BannerAd: {ad.LoadId} was dragged x:{x}/y:{y}.");
bannerAd.DidRecordImpression += ad => Debug.Log($"BannerAd: {ad.LoadId} was clicked.");


// create a load request with size and your placementName
var loadRequest = new BannerAdLoadRequest(
    "BANNER_PLACEMENT_NAME",
    BannerSize.Adaptive6X1(width)    // This can be any other size or the old non-adaptive size like `BannerSize.Standard`
);

...
```

### Loading in async Context
```csharp
...
// Load the banner ad with our previously configured load request
BannerAdLoadResult loadResult = await bannerAd.Load(loadRequest);
if(loadResult.Error.HasValue)
{
    // report load error
    return;
}
// loaded successfully
```

### Loading in sync Context
A lot of APIs provided in the Chartboost Mediation Unity SDK utilize the async/await C# implementation. It is possible to call the following code from a sync context where async/await might not be supported:

```csharp
// Show `IBannerAd` using async approach
bannerAd.Load(loadRequest).ContinueWithOnMainThread(continuation =>
{
    loadResult = continuation.Result;
});
```

## `BannerAdLoadResult`

`BannerAdLoadResult` contains information regarding the load for `IBannerAd` objects. Its result can be used as seen below:

```csharp
// Check if IBannerAd failed to load
var error = loadResult.Error;

// Failed to load
if (error.HasValue)
{
    // Report load failure
    Debug.LogError($"`IBannerAd` Load failed with error: {JsonTools.SerializeObject(error.Value, Formatting.Indented)}");
    return;
}

// Load succeeded

// Report metrics and show success
var loadId = loadResult.LoadId;
var metricsJson = JsonTools.SerializeObject(loadResult.Metrics, Formatting.Indented);
var winningBidInfo = JsonTools.SerializeObject(loadResult.WinningBidInfo, Formatting.Indented);
Debug.Log($"`IBannerAd` loaded successfully with:\n" +
          $"LoadId: {loadId}\n" +
          $"Metrics: {metricsJson}\n" +
          $"Winning Bid Info: {winningBidInfo}");

```

## `Dispose`

`IBannerAd` objects implement the [IDisposable](https://learn.microsoft.com/en-us/dotnet/api/system.idisposable?view=net-8.0){:target="_blank"} to properly dispose of managed and unmanaged resources.

You can free up resources directly by calling `IBannerAd.Dispose`.

```csharp
...
IBannerAd ad = ChartboostMediation.GetBannerAd();

// Do what we need to do with our IBannerAd

// Free up resources
ad.Dispose();
```

<div class="alert alert-info" role="alert">
  <b>Note:</b> While this is not a necessary call, since <code>IBannerAd</code> objects will be disposed by the garbage collector once they are no longer referenced. It is still a good practice to disposed of unmanaged resources when no longer needed.
</div>