Custom Native Ad Formats

Google Ad Manager publishers can create their own native ad formats by defining custom lists of assets. These custom native ad formats 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.

Load custom native ad formats

Custom native ad formats are loaded using AdLoader objects. The forCustomTemplateAd() method configures the AdLoader to handle custom native ad formats. Each custom native ad format has a template ID value associated with it. You must specify the template ID of the custom native ad format your app wants the AdLoader to request. Search the template IDs in the Ad Manager UI for the template ID of the native ad format you want to request.

void LoadCustomNativeTemplateAd()
{
    AdLoader adLoader = new AdLoader.Builder("/6499/example/native")
        .forCustomNativeAd("10063170")
        .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 to prepare the Adloader for more than one possible custom native ad format. The code snippet below demonstrates how to prepare an AdLoader for multiple custom native ad format templates.

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

Custom native ad format ad events

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

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

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

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

Display custom native ad formats

Custom native ad formats 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.

The following example implementation extracts assets from a CustomNativeTemplateAd:

public const int NATIVE_AD_TEMPLATE_1 = 10063170;
public const int NATIVE_AD_TEMPLATE_2 = 10063171;

private boolean adLoaded;
private Texture2d mainImageTexture;
private string headline;
private CustomNativeTemplateAd customNativeTemplateAd;
...

void Update()
{
    if(adLoaded)
    {
        mainImageTexture = customNativeTemplateAd.GetTexture2D("MainImage");
        headline = customNativeTemplateAd.GetText("Headline");

        string templateId = customNativeTemplateAd.GetCustomTemplateId();
        if (templateId == NATIVE_AD_TEMPLATE_1)
        {
            ...
        }
        else if (templateId == NATIVE_AD_TEMPLATE_2)
        {
            ...
        }
        ...
        adLoaded = false;
    }
}
...

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

Note: When ad events are forwarded from the Google Mobile Ads Android SDK to the Unity plugin, they are not called on the main thread. As Unity requires texture loading to be executed on the main thread, assets from a CustomNativeTemplateAd cannot be accessed within the onCustomNativeTemplateAdLoaded ad event. The code example above illustrates the recommended practice of setting a flag or modifying state from within the OnAdLoaded ad event. The Update() method can check for this flag or change in state and access the custom native template ad assets.

Handle 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.

Record impressions

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

customNativeTemplateAd.RecordImpression();

Report 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 native ad format 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");

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

1. Locate a content resolver for the ad's deep link URL and start the first one that resolves.
2. Open a browser and navigate to the ad's traditional destination URL.

Custom click actions

You may decide that you want to handle the click action yourself for your custom native ad formats instead of taking the user to a deep link or web browser. You can do this by providing an optional Action<CustomNativeTemplateAd, string> in the AdLoader.Builder.forCustomTemplateAd() method. By setting this custom click action, you are overriding the SDK's click behavior described above. Here's an example that uses a custom click action to log 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.");
}