🎮 The Complete Guide to Implementing Unity Ads in Your Mobile Game — From Integration to Choosing Unity Source Code

Unity Ads, a monetization SDK, is one of the more integrated ad services for mobile games built in Unity. This guide shows you the full workflow from Unity Ads SDK setup to implementing interstitial and rewarded ads along with cooldown timers and scene persistence. As usual, complete C# code snippets will be provided.

Most mobile game developers sooner or later come to the decision of how to monetize their games, and the earlier you make this decision the less work you’ll have to do later on to refine your game to accommodate for a monetization solution. As far as monetization solutions go, Unity Ads is the easiest for developers that are already using Unity: because of its SDK's direct integration into the Unity Editor, support for both iOS and Android, and its ad formats of rewarded ads and interstitial ads that, while they do have an impact on your player base, are the least detracting from the player experience.

This guide goes through all the different aspects that are accounted for with Unity Ads. If you’re looking to implement ads in either a hyper-casual puzzle type game or a large scale mobile game, the concepts that are included in this guide, like centralized ad management or cooldown systems, can apply to any type of mobile game. You’ll also see the anticipated modifications to the SDK that all Unity developers should be familiar with prior to deploying their games.

When you finish this guide, you’ll have all of the infrastructure you need to implement Unity Ads with modular C# code that you can add to your project as is.

💰 Why Monetize a Mobile Game with Unity Ads?

What sets Unity Ads apart when compared to other mobile ad networks?

Free-to-play models have become the standard in mobile gaming. Unity's ad services align well with the model for a few reasons.

Free-to-play model: Players will be less reluctant to download a game if it is free. Unity's ad services aid this model as ad revenue is based on the player base (which is likely to be greater with free downloads) as opposed to the players' willingness to purchase the game.

Free choice: Ads that are rewarded are less disruptive to players. A player only chooses to watch an ad if there is a reward that is of value to them (greater game currency, an extra life, etc.). With this model, revenues and player loyalty improve.

Increased eCPMs: Unity's ad service integrates competitive markets for mobile game ads, thus allowing competitive eCPMs.

🧩 Unity Ads Implementation Sequence Overview

Mainly, the implementation follows this sequence:

1. Set up Unity Ads in the Services window to get the Game ID

2. Create AdsManager

3. Unity Ads SDK integration

4. Interstitial ads integration

5. Ad callbacks via listener interfaces

6. Game state pause and resume during ad playback

7. Game Over ads integration

8. ShowResult.Finished to validate

9. Game reward integration

10. Cooldown timer with DateTime

11. Countdown is shown on UI button

12. AdsManager is made persistent with DontDestroyOnLoad

⚠️ Important: Unity Ads API Changes to Know Before You Ship

--

Starting April 1, 2026, Unity's Advertisement Legacy Package may experience reduced ad performance. According to Unity, the recommended course of action is to adopt Ads through LevelPlay mediation as a bidder for continued full ad performance and access to the latest SDK features.

LevelPlay is Unity's mediation platform that allows multiple ad networks to compete for each impression, increasing fill rates and eCPMs over the use of a single network.

If your project uses the com.unity.ads Legacy Package (versions 3.x or earlier), start your migration before this deadline. The recommended path is now:

• Remove the Legacy Advertisement package from Package Manager

• Install the LevelPlay SDK (also available through Package Manager)

• Configure Unity Ads as a bidder within the LevelPlay dashboard

• Update your initialization code to use the LevelPlay API

The new path maintains the logic for showing ads through the callback interface. Init and manage ads through the LevelPlay console rather than Advertisement.Initialize(). For current migration steps, see the official LevelPlay documentation published by Unity.

⚙️ Step 1: How to Set up Unity Ads in the Unity editor

Link your project to your Unity Gaming Services account via Edit → Project settings → Services. Then, in the Project Settings, find the Monetization section and switch Unity Ads on.

Unity creates two Game IDs, and they are for Android and iOS. You will need both and keep them handy during SDK initialization.

For development, enable Test Mode to avoid inventory ads and use placeholder ads. This protects the account against invalid traffic and keeps testing stable.

To install the Unity Ads SDK, open Window → Package Manager. In the search bar, open the Advertisement package and install the most updated version. Before you choose the package version, make a note of the significant API change that is mentioned later in this guide.

🧠 Step 2: Building a Centralized Unity Ads Manager with C#

Instead of having ads calls strewn through your game’s scripts, put everything in one AdsManager MonoBehavior. In addition to helping you avoid duplicate initialization, having everything in one centralized place helps to manage cooldowns and ads state, and helps with testing.

using UnityEngine;

using UnityEngine.Advertisements;

public class AdsManager : MonoBehaviour, IUnityAdsInitializationListener

{
    [SerializeField] private string _androidGameId = "YOUR_ANDROID_GAME_ID";

    [SerializeField] private string _iOSGameId = "YOUR_IOS_GAME_ID";

    [SerializeField] private bool _testMode = true;

    private string _gameId;

    public static AdsManager Instance { get; private set; }

    private void Awake()
    {
        if (Instance != null && Instance != this)
        {
            Destroy(gameObject);
            return;
        }

        Instance = this;
        DontDestroyOnLoad(gameObject);
        InitializeAds();
    }

    private void InitializeAds()
    {
#if UNITY_IOS
        _gameId = _iOSGameId;
#elif UNITY_ANDROID
        _gameId = _androidGameId;
#endif

        if (!Advertisement.isInitialized && Advertisement.isSupported)
        {
            Advertisement.Initialize(_gameId, _testMode, this);
        }
    }

    public void OnInitializationComplete()
    {
        Debug.Log("Unity Ads initialization complete.");
    }

    public void OnInitializationFailed(
        UnityAdsInitializationError error,
        string message)
    {
        Debug.LogError(
            $"Unity Ads initialization failed: {error} - {message}");
    }
}

🔧 Step 3: Understanding Unity Ads SDK Initialization

Unity Ads SDK initialization requires a Game ID string, a boolean for test mode, and a listener implementing IUnityAdsInitializationListener. The two callback methods, OnInitializationComplete and OnInitializationFailed, provide the means of handling the result of the Unity Ads SDK initialization and subsequently controlling the ability to load and show ads.

Before calling Initialize, always verify that Advertisement.isInitialized. To handle platforms on which ads cannot be shown, including the Unity Editor in the absence of test mode, check Advertisement.isSupported.

📺 Step 4: Embedding Interstitial Ads Using Unity

Interstitial Ads are used to show full screen advertisements at suitable ad break points from which you can proceed to the next point of ad playback like transitioning to the next game level full screen, at game over, or while returning to the main menu. For this, you will create a script to load and show Interstitial Ads:

using UnityEngine;
using UnityEngine.Advertisements;

public class InterstitialAd : MonoBehaviour,
    IUnityAdsLoadListener,
    IUnityAdsShowListener
{
    [SerializeField] private string _androidAdUnitId = "Interstitial_Android";
    [SerializeField] private string _iOSAdUnitId = "Interstitial_iOS";

    private string _adUnitId;

    private void Awake()
    {
#if UNITY_IOS
        _adUnitId = _iOSAdUnitId;
#elif UNITY_ANDROID
        _adUnitId = _androidAdUnitId;
#endif
    }

    public void LoadAd()
    {
        Debug.Log($"Loading interstitial ad: {_adUnitId}");
        Advertisement.Load(_adUnitId, this);
    }

    public void ShowAd()
    {
        Debug.Log($"Showing interstitial ad: {_adUnitId}");
        Advertisement.Show(_adUnitId, this);
    }

    // IUnityAdsLoadListener callbacks
    public void OnUnityAdsAdLoaded(string adUnitId)
    {
        Debug.Log($"Interstitial ad loaded: {adUnitId}");
    }

    public void OnUnityAdsFailedToLoad(
        string adUnitId,
        UnityAdsLoadError error,
        string message)
    {
        Debug.LogError(
            $"Failed to load interstitial ad {adUnitId}: {error} - {message}");
    }

    // IUnityAdsShowListener callbacks
    public void OnUnityAdsShowFailure(
        string adUnitId,
        UnityAdsShowError error,
        string message)
    {
        Debug.LogError(
            $"Failed to show interstitial ad {adUnitId}: {error} - {message}");
    }

    public void OnUnityAdsShowStart(string adUnitId)
    {
        Debug.Log($"Interstitial ad started: {adUnitId}");
    }

    public void OnUnityAdsShowClick(string adUnitId)
    {
        Debug.Log($"Interstitial ad clicked: {adUnitId}");
    }
}

IUnityAdsLoadListener reacts to ads finishing loading and failed loading callback events.

IUnityAdsShowListener reacts to start, click, complete, and failure events of ads that are shown.

Implementing both interfaces in a single class is a good idea to keep your logic clear. Always call LoadAd() in OnUnityAdsShowComplete to ensure the ad is loaded before it is required by the player.

⏸️ Step 6: How Do You Pause and Resume the Game During an Ad?

Once a full-screen ad is shown, gameplay needs to be fully stopped. You cannot allow timers, physics, or sounds to continue running in the background. Following is a code snippet using a combination of Time.timeScale and AudioListener.pause:

using UnityEngine;
using UnityEngine.Advertisements;

public class AdPauseHandler : MonoBehaviour, IUnityAdsShowListener
{
    public void PauseGameForAd()
    {
        Time.timeScale = 0f;
        AudioListener.pause = true;
    }

    public void ResumeGameAfterAd()
    {
        Time.timeScale = 1f;
        AudioListener.pause = false;
    }

    public void OnUnityAdsShowStart(string adUnitId)
    {
        PauseGameForAd();
    }

    public void OnUnityAdsShowComplete(
        string adUnitId,
        UnityAdsShowCompletionState showCompletionState)
    {
        ResumeGameAfterAd();
    }

    public void OnUnityAdsShowFailure(
        string adUnitId,
        UnityAdsShowError error,
        string message)
    {
        ResumeGameAfterAd();
    }

    public void OnUnityAdsShowClick(string adUnitId)
    {
        // Optional: track click events
    }
}

This code conveniently ensures the game is unpaused after an ad is shown, clicked, completed, or

🎁 Step 7: How to Add Rewarded Ads to the Game Over Screen

Rewarded Ads are the leading format for mobile game ad monetization. Players are naturally motivated to watch a video ad in exchange for a meaningful reward, like a free second chance, extra game currency, or a game power-up. To implement this, add a button for a rewarded ad to your Game Over screen.

Here is sample code for Unity, C#

using UnityEngine.Advertisements;

using UnityEngine.UI;

using UnityEngine;

public class RewardedAd : MonoBehaviour, IUnityAdsLoadListener, IUnityAdsShowListener
{
    [SerializeField] private string _androidAdUnitId = "Rewarded_Android";
    [SerializeField] private string _iOSAdUnitId = "Rewarded_iOS";
    [SerializeField] private Button _showAdButton;

    private string _adUnitId;

    private void Awake()
    {
#if UNITY_IOS
        _adUnitId = _iOSAdUnitId;
#elif UNITY_ANDROID
        _adUnitId = _androidAdUnitId;
#endif
        _showAdButton.interactable = false;
    }

    private void Start()
    {
        LoadAd();
    }

    public void LoadAd()
    {
        Debug.Log($"Loading rewarded ad: {_adUnitId}");
        Advertisement.Load(_adUnitId, this);
    }

    public void ShowAd()
    {
        _showAdButton.interactable = false;
        Advertisement.Show(_adUnitId, this);
    }

    public void OnUnityAdsAdLoaded(string adUnitId)
    {
        Debug.Log($"Rewarded ad loaded: {adUnitId}");
        _showAdButton.interactable = true;
    }

    public void OnUnityAdsFailedToLoad(
        string adUnitId,
        UnityAdsLoadError error,
        string message)
    {
        Debug.LogError(
            $"Failed to load rewarded ad {adUnitId}: {error} - {message}");
        _showAdButton.interactable = false;
    }

    public void OnUnityAdsShowFailure(
        string adUnitId,
        UnityAdsShowError error,
        string message)
    {
        Debug.LogError(
            $"Failed to show rewarded ad {adUnitId}: {error} - {message}");
    }

    public void OnUnityAdsShowStart(string adUnitId)
    {
        Debug.Log($"Rewarded ad started: {adUnitId}");
    }
}

✅ Step 8: How Do You Validate A Reward Using ShowResult.Finished?

In the context of the current SDK and using the Unity SDK, ShowResult.Finished refers to the UnityAdsShowCompletionState.COMPLETED. To validate a reward, you can implement the method to complete on ad show, as follows:

public void OnUnityAdsShowComplete(
    string adUnitId,
    UnityAdsShowCompletionState showCompletionState)
{
    if (adUnitId.Equals(_adUnitId) &&
        showCompletionState == UnityAdsShowCompletionState.COMPLETED)
    {
        // Player watched the full ad — reward is valid
        GrantReward();
    }
    else if (showCompletionState == UnityAdsShowCompletionState.SKIPPED)
    {
        Debug.Log("Player skipped the ad. No reward granted.");
    }
    else if (showCompletionState == UnityAdsShowCompletionState.UNKNOWN)
    {
        Debug.LogWarning("Ad completion state unknown. No reward granted.");
    }
}

You should never consider the reward valid for SKIPPED or UNKNOWN states. If you do, you allow reward farming and negatively affect your in-game economy.

🎮 Step 9: How Do You Connect a Rewarded Ad to Gameplay in Unity?

The reward is specific to your game and can be a continue, coins, lives, or a power-up. To connect your RewardedAd to your GameManager, you can use an event or make a direct reference.

using UnityEngine;

using UnityEngine.Advertisements;

public class RewardedAdWithGameplay : MonoBehaviour, IUnityAdsLoadListener, IUnityAdsShowListener
{
    [SerializeField] private string _androidAdUnitId = "Rewarded_Android";
    [SerializeField] private string _iOSAdUnitId = "Rewarded_iOS";
    [SerializeField] private GameManager _gameManager;

    private string _adUnitId;

    private void Awake()
    {
#if UNITY_IOS
        _adUnitId = _iOSAdUnitId;
#elif UNITY_ANDROID
        _adUnitId = _androidAdUnitId;
#endif
    }

    private void Start()
    {
        LoadAd();
    }

    public void LoadAd()
    {
        Advertisement.Load(_adUnitId, this);
    }

    public void ShowAd()
    {
        Advertisement.Show(_adUnitId, this);
    }

    public void OnUnityAdsAdLoaded(string adUnitId) { }

    public void OnUnityAdsFailedToLoad(
        string adUnitId,
        UnityAdsLoadError error,
        string message) { }

    public void OnUnityAdsShowStart(string adUnitId) { }

    public void OnUnityAdsShowClick(string adUnitId) { }

    public void OnUnityAdsShowFailure(
        string adUnitId,
        UnityAdsShowError error,
        string message) { }

    public void OnUnityAdsShowComplete(string adUnitId, UnityAdsShowCompletionState showCompletionState)

⏱️ Step 10: How to Implement a Cooldown Timer for Unity Ads

To maintain the player experience and to prevent your game from being flagged for poor ad quality, it is important to find a balance for how frequently ads are shown to players. A cooldown system is implemented using DateTime, where ads are prevented from showing in a configurable time window.

using System;
using UnityEngine;

public class AdCooldownManager : MonoBehaviour
{
    [SerializeField] private float _cooldownMinutes = 3f;

    private DateTime _lastAdShownTime;
    private bool _hasShownFirstAd = false;

    public static AdCooldownManager Instance { get; private set; }

    private void Awake()
    {
        if (Instance != null && Instance != this)
        {
            Destroy(gameObject);
            return;
        }

        Instance = this;
        DontDestroyOnLoad(gameObject);
    }

    public bool CanShowAd()
    {
        if (!_hasShownFirstAd) return true;

        TimeSpan timeSinceLast = DateTime.Now - _lastAdShownTime;
        return timeSinceLast.TotalMinutes >= _cooldownMinutes;
    }

    public void RegisterAdShown()
    {
        _lastAdShownTime = DateTime.Now;
        _hasShownFirstAd = true;
    }

    public float GetRemainingCooldownSeconds()
    {
        if (!_hasShownFirstAd) return 0f;

        TimeSpan remaining = TimeSpan.FromMinutes(_cooldownMinutes) - (DateTime.Now - _lastAdShownTime);
        return Mathf.Max(0f, (float)remaining.TotalSeconds);
    }
}

🔘 Step 11: How To Show a Cooldown Timer Text on a UI Button

Instead of showing a generic disabled button, you can show the remaining time for the next ad access:

using System.Collections;

using TMPro;

using UnityEngine;

using UnityEngine.UI;

public class AdButtonCooldownUI : MonoBehaviour
{
    [SerializeField] private Button _adButton;
    [SerializeField] private TextMeshProUGUI _buttonText;
    [SerializeField] private string _readyText = "Watch Ad for Reward";
    [SerializeField] private float _updateInterval = 1f;

    private Coroutine _cooldownCoroutine;

    private void OnEnable()
    {
        UpdateButtonState();
        _cooldownCoroutine = StartCoroutine(CooldownUpdateRoutine());
    }

    private void OnDisable()
    {
        if (_cooldownCoroutine != null)
            StopCoroutine(_cooldownCoroutine);
    }

    private IEnumerator CooldownUpdateRoutine()
    {
        while (true)
        {
            yield return new WaitForSeconds(_updateInterval);
            UpdateButtonState();
        }
    }

    private void UpdateButtonState()
    {
        if (AdCooldownManager.Instance == null) return;

        float remaining = AdCooldownManager.Instance.GetRemainingCooldownSeconds();

        if (remaining <= 0f)
        {
            _adButton.interactable = true;
            _buttonText.text = _readyText;
        }
        else
        {
            _adButton.interactable = false;

            int minutes = Mathf.FloorToInt(remaining / 60f);
            int seconds = Mathf.FloorToInt(remaining % 60f);

            _buttonText.text = $"Available in {minutes:00}:{seconds:00}";
        }
    }
}

Using WaitForSecondsRealtime instead of WaitForSeconds will pause the countdown and cool down even if the game is paused.

🌐 Step 12: How To Make AdsManager Persist in All Scenes in Unity

As explained in Step 2, the AdsManager under the Paths SDK will have DontDestroyOnLoad invoked in its Awake() method. Therefore, the SDK will not lose all of its data, keeping the cooldown for Game Ads, and remaining Ads will always be loaded.

Having the singleton pattern with a check for duplicate instances will also prevent having a bunch of AdsManager objects when a loaded scene with the prefab is loaded again.

For better organization when working on a larger project, it’s highly recommended that you put the AdsManager prefab in either a persistent scene or a scene that is designated a bootstrapper scene, which should load once and not unload thereafter. This is especially useful for larger projects where you want the ad states to persist alongside other services like analytics or data saves.

🏆 What Are the Best Practices for Mobile Ad Implementation in Unity?

Load ads before they are needed. Always call LoadAd() once an ad has been shown, not right before you are about to show the Game Over screen. Loaded ads are shown immediately, and unloaded ads are either delayed or shown as a failure.

Never show an ad without context for the player. An interstitial between levels is good practice, while an interstitial shown mid-game may confuse or frustrate a player. Placement matters as much as frequency.

Observing a cooldown is a good practice. Setting a baseline minimum of three minutes between interstitial ads is reasonable. Adjust the minimum according to the length of the game session.

Failure of an ad should not be a dead end. Implement OnUnityAdsFailedToLoad and OnUnityAdsShowFailure. Failure should log the error, hide any ad buttons (should no ad be available), and retry after a delay.

Finally, test your project on an actual phone or tablet. The ads in the Editor are often unpredictable.

Test Mode on a real device is the only way to fully test your implementation.

Analyze performance through placement. Separate ad unit IDs for interstitials and rewards in the Unity Dashboard and analyze their eCPMs individually.

Move to LevelPlay before the Legacy Package deprecation in April 2026 to remove the negative impact of diminishing performance.

❓ Frequently Asked Questions About Implementing Unity Ads

🎬 What are the differences between interstitial and rewarded ads in Unity?

Interstitial ads offer full-screen advertisements that are presented to the player at predetermined places or junctures in the game flow. These ads come without player control. On the other hand, rewards ads satiate players’ requests. Ads are opt-in and are traded with an in-game benefit. Rewarded ads increase eCPMs and player retention as it adds value to the game experience.

🆔 How do I find my Unity Ads Game ID?

After a project in the Unity Dashboard has monetization enabled, two Game IDs (one for each operating system) are created. These are located in Monetize > Setup > Game IDs in the Unity Dashboard. Fill in these values to the serialized fields in the AdsManager script in the Unity Inspector.

🖥️ Why aren’t Unity Ads interstitials shown in the Editor?

The Unity Editor is used for testing, and as such, does not utilize real advertisements. To see mock ads, you must enable Test Mode and either build to a device or an emulator to test your build. Make sure initialization has been completed, signified by the onInitializationComplete() method being called, before calling Advertisement.Load().

🎁 What does UnityAdsShowCompletionState.COMPLETED mean?

UnityAdsShowCompletionState.COMPLETED indicates the player finished watching a rewarded ad without skipping it. This state is the only one under which a reward should be granted. The other two states, SKIPPED and UNKNOWN, mean the ad was not viewed, and therefore a reward should not be granted.

⏱️ At what frequency should I place interstitial ads in a mobile game?

In mobile games, one interstitial per three to five minutes of active gameplay is a safe rule of thumb. Issuing more ads will increase revenue in the short term but increase uninstalls in the long term. Implement the AdCooldownManager pattern from Step 10 to set a minimum time between ads and adjust the time based on the average session of your game.

🔄 Should I use the Unity Ads Legacy Package or LevelPlay in 2026?

In 2026, Unity endorses using LevelPlay and Unity Ads for mediation over using the Legacy Advertisement Package. Starting on April 1, 2026, the performance of ads in the Legacy Package may decrease. For new projects, use LevelPlay first. For older projects that use the Legacy Package, plan for a migration to LevelPlay.

⏳ What is the ideal Unity Ads cooldown duration for casual mobile games?

For hyper-casual and casual puzzle games with sessions of two to five minutes, set a cooldown between interstitial ads of two to three minutes. For longer sessions, set the cooldown between ads to five minutes or more. To strike a balance between revenue and retention, test different cooldown durations against player retention through A/B testing.

🕹️ Unity Ads and Ready Made Unity Projects

For a single game, it’s perfectly fine to build an ads system manually, but when you plan on publishing a few more games down the line, or when you work with game source codes from the Unity game source code marketplace, it’s a different ballgame.

Ready Made solutions like unity 2d game templates and unity 3d game code from UnityTemplate.com include wired ad placeholders, and will save you a lot of time. Instead of building AdsManager, cooldown systems, and UI from scratch, you modify an existing implementation that is already tested.

Unity premium game templates are a great help in this regard. Complete templates from a reputable unity game code repository come with dedicated game monetization scaffolding. You get game, UI, and ad integration in a single cohesive system that you can then modify to suit your design in terms of ad unit IDs, cooldowns, and rewards.

If you are creating a multiplayer game, unity multiplayer game codes will up the complexity of ad timing, since you must pause the game for all users connected to the network. Well-thought out unity assets and codes that accommodate this will significantly reduce your time to develop.

💰 Should You Buy Unity Source Code?

Purchasing Unity source code saves time and money if the base game design and aesthetics fit your idea. The math is simple: if a template costs $50-$200 and saves 2-4 weeks of development, then the return on investment is positive.

However, in order to maximize your profits, there are some things that you should consider before buying unity game development assets. The first thing you should look for is documentation. If the seller takes the time to write details on how the ads are integrated, then that's great! But if there is no documentation and you have no source code, then you're stuck in reverse engineering land. (no bueno)

Another thing to focus on is the code architecture. If the seller used the centralized manager pattern, then the ad calls are contained in the central manager. But if they threw calls all over the place in scripts that are tied to each scene, well, then they lost the pattern and you're losing time and money.

Lastly, look at the projects listed on the store page and see if the seller has made any updates to the code in the past. Rather quickly look through the files and see if the seller is using the legacy package. That's a huge red flag.

Unity Template has reviewed each code listed and has built their catalog around each of these points. If these conditions are checked and all passes, then a source code purchase may be justified.

🚀 How to Bring Your Unity Game to Market Quickly

First things first, the integration of ads in Unity is a complicated process to execute as it requires you to set up initialization, handle callbacks, validate rewards, and manage cooldowns. Following the guides provided gives you a flexibility of building this easily, but doing it from scratch for every game makes your game development process longer by weeks.

Rather than following the guides and doing the development process from scratch, you can take a look at the Unity game development assets for sale at UnityTemplate.com and see if you like any of the 13,000+ highly rated assets. They have 2d and 3d game templates, game codes, premium game templates, and multiplayer game codes that have been checked for quality. You can find Unity game code for puzzle games, runners, or something that is more elaborate. UnityTemplate.com has a choice of a number of game codes that are ready to go.