Custom native ad formats

Note: Custom native ads are 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 ads enable publishers to pass arbitrary image and string data to their apps. This data is represented by a CustomNativeAd object.

Load a custom native ad

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

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

Custom native ads are loaded through the AdLoader class, which has its own AdLoader.Builder class to customize it during creation. The ForCustomNativeAd() method configures the AdLoader to handle native ads.

void LoadCustomNativeAd()
{
    AdLoader adLoader = new AdLoader.Builder("/21775744923/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 custom native ad formats, ForCustomNativeAd() can be called multiple times with different format IDs in order to prepare the ad loader for more than one possible custom native ad formats.

Custom native ad events

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

private AdLoader adLoader;
adLoader.OnCustomNativeAdLoaded += HandleCustomNativeAdLoaded;
adLoader.OnAdFailedToLoad += HandleCustomNativeAdFailedToLoad;

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

void HandleCustomNativeAdLoaded(object sender, CustomNativeAdEventArgs args)
{
    this.customNativeAd = args.nativeAd;
}

The HandleCustomNativeAdFailedToLoad() method contains an AdFailedToLoadEventArgs parameter. The error message may be accessed by calling the GetMessage method on the LoadAdError field, as shown below:

void HandleCustomNativeAdFailedToLoad(object sender, AdFailedToLoadEventArgs args)
{
    string message = args.LoadAdError.GetMessage();
    Debug.Log("Ad Loader fail event received with message: " + message);
}

Display custom native ad formats

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

Here's an example implementation that accesses assets from a custom native ad:

private bool adLoaded;
private Texture2D mainImageTexture;
private string headline;
private CustomNativeAd customNativeAd;
...

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

Handle custom native ad's impressions and clicks

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

Record impressions

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

customNativeAd.RecordImpression();

Report clicks

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

customNativeAd.PerformClick("MainImage");

Respond to custom click actions

When a click is reported on a custom ad, the possible responses from the SDK are 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.

If you want to handle the click action for your custom native ad formats yourself instead of taking the user to a deep link or web browser, provide an optional Action<CustomNativeAd, string> in the AdLoader.Builder.ForCustomNativeAd() method. By setting this custom click action, you are overriding the SDK's click behavior. Here's an example that uses a custom click action to log a click for a given asset:

private void LoadCustomNativeAd()
{
    AdLoader adLoader = new AdLoader.Builder("/21775744923/example/native")
            .ForCustomNativeAd("10063170", HandleCustomNativeAdClicked)
            .Build();
    adLoader.OnCustomNativeAdLoaded += HandleCustomNativeAdLoaded;
    adLoader.LoadAd(createAdRequest());
}

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