> [!CAUTION] > **Caution:** The Google Mobile Ads for Unity native plugin is deprecated. Use [native overlay ads](https://developers.google.com/ad-manager/mobile-ads-sdk/unity/native-overlay.md.txt) instead. If you want to continue to use native ads rendered as part of the game environment, fill out the [Google Immersive InGame Ads beta request form](https://docs.google.com/forms/d/1uj-DfkLBqtP_KS8rxaYSF_E9Ebxxv74rFDlWNPpTHZw) and notify your account manager. This guide shows you how to use the native ads add-on to implement native ads in a Unity app, as well as some important things to consider along the way. Native ads match both the form and function of the user experience in which they're placed. They also match the visual design of the app they live within. Ad Manager's native ads format enables publishers to render ads that are seamless with content. You can use this technology to implement highly custom renderings that take full advantage of the native code in Unity apps. Native ads are shown using the same types of `GameObjects` with which you're already building your apps and can be formatted to match the visual design of the user experience in which they live. When a native ad loads, your app receives a native object that contains its assets and the Unity app, rather than the SDK, displays them. ## Prerequisites - Google Mobile Ads Unity plugin version 7.0.0 or higher. - Complete the [Get started guide](https://developers.google.com/ad-manager/mobile-ads-sdk/unity/quick-start.md.txt). - [Download](https://dl.google.com/googleadmobadssdk/GoogleMobileAds-native.unitypackage) and install the native ads add-on. ## Load native ad formats Native ads are loaded through the `AdLoader` class, which has its own `AdLoader.Builder` class to customize it during creation. The `ForNativeAd()` method configures the AdLoader to handle native ads. ```c# private void RequestNativeAd() { AdLoader adLoader = new AdLoader.Builder(INSERT_AD_UNIT_HERE) .ForNativeAd() .Build(); } ``` ## Register for AdLoader ad events To be notified when a native ad either successfully loads or fails to load, add delegates to the `AdLoader` class for the events listed below. ### OnNativeAdLoaded Invoked when a native ad is successfully loaded. It is required to have a delegate for this event to access the ad that loaded. ### OnAdFailedToLoad Invoked when a native ad fails to load. ## Load the ad Once you've finished building an `AdLoader`, call its `LoadAd()` method to request an ad: ```c# adLoader.LoadAd(new AdRequest.Builder().Build()); ``` ### Put the ad request together The code snippet below demonstrates how to build an `AdLoader` that is configured to request native ads, sets delegates for successful and failed ad loads, and makes an ad request. ```c# private void RequestNativeAd() { AdLoader adLoader = new AdLoader.Builder(INSERT_AD_UNIT_HERE) .ForNativeAd() .Build(); adLoader.OnNativeAdLoaded += this.HandleNativeAdLoaded; adLoader.OnAdFailedToLoad += this.HandleAdFailedToLoad; adLoader.LoadAd(new AdRequest.Builder().Build()); } ``` ### Handle failed ad loads The `OnAdFailedToLoad` event is of type `EventHandle`. Parsing the reason for an ad load failure from this event is shown below. ```c# private void RequestNativeAd() { ... adLoader.OnAdFailedToLoad += this.HandleNativeAdFailedToLoad; } private void HandleNativeAdFailedToLoad(object sender, AdFailedToLoadEventArgs args) { Debug.Log("Native ad failed to load: " + args.Message); } ``` ## Display a native ad When a Native Ad loads, the ad event for the corresponding ad format is invoked. Your app is then responsible for displaying the ad, though it doesn't necessarily have to do so immediately. ## Handle ad load The `OnNativeAdLoaded` event is of type `EventHandler`. The ad, encapsulated in a `NativeAd` object, can be retrieved from `NativeAdEventArgs` as shown: ```c# private NativeAd nativeAd; ... private void HandleNativeAdLoaded(object sender, NativeAdEventArgs args) { Debug.Log("Native ad loaded."); this.nativeAd = args.nativeAd; } ``` ## Retrieve native ad assets Once ads have loaded, their assets can be accessed as shown below. Graphical assets are returned as `Texture2D` objects and text assets are returned as `string` objects. ```c# private bool nativeAdLoaded; private NativeAd nativeAd; void Update() { ... if (this.nativeAdLoaded) { this.nativeAdLoaded = false; // Get Texture2D for the icon asset of native ad. Texture2D iconTexture = this.nativeAd.GetIconTexture(); // Get string for headline asset of native ad. string headline = this.nativeAd.GetHeadlineText(); } } private void HandleNativeAdLoaded(object sender, NativeAdEventArgs args) { Debug.Log("Native ad loaded."); this.nativeAd = args.nativeAd; this.nativeAdLoaded = true; } ``` Note that ad assets should only be accessed on the main thread, for example, from the `Update()` method of a Unity script. Also note the following assets are not always guaranteed to be present, and should be checked before being displayed: - `GetStarRating()` - `GetStore()` - `GetPrice()` - `GetAdvertiser()` - `GetIconTexture()` ### AdChoices asset It's a requirement to display the AdChoices ad asset as part of the native ad. Also, it's important that the AdChoices ad asset be easily seen, so choose background colors and images appropriately. ## Register GameObjects for ad asset You must register the `GameObject` for the ad asset to be displayed in your Unity app. If registration is successful, the method used to register the `GameObject` returns a `bool`. For a `List`, the method returns an `int` indicating the successfully registered `GameObject` count. If registration of an ad asset is unsuccessful, impressions and clicks on the corresponding native ad won't be recognized. ```c# if (!this.nativeAd.RegisterIconImageGameObject(icon)) { // Handle failure to register the icon ad asset. } ``` The `GameObject` that is registered for an ad asset must have a convex Collider component that is representative of the size and shape of the `GameObject`. If `GameObject` objects registered to ad assets are missing `Collider` components or have an incorrectly configured one, native ads will not operate correctly. In the code snippet below, a `BoxCollider` is added to `GameObject` that uses a `TextMesh` to display the headline ad asset of a native ad. Once the `BoxCollider` is attached to the `GameObject`, it will automatically scale to accommodate the text of the `TextMesh` component. ```c# // Create GameObject that will display the headline ad asset. GameObject headline = new GameObject(); headline.AddComponent(); headline.GetComponent().characterSize = 0.5 f; headline.GetComponent().anchor = TextAnchor.MiddleCenter; headline.GetComponent().color = Color.black; // Get string of the headline asset. string headlineText = this.nativeAd.GetHeadlineText(); headline.GetComponent().text = headlineText; // Add box collider to the GameObject which will automatically scale. headline.AddComponent(); ``` ## Demo The following code demonstrates how to retrieve the icon asset of a successfully loaded native ad, display the icon ad asset by setting the texture of a `Quad`, and register the `GameObject` to use to display the asset. This process of retrieving the ad asset and registering it with the native ad class should be repeated for each of the assets that the app displays. ```c# private GameObject icon; private bool nativeAdLoaded; private NativeAd nativeAd; ... void Update() { ... if (this.nativeAdLoaded) { this.nativeAdLoaded = false; // Get Texture2D for icon asset of native ad. Texture2D iconTexture = this.nativeAd.GetIconTexture(); icon = GameObject.CreatePrimitive(PrimitiveType.Quad); icon.transform.position = new Vector3(1, 1, 1); icon.transform.localScale = new Vector3(1, 1, 1); icon.GetComponent().material.mainTexture = iconTexture; // Register GameObject that will display icon asset of native ad. if (!this.nativeAd.RegisterIconImageGameObject(icon)) { // Handle failure to register ad asset. } } } ... private void HandleNativeAdLoaded(object sender, NativeAdEventArgs args) { Debug.Log("Native ad loaded."); this.nativeAd = args.nativeAd; this.nativeAdLoaded = true; } ```