How to Setup Unity Ads

Use this guide to configure the Unity Ads integration — the ad provider used whenever AdsProviderType.UnityAds is selected. Based directly on the installed UPM packages (com.unity.ads 4.17.0, com.unity.ads.ios-support 1.0.1) and the project's UnityAdsProxy implementation.

Architecture Context

When AdsManager resolves the active provider (see the AdMob guide's Architecture Context section for how that resolution works) to UnityAds, it instantiates a UnityAdsProxy, which implements Unity Ads' IUnityAdsInitializationListener / IUnityAdsLoadListener / IUnityAdsShowListener interfaces directly.

  • Unity Ads identifies your app by a Game ID (one per platform, a short numeric string from the Unity Dashboard), not by an app ID like AdMob's.
  • Ad slots are identified by Placement names (arbitrary strings you define in the Unity Dashboard), not by generated per-unit IDs — there's no / or ~ formatting to worry about, just whatever name you gave the placement.
  • Both the Game IDs and the Placement names are plain const string fields in AdsConstants.cs: UnityAdsGameIDiOS / UnityAdsGameIDAndroid, and UnityAdsBannerIDAndroid / UnityAdsInterstitialIDAndroid / UnityAdsRewardedIDAndroid (plus the matching ...IDiOS versions).
  • Unlike AdMob, there's no separate set of "test" placement constants. UnityAdsProxy.InitializeAds() passes GameConstants.IsDebugBuild() straight into Advertisement.Initialize(gameID, testMode, this) as the SDK's own testMode flag — the same placement name is used in both debug and production builds; Unity Ads' dashboard-side test mode is what decides whether test creatives are served.

Pre-Setup Checklist

  • A Unity Gaming Services project with Unity Ads enabled, and Game IDs generated for each platform you ship.
  • Placements created in the Unity Dashboard for every ad format you actually use (Banner / Interstitial / Rewarded), per platform.
  • com.unity.ads (4.17.0) and, if you ship iOS 14+, com.unity.ads.ios-support (1.0.1) installed via the Package Manager.

Main Procedure

Step 1: Set the Game IDs

In AdsConstants.cs, set UnityAdsGameIDAndroid and UnityAdsGameIDiOS to your project's real per-platform Game IDs from the Unity Dashboard.

Step 2: Set the Placement Names

Still in AdsConstants.cs, replace the placeholder-style names (Banner_Android, Interstitial_Android, Rewarded_Android, and their ...iOS counterparts) with the exact Placement names you created in the dashboard — these are case-sensitive and must match exactly.

public const string UnityAdsBannerIDAndroid = "YourBannerPlacementName";
public const string UnityAdsInterstitialIDAndroid = "YourInterstitialPlacementName";
public const string UnityAdsRewardedIDAndroid = "YourRewardedPlacementName";
// ...and the matching UnityAds...IDiOS constants

Step 3: Select Unity Ads as the Active Provider

Set GameConfig.AdsProviderMobile (and AdsProviderEditor, for testing in-editor) to AdsProviderType.UnityAds, or drive it from remote config by setting the "AdsProvider" key to "UnityAds".

Step 4: iOS 14+ Tracking Support

If you ship on iOS, make sure com.unity.ads.ios-support is installed — it's what lets Unity Ads correctly handle the App Tracking Transparency prompt flow on iOS 14 and later.

Step 5: Validate

  • Confirm OnInitializationComplete() logs "Unity Ads initialization complete." — if you instead see OnInitializationFailed, the Game ID is wrong for that platform, or Unity Ads isn't enabled for the linked Unity Gaming Services project.
  • In the dashboard, turn on Test Mode for the relevant placement to confirm test creatives show before flipping it off for release.

Common Edit Recipes

Recipe A: Rotate a Placement

If you rename or recreate a placement in the dashboard, just update the matching constant in AdsConstants.cs — UnityAdsProxy always reads placement names from there.

Recipe B: Add a New Ad Format

Create the new placement in the dashboard, add a matching constant to AdsConstants.cs, then wire a new load/show path through AdsManager the same way the existing Interstitial/Rewarded events (ON_INTERSTITIAL_*, ON_REWARDED_*) are wired — UnityAdsProxy follows the same Load*() / Show*() / OnUnityAds* pattern for every format.

Troubleshooting

  • Nothing happens, no init callback at all. InitializeAds() only calls Advertisement.Initialize() when Advertisement.isSupported is true — some editor/platform combinations aren't supported and this silently no-ops.
  • OnInitializationFailed fires. Almost always a wrong Game ID for the platform, or Unity Ads not yet enabled for the project in the dashboard.
  • Test creatives show in a real production build. Check GameConstants.IsDebugBuild() for that build configuration — it's the single flag that becomes the SDK's testMode parameter.
  • A specific placement never loads (OnUnityAdsFailedToLoad). Double check the AdsConstants string matches the dashboard placement name exactly, including case.
Edit this page