Banner views are rectangular image or text ads that occupy a spot on screen. They stay on screen while users are interacting with the app, and can refresh automatically after a certain period of time. If you're new to mobile advertising, they're a great place to start.
This guide shows you how to integrate banner views into a Unity app. In addition to code snippets and instructions, it also includes information about sizing banners properly and links to additional resources.
Prerequisites
- Complete the Get started guide.
Always test with test ads
The following sample code contains an ad unit ID which you can use to request test ads. It's been specially configured to return test ads rather than production ads for every request, making it safe to use.
However, after you've registered an app in the Ad Manager web interface and created your own ad unit IDs for use in your app, explicitly configure your device as a test device during development.
/21775744923/example/adaptive-banner
Initialize the Mobile Ads SDK
Before loading ads, have your app initialize the Mobile Ads SDK by calling
MobileAds.Initialize()
. This needs to be done only once, ideally at app launch.
using GoogleMobileAds;
using GoogleMobileAds.Api;
public class GoogleMobileAdsDemoScript : MonoBehaviour
{
public void Start()
{
// Initialize the Google Mobile Ads SDK.
MobileAds.Initialize((InitializationStatus initStatus) =>
{
// This callback is called once the MobileAds SDK is initialized.
});
}
}
If you're using mediation, wait until the callback occurs before loading ads as this will ensure that all mediation adapters are initialized.
BannerView example
The following sample code details how to use the banner view. In the example,
create an instance of a banner view, use an
AdManagerAdRequest
to load an ad into the banner view, and
then extend its capabilities by handling lifecycle events.
Create a banner view
The first step in using a banner view is to create an instance of a banner view.
Replace AD_UNIT_ID with your ad unit ID.
The constructor for a AdManagerBannerView
has the following
parameters:
adUnitId
: The ad unit ID of the banner ad to load.AdSize
: The banner size you'd like to use.AdPosition
: The position where the banner views should be placed.
(Optional) Create a banner view with a custom position
For greater control over where a banner view is placed on screen than what's
offered by AdPosition
values, use the constructor
that has x- and y-coordinates as parameters:
The top-left corner of the banner view is positioned at the x and y values passed to the constructor, where the origin is the top-left of the screen.
(Optional) Create a banner view with a custom size
In addition to using an AdSize
constant, you can also specify a custom size
for your ad:
(Optional) Multiple ad sizes
Ad Manager lets you specify multiple ad sizes which could be eligible to serve
in an AdManagerBannerView
. Before implementing this feature in the SDK, create
a line item targeting the same ad units associated with different size creatives.
In your app, pass multiple AdSize
parameters into ValidAdSizes
:
If AdManagerAdView
changes size at refresh time, your layout should be able to
automatically adapt to the new size. AdManagerAdView
defaults to the size
passed in the first parameter until the next ad returns.
Load a banner ad
After the AdManagerBannerView
is in place, proceed to load
an ad with the LoadAd()
method in the AdManagerBannerView
class. It takes an parameter which holds
runtime information, such as targeting info, exclusion labels, and the publisher
provided ID.
To load an ad, create an AdManagerAdRequest
and pass it to
the LoadAd()
method.
// Send a request to load an ad into the banner view.
adManagerBannerView.LoadAd(new AdManagerAdRequest());
Listen to banner view events
To customize the behavior of your ad, you can hook into a number of events in the ad's lifecycle, such as loading, opening, or closing. To listen for these events, register a delegate:
adManagerBannerView.OnBannerAdLoaded += () =>
{
// Raised when an ad is loaded into the banner view.
};
adManagerBannerView.OnBannerAdLoadFailed += (LoadAdError error) =>
{
// Raised when an ad fails to load into the banner view.
};
adManagerBannerView.OnAdPaid += (AdValue adValue) =>
{
// Raised when the ad is estimated to have earned money.
};
adManagerBannerView.OnAdImpressionRecorded += () =>
{
// Raised when an impression is recorded for an ad.
};
adManagerBannerView.OnAdClicked += () =>
{
// Raised when a click is recorded for an ad.
};
adManagerBannerView.OnAdFullScreenContentOpened += () =>
{
// Raised when an ad opened full screen content.
};
adManagerBannerView.OnAdFullScreenContentClosed += () =>
{
// Raised when the ad closed full screen content.
};
Destroy the banner view
When finished using the banner view, be sure to call Destroy()
to release
resources.
if (adManagerBannerView != null)
{
// Always destroy the banner view when no longer needed.
adManagerBannerView.Destroy();
adManagerBannerView = null;
}
That's it! Your app is now ready to display banner ads.
Refresh an ad
If you configured your ad unit to refresh, you don't need to request another ad when the ad fails to load. Google Mobile Ads SDK respects any refresh rate you specified in the Ad Manager UI. If you haven't enabled refresh, issue a new request. For more details on ad unit refresh, such as setting a refresh rate, see Refresh rate for ads in mobile apps.
Banner sizes
The following table lists the standard banner sizes:
Size in dp (WxH) | Description | Availability | AdSize constant |
---|---|---|---|
320x50 | Standard Banner | Phones and Tablets | BANNER |
320x100 | Large Banner | Phones and Tablets | LARGE_BANNER |
300x250 | IAB Medium Rectangle | Phones and Tablets | MEDIUM_RECTANGLE |
468x60 | IAB Full-Size Banner | Tablets | FULL_BANNER |
728x90 | IAB Leaderboard | Tablets | LEADERBOARD |
Provided width x Adaptive height | Adaptive banner | Phones and Tablets | N/A |
Screen width x 32|50|90 | Smart banner | Phones and Tablets | SMART_BANNER |
Learn more about Adaptive Banners, intended to replace Smart Banners. |
App events
App events let you create ads that can send messages to their app code. The app can then take actions based on these messages.
You can listen for Ad Manager specific app events using AppEvent
. These events
can occur at any time during the ad's lifecycle, even before load is called.
OnAppEventReceived
is raised when an app event occurs in an ad. Here is an
example of how to handle this event in your code:
adManagerBannerView.OnAppEventReceived += (AppEvent args) =>
{
Debug.Log($"Received app event from the ad: {args.Name}, {args.Data}.");
};
Here is an example showing how to change the background color of your app depending on an app event with a name of color:
adManagerBannerView.OnAppEventReceived += (AppEvent args) =>
{
if (args.Name == "color")
{
Color color;
if (ColorUtility.TryParseHtmlString(args.Data, out color))
{
renderer.material.color = color;
}
}
};
And, here is the corresponding creative that sends color app event:
<html>
<head>
<script src="//www.gstatic.com/afma/api/v1/google_mobile_app_ads.js"></script>
<script>
document.addEventListener("DOMContentLoaded", function() {
// Send a color=green event when ad loads.
admob.events.dispatchAppEvent("color", "green");
document.getElementById("ad").addEventListener("click", function() {
// Send a color=blue event when ad is clicked.
admob.events.dispatchAppEvent("color", "blue");
});
});
</script>
<style>
#ad {
width: 320px;
height: 50px;
top: 0;
left: 0;
font-size: 24pt;
font-weight: bold;
position: absolute;
background: black;
color: white;
text-align: center;
}
</style>
</head>
<body>
<div id="ad">Carpe diem!</div>
</body>
</html>
Additional resources
- HelloWorld example: A minimal implementation of all ad formats.