Banner Ads

This guide shows you how to integrate banner ads from CAS into a Unity app. In addition to code snippets and instructions, it also includes information about sizing banners properly.

Enable Banner Ads for your game in Assets > CleverAdsSolutions > Settings menu.

For easier ads integration using the Unity Editor, try the new BannerAdObject.

Ad size

To load a banner ad, you need to specify the ad size. To do this, choose one of the AdSize from the list below:

1. Adaptive banner ads have a fixed aspect ratio for the maximum screen width. The adaptive size calculates the optimal height for that width with an aspect ratio similar to 320x50.

AdSize adSize = AdSize.AdaptiveBanner;

The width cannot be less than 300 density independent pixels and larger than 728 density independent pixels.
2. Adaptive Full Width Banner ads are similar to AdaptiveBanner, but they can have a width greater than 728 pixels in landscape orientation.

AdSize adSize = AdSize.AdaptiveFullWidth;

3. Smart ad size selects the optimal dimensions depending on the device type. For mobile devices, it returns 320x50, while for tablets, it returns 728x90. In the UI, these banners occupy the same amount of space regardless of device type.

AdSize adSize = AdSize.SmartBanner;

4. Medium Rectangle has a fixed size of 300x250.

AdSize adSize = AdSize.MediumRectangle;

5. Leaderboard has a fixed size of 728x90 and is allowed on tablets only.

AdSize adSize = AdSize.Leaderboard;

6. Standard banner has a fixed size of 320x50 and is the minimum ad size.

AdSize adSize = AdSize.Banner;

Get the ad view interface for specific AdSize:

IAdView adView = manager.GetAdView(adSize);

Load an Ad

By default, the auto-load ads mode is used and a load method does not need to be called.
Call manual load ad after manager.GetAdView() if you use LoadingManagerMode.Manual only.

adView.Load();

Also you can use the load for cancel current impression and load next ad.

Ad events

To further customize the behavior of your ad, you can hook into a number of events in the ad's lifecycle: loading, clicking, and so on. Listen for these events by registering a delegate for the appropriate event, as shown below.

void OnEnable()
{
    adView.OnLoaded += AdLoaded;
    adView.OnFailed += AdFailedToLoad;
    adView.OnClicked += AdClicked;
}

void OnDisable()
{
    adView.OnLoaded -= AdLoaded;
    adView.OnFailed -= AdFailedToLoad;
    adView.OnClicked -= AdClicked;
}

void AdLoaded()
{
    // Called when the ad loaded and ready to present.
    Debug.Log("Banner ad loaded");
}

void AdFailedToLoad(AdError error)
{
    // Сalled when an error occurred with the ad.
    Debug.Log("Banner failed to load an ad with error: " + error.GetMessage());
}

void AdClicked()
{
    // Called when the user clicks on the Ad.
    Debug.Log("Banner ad was clicked");
}

Read more about event OnImpression with Impression Level Data and AdMetaData.

Display the Ad

The newly created AdView has an inactive state.
When you are ready to show the ad on the screen, simply call the following method:

adView.SetActive(true);

When you need to hide AdView from the user, just deactivate it:

adView.SetActive(false);

Ad position

The position where the banner ad should be placed. The CAS.AdPosition enum lists the valid ad position values. By default, the banner ad is centered at the bottom.

The table for all positions on the screen. Some position values ​​do not support offset on the X or Y axis, this can be seen in the table as (X, Y).

Use the SetPosition(int, int, AdPosition) to place AdView at the X and Y offset, where the origin is the selected corner (AdPosition) of the screen.

The coordinates on the screen are determined in Density-independent Pixels(DP):

adView.SetPosition(xOffsetInDP, yOffsetInDP, AdPosition.TopLeft);

The coordinates on the screen are determined in pixels:

adView.SetPositionPx(xOffsetInPx, yOffsetInPx, AdPosition.TopLeft);

To specify a position on the screen without offset, use the position property.

adView.position = AdPosition.TopCenter;

This line is the same as calling SetPosition(0, 0, AdPosition.TopCenter)

Rect in pixels

You can calculate the actual rect of the Ad Banner in pixels on the screen.

Rect rect = adView.rectInPixels;
Vector2 adSizePixels = rect.size;
Vector2 adPositionInPixels = rect.position; 

This value is buffered after calculation, feel free to check ad view rect each frame.
The position on the screen is calculated with the addition of indents for the cutouts.

CAS plugin provides the ability to get the correct device screen scale value to convert Pixels to Density-independent Pixels(DP) and vice versa.

float scale = CAS.MobileAds.GetDeviceScreenScale();
float widthInDP = adSizePixels.x / scale;
float heightInDP = adSizePixels.y / scale;

float someValueInPixels = someValueInDP * scale;

Ad Refresh rate

An ad unit’s automatic refresh rate (in seconds) determines how often a new ad request is generated for that ad unit.
We recommended using refresh rate 30 seconds. However, you can choose any value you want longer than 10 seconds.

Change the banner automatic refresh rate using the following method:

adView.refreshInterval = refreshIntervalInSeconds;

Or disable automatic refresh ads with method:

adView.DisableRefresh();

Free ad memory

If you no longer need the AdView with specific size, please call IDisposable.Dispose() to free memory.

adView.Dispose();

After calling Dispose(), you can use GetAdView(AdSize) method to create a new view.

Ad Availability

You can ask for the ad availability directly by calling the following function:

bool bannerLoaded = adView.isReady;

Complete example

• HelloWorld example — a minimal implementation of all ad formats