Using the Native Ad API in Unity

The Native Ad API allows you to build a customized experience for the ads you show in your app. When using the Native Ad API, instead of receiving an ad ready to be displayed, you will be able to construct a custom view where the ad is shown.

In this guide we will implement the following native ad placement. You will create a native ad with the following components:

View #1: Ad Icon

View #2: Ad Title

View #3: Sponsored Label

View #4: AdChoices Icon

View #5: MediaView

View #6: Social Context

View #7: Ad Body

View #8: Call to Action button




Native Ad Steps

Step 1: Requesting a Native Ad

Step 2: Creating your Native Ad Layout

Step 3: Populating your Layout Using the Ad's Metadata

Step 1: Requesting a Native Ad

The first step toward displaying a native ad is to create an NativeAd object in a C# script attached to a GameObject.

...
using AudienceNetwork;
...
public class NativeAdTest : MonoBehaviour
{
    private NativeAd nativeAd;
    ...
    // UI elements in scene
    [Header("Text:")]
    public Text advertiserName;
    public Text socialContext;
    public Text body;
    public Text sponsored;
    [Header("Images:")]
    public GameObject mediaView;
    public GameObject iconImage;
    [Header("Buttons:")]
    // This doesn't have be a button - it can also be an image
    public Button callToActionButton;
    [Header("Ad Choices:")]
    [SerializeField]
    private AdChoices adChoices

    ...

    // Load Ad button
    public void LoadAd()
    {
        if (this.nativeAd != null) {
            this.nativeAd.Dispose();
        }
        // Create a native ad request with a unique placement ID (generate your own on the Facebook app settings).
        // Use different ID for each ad placement in your app.
        this.nativeAd = new AudienceNetwork.NativeAd("YOUR_PLACEMENT_ID");

        // Wire up GameObject with the native ad. The game object should be a child of the canvas.
        nativeAd.RegisterGameObject(gameObject);

        // Set delegates to get notified on changes or when the user interacts with the ad.
        nativeAd.NativeAdDidLoad = (delegate() {
            ...
        });
        nativeAd.NativeAdDidDownloadMedia = (delegate() {
            Debug.Log("Native ad media downloaded");
        });
        nativeAd.NativeAdDidFailWithError = (delegate(string error) {
            Debug.Log("Native ad failed to load with error: " + error);
        });
        nativeAd.NativeAdWillLogImpression = (delegate() {
            Debug.Log("Native ad logged impression.");
        });
        nativeAd.NativeAdDidClick = (delegate() {
            Debug.Log("Native ad clicked.");
        });

        // Initiate a request to load an ad.
        nativeAd.LoadAd();

        Debug.Log("Native ad loading...");
    }
    ...

}

We will be coming back later to add code to the NativeAdDidLoad callback.

Step 2: Creating your Native Ad Layout

The next step is to extract the ad metadata and use its properties to build your customized native UI.

Please consult our guidelines for native ads when designing native ads in your app.

In your scene or Prefab, you can create a GameObject as a container for the native ad, and add the elements mentioned in at the beginning of this document:

public class NativeAdTest : MonoBehaviour
{
    private NativeAd nativeAd;

    // UI elements in scene
    [Header("Text:")]
    public Text advertiserName;
    public Text socialContext;
    public Text body;
    public Text sponsored;
    [Header("Images:")]
    public GameObject mediaView;
    public GameObject iconImage;
    [Header("Buttons:")]
    // This doesn't be a button - it can also be an image
    public Button callToActionButton;
    [Header("Ad Choices:")]
    [SerializeField]
    private AdChoices adChoices;

    ...
}

Here is how they can be associated with the views in the editor:

Notice that for the Ad Choices icon you can use the AdChoices Prefab provided by the Audience Network Unity SDK. For the ad icon and Media View, simply create empty GameObject with desired location and size, the Audience Network Unity SDK will handle populating them with the images or media.

Step 3: Populating your Layout Using the Ad's Metadata

Scenario 1: Immediately display the ad once it is loaded successfully. Modify the NativeAdDidLoad callback above to retrieve the Native Ad's properties and display it as follows:

...
public class NativeAdTest : MonoBehaviour
{
    private NativeAd nativeAd;
    ...

    public void LoadAd()
    {
        if (this.nativeAd != null) {
            this.nativeAd.Dispose();
        }
        // Create a native ad request with a unique placement ID (generate your own on the Facebook app settings).
        // Use different ID for each ad placement in your app.
        this.nativeAd = new AudienceNetwork.NativeAd("YOUR_PLACEMENT_ID");

        // Wire up GameObject with the native ad. The game object should be a child of the canvas.
        nativeAd.RegisterGameObject(gameObject);

        // Set delegates to get notified on changes or when the user interacts with the ad.
        nativeAd.NativeAdDidLoad = (delegate() {
            // Register game objects for interactions.
            // MediaView will be used for impression logging.
            // CallToActionButton will be used for click logging.
            nativeAd.RegisterGameObjectsForInteraction((RectTransform)mediaView.transform, (RectTransform)callToActionButton.transform,
                    (RectTransform)iconImage.transform);
            Debug.Log("Native ad loaded.");

            // Associate the native ad instance with the Ad Choices Prefab object
            adChoices.SetAd(nativeAd);

            // Set the text with the text views
            advertiserName.text = nativeAd.AdvertiserName;
            socialContext.text = nativeAd.SocialContext;
            body.text = nativeAd.Body;
            sponsored.text = nativeAd.SponsoredTranslation;

            // Set the text of the call to action button
            callToActionButton.GetComponentInChildren<Text>().text = nativeAd.CallToAction;
        });
        nativeAd.NativeAdDidDownloadMedia = (delegate() {
            Debug.Log("Native ad media downloaded");
        });
        nativeAd.NativeAdDidFailWithError = (delegate(string error) {
            Debug.Log("Native ad failed to load with error: " + error);
        });
        nativeAd.NativeAdWillLogImpression = (delegate() {
            Debug.Log("Native ad logged impression.");
        });
        nativeAd.NativeAdDidClick = (delegate() {
            Debug.Log("Native ad clicked.");
        });

        // Initiate a request to load an ad.
        nativeAd.LoadAd();

        Debug.Log("Native ad loading...");

    }
    ...
}

The SDK will log the impression and handle the click automatically.

Scenario 2: Display the ad in a few seconds or minutes after it is successfully loaded. You should check whether the ad has been invalidated before displaying it.

In case of not showing the ad immediately after the ad has been loaded, the developer is responsible for checking whether or not the ad has been invalidated. Once the ad is successfully loaded, the ad will be valid for 60 mins. You will not get paid if you are showing an invalidated ad.

In such scenario, you can use another function to show the ad instead doing that directly in the NativeAdDidLoad callback directly. For example:

public class NativeAdTest : MonoBehaviour
{
    private NativeAd nativeAd;
    ...

    public void LoadAd()
    {
        ...
        this.nativeAd = new AudienceNetwork.NativeAd("YOUR_PLACEMENT_ID");
        ...
        nativeAd.NativeAdDidLoad = (delegate() {
            Debug.Log("Native ad loaded!");
        });
        ...
        nativeAd.LoadAd();
    }

    // Another function to show the ad
    public void ShowAd()
    {
        if (this.nativeAd == null || !this.nativeAd.IsValid()) {
            return;
        }
        // Register game objects for interactions.
        // MediaView will be used for impression logging.
        // CallToActionButton will be used for click logging.
        nativeAd.RegisterGameObjectsForInteraction((RectTransform)mediaView.transform, (RectTransform)callToActionButton.transform,
                (RectTransform)iconImage.transform);

        // Associate the native ad instance with the Ad Choices Prefab object
        adChoices.SetAd(nativeAd);

        // Set the text with the text views
        advertiserName.text = nativeAd.AdvertiserName;
        socialContext.text = nativeAd.SocialContext;
        body.text = nativeAd.Body;
        sponsored.text = nativeAd.SponsoredTranslation;

        // Set the text of the call to action button
        callToActionButton.GetComponentInChildren<Text>().text = nativeAd.CallToAction;
    }
    ...
}

Next Steps

Follow our guides for integrating different Ad Formats in your Unity app:

Once you're ready to go live with your app and monetize, submit your app for review after ensuring it it complies with Audience Network policies and the Facebook community standards.