Custom Native Ad Formats for Unity

Note: Custom Native Ad Format Ads is only available to Ad Manager publishers.

Ad Manager publishers have the option of creating their own native ad formats by defining custom lists of assets. These are called custom native ad formats, and can be used with reserved ads. Custom native ad formats enable publishers to pass arbitrary image and string data to their apps. This data is represented by a CustomNativeTemplateAd object.

Loading custom native ad formats

Custom native ads are loaded using AdLoader objects. The forCustomTemplateAd() method configures the AdLoader to handle custom template ads. There are two parameters for this method:

• The templateID of the custom template that the AdLoader should request. Each custom native ad format has a template ID value associated with it. This parameter indicates which template your app wants the AdLoader to request.
• An optional Action<CustomNativeTemplateAd, string> to be invoked when the user clicks on the ad.

void LoadCustomNativeTemplateAd()
{
    AdLoader adLoader = new AdLoader.Builder("/6499/example/native")
            .forCustomNativeAd("10063170", HandleCustomNativeAdClicked)
            .Build();
    adLoader.LoadAd(new AdRequest.Builder().Build());
}

Because a single ad unit can be set up to serve more than one creative template, forCustomTemplateAd() can be called multiple times with different template IDs in order to prepare the ad loader for more than one possible custom native ad format.

Custom native template ad events

The AdLoader class provides ad events, of type EventHandler, to notify you about a custom native template ad's lifecycle. The example below demonstrates how to register for custom native template ad events on an ad loader:

adLoader.onCustomNativeTemplateAdLoaded += HandleCustomNativeAdLoaded;
adLoader.OnAdFailedToLoad += HandleCustomNativeAdFailedToLoad;

The HandleCustomNativeAdLoaded() method contains a CustomNativeEventArgs parameter. The custom native template that has loaded can be accessed through this event parameter, as shown below:

void HandleCustomNativeAdLoaded(object sender, CustomNativeEventArgs args)
{
    CustomNativeTemplateAd customNativeTemplateAd = args.nativeAd;
    ...
}

Displaying custom native ad formats

Custom native template ads provide support for any number of user-defined image and text assets. These assets are accessed through the CustomNativeTemplateAd class, which provides GetTexture2D() and GetText() methods that take the variable ID of a template field as a parameter.

Here's an example implementation that accesses assets from a CustomNativeTemplateAd:

private boolean adLoaded;
Private Texture2d mainImageTexture;
private string headline;
...

void Update()
{
    if(adLoaded)
    {
        mainImageTexture = customNativeTemplateAd.GetTexture2D("MainImage");
        headline = customNativeTemplateAd.GetText("Headline");
        adLoaded = false;
    }
}
...
void HandleCustomNativeAdLoaded(object sender, CustomNativeEventArgs args)
{
    CustomNativeTemplateAd customNativeTemplateAd = args.nativeAd;
    ...
}

Handling custom native ad format clicks and impressions

With custom native ad formats, your app is responsible for recording impressions and reporting click events to the SDK.

Recording impressions

To record an impression for a custom template ad, call the RecordImpression() method on the corresponding CustomNativeTemplateAd:

customNativeTemplateAd.RecordImpression();

Reporting clicks

To report to the SDK that a click has occurred on an asset, call the PerformClick() method on the corresponding CustomNativeTemplateAd and pass the name of the asset that was clicked. For example, if you had an asset in your custom template called "MainImage" and wanted to report a click on the texture that corresponded to that asset, your code would look like this:

customNativeTemplateAd.PerformClick("MainImage");

Responding to custom click actions

When a click is reported on a custom template ad, there are three possible responses from the SDK, attempted in this order:

1. Invoke the Action<CustomNativeTemplateAd, string> from the AdLoader that was set when configuring a custom native template ad, if one was provided in the AdLoader.Builder.forCustomTemplateAd() method.
2. For each of the ad's deep link URLs, attempt to locate a content resolver and start the first one that resolves.
3. Open a browser and navigate to the ad's traditional destination URL.

Custom click actions allow your app to decide the best action to take in response to a click, whether it's updating the UI, or merely logging the click. Here's an example that logs a click for a given asset:

private void LoadCustomNativeTemplateAd()
{
    AdLoader adLoader = new AdLoader.Builder("/6499/example/native")
            .forCustomNativeAd("10063170", HandleCustomNativeAdClicked)
            .Build();
    adLoader.onCustomNativeTemplateAdLoaded += HandleCustomNativeAdLoaded;
    adLoader.OnAdFailedToLoad += HandleCustomNativeAdFailedToLoad;
    adLoader.LoadAd(createAdRequest());
}

private void HandleCustomNativeAdClicked(CustomNativeTemplateAd
customNativeTemplateAd, string assetName)
{
    Debug.Log("Native ad asset with name " + assetName + " was clicked.");
}