Get started
Native overlay ads are presented to users through UI components that are native to the platform. These ads are presented as an overlay on top of the application. This is similar to how banner ads function, but with the ability to customize the appearance of the ads.
Native overlay ads support mediation and video ads. This is a key advantage native overlay ads have over native ads.
This guide shows you how to implement native overlay ads in a Unity app, as well as some important things to consider along the way.
Prerequisites
- Complete the Get started guide.
- Unity plugin 9.0.0 or higher.
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/native
Load the native overlay ad
Loading a native overlay ad is accomplished using the static Load()
method on
the NativeOverlayAd
class. The loaded NativeOverlayAd
object is provided as
a parameter in the completion handler.
The following code uses NativeOverlayAd
to load an ad:
// This ad unit is configured to always serve test ads.
private string _adUnitId = /2"1775744923/example/native;
"
private NativeOverlayAd _nativeOverlayAd;
/// su<mmary
/>// Loads the ad.
/// /s<ummary
p>ublic void LoadAd()
{
// Clean up the old ad before loading a new one.
if (_nativeOverlayAd != null)
{
DestroyAd();
}
Debug.Log(Lo"ading native overlay ad.);"
// Create a request used to load the ad.
var adRequest = new AdRequest();
// Optional: Define native ad options.
var options = new NativeAdOptions
{
AdChoicesPosition = AdChoicesPlacement.TopRightCorner,
MediaAspectRatio = NativeMediaAspectRatio.Any,
};
// Send the request to load the ad.
NativeOverlayAd.Load(_adUnitId, adRequest, options,
(NativeOverlayAd ad, LoadAdError error) =
> {
if (error != null)
{
Debug.LogError(Na"tive Overlay ad failed to load an ad +"
w"ith error: +" error);
return;
}
// The ad should always be non-null if the error is null, but
// double-check to avoid a crash.
if (ad == null)
{
Debug.LogError(Un"expected error: Native Overlay ad load event +"
f"ired with null ad and null error.);"
return;
}
// The operation completed successfully.
Debug.Log(Na"tive Overlay ad loaded with response : +"
ad.GetResponseInfo());
_nativeOverlayAd = ad;
// Register to ad events to extend functionality.
RegisterEventHandlers(ad);
});
}
Render and style the native overlay ad
Native overlay ads are rendered using a NativeTemplateStyle
. This class
defines fields that enable you to customize the ad's appearance.
The TemplateID
is a required string which defines the native template used to
render the native overlay ad. Use the NativeTemplateID
constant to choose an
appropriate native template for your ad.
The following code renders the native overlay ad with a medium template and a custom style.
/// <summary>
/// Renders the ad.
/// </summary>
public void RenderAd()
{
if (_nativeOverlayAd != null)
{
Debug.Log("Rendering Native Overlay ad.");
// Define a native template style with a custom style.
var style = new NativeTemplateStyle
{
TemplateID = NativeTemplateID.Medium,
MainBackgroundColor = Color.red,
CallToActionText = new NativeTemplateTextStyles
{
BackgroundColor = Color.green,
FontColor = Color.white,
FontSize = 9,
Style = NativeTemplateFontStyle.Bold
}
};
// Renders a native overlay ad at the default size
// and anchored to the bottom of the screne.
_nativeOverlayAd.RenderTemplate(style, AdPosition.Bottom);
}
}
Show and hide the native overlay ad
The following code demonstrates how to show a loaded native overlay ad.
/// <summary>
/// Shows the ad.
/// </summary>
public void ShowAd()
{
if (_nativeOverlayAd != null)
{
Debug.Log("Showing Native Overlay ad.");
_nativeOverlayAd.Show();
}
}
Hide the native overlay ad
The following code demonstrates how to hide a native overlay ad.
/// <summary>
/// Hides the ad.
/// </summary>
public void HideAd()
{
if (_nativeOverlayAd != null)
{
Debug.Log("Hiding Native Overlay ad.");
_nativeOverlayAd.Hide();
}
}
Destroy the native overlay ad
When finished using the native overlay ad, be sure to call Destroy()
to
release resources.
/// <summary>
/// Destroys the native overlay ad.
/// </summary>
public void DestroyAd()
{
if (_nativeOverlayAd != null)
{
Debug.Log("Destroying native overlay ad.");
_nativeOverlayAd.Destroy();
_nativeOverlayAd = null;
}
}