This guide shows you how to use the Google Mobile Ads Unity plugin to implement AdMob Native Ads Advanced in a Unity app, as well as some important things to consider along the way.
Native ads match both the form and function of the user experience in which they're placed. They also match the visual design of the app they live within. AdMob's native ads advanced format enables publishers to render ads that are seamless with content. You can use this technology to implement highly custom renderings that take full advantage of the native code in Unity apps.
Native advanced ads are shown using the same types of GameObjects
with which
you're already building your apps and can be formatted to match the visual
design of the user experience in which they live. When a native ad loads, your
app receives a native object that contains its assets and the Unity app (rather
than the SDK) displays them.
There are two standard native ads advanced field
descriptions: app install and
content.
App install ads are represented by NativeAppInstallAd
, and content
ads are represented by NativeContentAd
. These objects contain the assets for
the native ad.
Read customer success stories:
case study 1,
case study 2.
Prerequisites
- If you are migrating from the public version of the Google Mobile Ads plugin on GitHub, first remove all existing Google Mobile Ads files.
- Download the native ads build of the Google Mobile Ads Unity plugin to support Native Ads Advanced.
- Follow the instructions from the Get Started guide on how to Import the Mobile Ads Unity plugin and Include the Mobile Ads SDK.
Load native ad formats
Native Ads Advanced are loaded via the AdLoader
class, which has its own
AdLoader.Builder
class to customize it during creation. The
ForNativeAppInstallAd()
method configures the AdLoader
to handle
app install ads and the ForNativeContentAd()
configures the AdLoader
to
handle content ads.
private void RequestNativeAd() {
AdLoader adLoader = new AdLoader.Builder(INSERT_AD_UNIT_HERE)
.ForNativeAppInstallAd()
.ForNativeContentAd()
.Build();
}
Register for AdLoader ad events
To be notified when a native advanced ad either successfully loads or fails to
load, add delegates to the AdLoader
class for the events listed below.
OnNativeAppInstallAdLoaded
- Invoked when a native app install ad is successfully loaded. It is required to have a delegate for this event to access the ad that loaded.
OnNativeContentAdLoaded
- Invoked when a native content ad is successfully loaded. It is required to have a delegate for this event to access the ad that loaded.
OnAdFailedToLoad
- Invoked when a native ad fails to load.
Load the ad
Once you've finished building an AdLoader
, call its LoadAd()
method to
request an ad:
adLoader.LoadAd(new AdRequest.Builder().Build());
Put the ad request together
The code snippet below demonstrates how to build an AdLoader
that is
configured to request
app install and content
ads, sets delegates for successful and failed ad loads, and makes an ad request.
private void RequestNativeAd() {
AdLoader adLoader = new AdLoader.Builder(INSERT_AD_UNIT_HERE)
.ForNativeAppInstallAd()
.ForNativeContentAd()
.Build();
adLoader.OnNativeAppInstallAdLoaded += this.HandleNativeAppInstallAdLoaded;
adLoader.OnNativeContentAdLoaded += this.HandleNativeContentAdLoaded;
adLoader.LoadAd(new AdRequest.Builder().Build());
}
Handle failed ad loads
The OnAdFailedToLoad
event is of type EventHandler<AdFailedToLoadEventArgs>
.
Parsing the reason for an ad load failure from this event is shown below.
private void HandleNativeAdFailedToLoad(object sender, AdFailedToLoadEventArgs args) {
MonoBehaviour.print("Native ad failed to load: " + args.Message);
}
Display an ad
When a Native Ad Advanced loads, the ad event for the corresponding ad format is invoked. Your app is then responsible for displaying the ad, though it doesn't necessarily have to do so immediately.
Handle app install ad load
The OnNativeAppInstallAdLoaded
event is of type
EventHandler<NativeAppInstallAdEventArgs>
. The app install ad, encapsulated
in a NativeAppInstallAd
object, can be retrieved from
NativeAppInstallAdEventArgs
as shown:
private NativeAppInstallAd appInstallAd;
...
private void HandleNativeAppInstallAdLoaded(object sender, NativeAppInstallAdEventArgs args) {
MonoBehaviour.print("App install ad loaded.");
this.appInstallAd = args.nativeAd;
}
Handle content ad load
The OnNativeContentAdLoaded
event is of type
EventHandler<NativeContentAdEventArgs>
. The content ad, encapsulated in a
NativeContentAd
object, can be retrieved from NativeAppInstallAdEventArgs
as shown:
private void HandleNativeContentAdLoaded(object sender, NativeContentAdEventArgs args) {
MonoBehaviour.print("Content ad loaded.");
this.contentAd = args.nativeAd;
}
Retrieve native ad assets
Once ads have loaded, their assets can be accessed as shown below. Graphical
assets are returned as Texture2D
objects and text assets are returned as
string
objects.
private bool appInstallAdLoaded;
private NativeAppInstallAd appInstallAd;
...
void Update() {
...
if (this.appInstallAdLoaded) {
this.appInstallAdLoaded = false;
// Get Texture2D for icon asset of app install ad.
Texture2D iconTexture = this.appInstallAd.GetIconTexture();
// Get string for headline asset of app install ad.
string headline = this.appInstallAd.GetHeadlineText();
}
}
...
private void HandleNativeAppInstallAdLoaded(object sender, NativeAppInstallAdEventArgs args) {
MonoBehaviour.print("App install ad loaded.");
this.appInstallAd = args.nativeAd;
this.appInstallAdLoaded = true;
}
It is important to note that ad assets can only be accessed from the Update()
method of a Unity script.
AdChoices asset
It's a requirement to display the AdChoices ad asset as part of the Native Advanced ad. Also, it's important that the AdChoices ad asset be easily seen, so choose background colors and images appropriately.
Register GameObjects for ad asset
For each ad asset to be displayed, you must register the GameObject
to use to
display the asset within the Unity app. Every method to register a GameObject
for an ad asset will return a bool
indicating if registration was successful.
If registration of an ad asset unsuccessful, impressions and clicks on the
corresponding native ad will not be recognized.
if (!this.appInstallAd.RegisterIconImageGameObject(icon))
{
// Handle failure to register ad asset.
}
The GameObject
that is registered for an ad asset asset must have a convex
Collider
component that is representative of the size and shape of the
GameObject
. If GameObject
objects registered to ad assets are missing
Collider
components or have an incorrectly configured one, native advanced
ads will not operate correctly.
In the code snippet below, a BoxCollider
is added to GameObject
that uses a
TextMesh
to display the headline ad asset of
an app install
ad. Once the BoxCollider
is attached to the GameObject
, it will
automatically scale to accommodate the text of the TextMesh
component.
// Create GameObject that will display the headline ad asset.
GameObject headline = new GameObject();
headline.AddComponent<TextMesh>();
headline.GetComponent<TextMesh>().characterSize = 0.5 f;
headline.GetComponent<TextMesh>().anchor = TextAnchor.MiddleCenter;
headline.GetComponent<TextMesh>().color = Color.black;
// Get string of the headline asset.
string headlineText = this.appInstallAd.GetHeadlineText();
headline.GetComponent<TextMesh>().text = headlineText;
// Add box collider to the GameObject which will automatically scale.
headline.AddComponent<BoxCollider>();
Demo
The following code demonstrates how to retrieve the icon asset of a successfully
loaded
app install
ad, display the icon ad asset by setting the texture of a Quad
, and register
the GameObject
to use to display the asset.
This process of retrieving the ad asset and registering it with the native ad
class should be repeated for each of the assets that the app displays.
private GameObject icon;
private NativeAppInstallAd appInstallAd;
private bool appInstallAdLoaded;
...
void Update() {
...
if (this.appInstallAdLoaded) {
this.appInstallAdLoaded = false;
// Get Texture2D for icon asset of app install ad.
Texture2D iconTexture = this.appInstallAd.GetIconTexture();
icon = GameObject.CreatePrimitive(PrimitiveType.Quad);
icon.transform.position = new Vector3(1, 1, 1);
icon.transform.localScale = new Vector3(1, 1, 1);
icon.GetComponent<Renderer>().material.mainTexture = iconTexture;
// Register GameObject that will display icon asset of app install ad.
if (!this.appInstallAd.RegisterIconImageGameObject(icon))
{
// Handle failure to register ad asset.
}
}
}
...
private void HandleNativeAppInstallAdLoaded(object sender, NativeAppInstallAdEventArgs args) {
MonoBehaviour.print("App install ad loaded.");
this.appInstallAd = args.nativeAd;
this.appInstallAdLoaded = true;
}