Installation
Folder Structure After Install
After purchasing, download the zip, extract it, and copy the addons/ folder into your Godot project root.
unity_ads_plugin — the AAR path is hardcoded in the export plugin.Autoload, not a scene node
UnityAds is a global autoload (singleton). Enabling the plugin registers it for you (check Project Settings → Globals → Autoload). You call it from any script as UnityAds.initialize(), UnityAds.show_interstitial() and so on.
UnityAds.gd into a scene as a Node. A second copy connects to the native plugin again, and every signal fires twice. It also has no _ready() timing guarantee relative to your own scene. Use the autoload only.UnityAds still exists but every call just prints "Plugin NOT found" and does nothing. Test ads on a real Android device.Enable the Plugin
- Open your project in Godot 4.4
- Go to Project → Project Settings → Plugins
- Find UnityAdsPlugin in the list and toggle it ON
- Godot automatically adds
UnityAdsas a global autoload singleton
Screenshot: Project Settings → Plugins → UnityAdsPlugin enabled
Unity Dashboard Setup
Get Your Game ID
- Go to cloud.unity.com and sign in
- Select your project (or create a new one)
- Go to Monetization → Ad Units in the left menu
- Your Game ID is shown at the top of this page — copy it
- Open
UnityAds.gdand replace theGAME_IDconstant
# Replace with your real Game ID from Unity Dashboard const GAME_ID = "YOUR_GAME_ID_HERE" const TEST_MODE = true # set false for production build
Screenshot: Unity Dashboard → Monetization → Ad Units — Game ID location
Placement IDs — Default vs Manual
Unity auto-creates Interstitial and Rewarded placements when you set up your project. Banner must be created manually.
| Ad Type | Default Placement ID | Created By |
|---|---|---|
| Interstitial | Interstitial_Android |
AUTO |
| Rewarded | Rewarded_Android |
AUTO |
| Banner | Banner_Android |
MANUAL |
Banner_Android, platform to Android, format to Banner. Without this, the banner will not load and on_banner_failed_to_load fires (nothing appears on screen, so watch the log).Screenshot: Unity Dashboard → Add Ad Unit → Banner_Android setup
UnityAds.gd — you don't need to change them as long as you use the default names above. If your dashboard placements are named differently, edit the PLACEMENT_* constants at the top of UnityAds.gd to match exactly (they are case-sensitive).Install Android Build Templates
- Go to Project → Install Android Build Template…
- Click Install and wait for Godot to finish
- The
android/build/folder will now exist in your project - Requires JDK 17 and the Android SDK — see Step 4: Export Guide
Screenshot: Project → Install Android Build Template menu
Export Guide
Requirements Checklist
| Item | Required | Why |
|---|---|---|
| Godot | 4.4 (4.2+ works) | Plugin uses the Godot v2 Android plugin format |
| JDK | JDK 17 | Godot 4.4 Gradle build and the compiled AAR both target Java 17. JDK 21+ can cause Gradle errors |
| Android SDK | Platform 35, Build-Tools 35.0.1, Platform-Tools, Cmdline-Tools | Godot 4.4 export defaults |
| Min SDK | 24 or higher | The plugin AAR declares minSdkVersion 24. Lower values break the manifest merge |
| Unity Ads SDK | 4.12.3 | Downloaded from Maven Central automatically on first build |
| Internet | On first build | Gradle downloads the Unity Ads SDK and its dependencies |
| Build template | Installed (Step 3) | Must match your editor version — reinstall after upgrading Godot |
A. Install JDK 17 and the Android SDK
- Install JDK 17 (Temurin or OpenJDK 17). Verify in a terminal with
java -version— it should print17.x - Install the Android SDK, either through Android Studio → SDK Manager or the command-line tools
- In the SDK Manager, install Android SDK Platform 35, Build-Tools 35.0.1, Platform-Tools and Command-line Tools
- If Godot asks for extra SDK components (such as NDK or CMake) during setup, install the versions it names
# Run from your cmdline-tools/latest/bin folder sdkmanager "platform-tools" "platforms;android-35" "build-tools;35.0.1" "cmdline-tools;latest" sdkmanager --licenses
B. Point Godot at the JDK and SDK
- Open Editor → Editor Settings → Export → Android
- Set Java SDK Path to your JDK 17 folder (the folder that contains
bin) - Set Android SDK Path to your Android SDK folder
- Set the Debug Keystore, user and password (see the keystore section below)
Screenshot: Editor Settings → Export → Android — Java SDK Path and Android SDK Path
C. Create Keystores
Use keytool from your JDK 17 bin folder.
keytool -genkey -v -keystore release.keystore -alias my_alias -keyalg RSA -keysize 2048 -validity 10000
keytool -keyalg RSA -genkeypair -alias androiddebugkey -keypass android -keystore debug.keystore -storepass android -dname "CN=Android Debug,O=Android,C=US" -validity 9999 -deststoretype pkcs12
D. Android Export Preset
- Go to Project → Export → Add… → Android
- Turn on Use Gradle Build
- Set Min SDK to
24or higher - Under Architectures, enable
arm64-v8a(addarmeabi-v7aif you support older devices) - Enable the INTERNET and ACCESS_NETWORK_STATE permissions
- Fill in the Release keystore, user and password
── Gradle Build ────────────────────────────── [✓] Use Gradle Build Min SDK: 24 (or higher) ── Architectures ───────────────────────────── [✓] arm64-v8a [ ] armeabi-v7a (optional) ── Permissions ─────────────────────────────── [✓] INTERNET [✓] ACCESS_NETWORK_STATE Note: AD_ID permission is auto-injected by plugin. There is no plugin checkbox to tick — the export plugin adds the AAR automatically. ── Keystore (release build) ────────────────── Release Keystore: path/to/release.keystore Release User: my_alias Release Password: your_password
Screenshot: Export dialog — Gradle Build enabled, Min SDK 24, permissions checked, Release keystore set
E. Export the Build
- In the Export dialog, uncheck "Export With Debug" for a release build
- Click Export Project… (not One-Click Deploy) and choose a file name
- Choose APK for direct install and testing, or AAB for Play Store upload (AAB needs Gradle Build, which you already enabled)
- Wait for Gradle. The first build is slow because it downloads Gradle, the Unity Ads SDK and other dependencies
- Install the APK on a real Android device and test with
TEST_MODE = truefirst
1. Use a Release Keystore and export a Release build via Project → Export. Do NOT use One-Click Deploy.
2. Set TEST_MODE = false in UnityAds.gd and use your real Game ID.
Export Errors and Fixes
| ERROR / SYMPTOM | CAUSE & FIX |
|---|---|
| Unsupported class file major version / Could not determine java version | Wrong JDK. Install JDK 17 and set Java SDK Path in Editor Settings → Export → Android. |
| minSdkVersion 21 cannot be smaller than version 24 declared in library | Min SDK too low. In the Android export preset, set Min SDK to 24 or higher. |
| Could not resolve com.unity3d.ads:unity-ads:4.12.3 | No access to Maven Central. Check internet, VPN, proxy or firewall. Gradle needs network access on the first build. |
| Android build template version mismatch | Template out of date. Run Project → Install Android Build Template again after upgrading Godot. |
| Invalid Android SDK path / missing build-tools or platform | SDK components missing. Install Platform 35 and Build-Tools 35.0.1 in the SDK Manager, then re-check the Android SDK Path. |
| Keystore / signing error | Wrong keystore path, alias or password. Re-check the Release (or Debug) fields in the export preset. Alias is case-sensitive. |
| Manifest merger failed | Conflicting manifest entries. Read the Gradle log for the exact line. The plugin adds the Unity Ads activities and permissions itself — remove any copies you added by hand to android/build/AndroidManifest.xml. |
Using the Ads
3 Ad Types Available
Banner
320×50 strip. Top or bottom. Displays automatically after load_banner() succeeds.
Interstitial
Full-screen. Auto-reloads after closing or failed show.
Rewarded
Video with reward. Fires on_rewarded_earned on completion.
Call Order — initialize → load → show
on_initialization_complete before loading ads. And always wait for on_*_loaded before showing. The wrapper has built-in guards — calling show_interstitial() before it's ready just prints a warning and does nothing.extends Node # Load these from YOUR consent screen / saved settings. Never hardcode true. var has_gdpr_consent := false var has_privacy_consent := false func _ready() -> void: # 1. Connect ALL signals first, before calling initialize() UnityAds.on_initialization_complete.connect(_on_ads_ready) UnityAds.on_initialization_failed.connect(_on_ads_failed) UnityAds.on_interstitial_loaded.connect(_on_interstitial_loaded) UnityAds.on_interstitial_completed.connect(_on_interstitial_completed) UnityAds.on_interstitial_failed_to_load.connect(_on_interstitial_failed) UnityAds.on_interstitial_failed_to_show.connect(_on_interstitial_failed_to_show) UnityAds.on_rewarded_loaded.connect(_on_rewarded_loaded) UnityAds.on_rewarded_earned.connect(_on_reward_earned) UnityAds.on_rewarded_failed_to_load.connect(_on_rewarded_failed) UnityAds.on_rewarded_failed_to_show.connect(_on_rewarded_failed_to_show) UnityAds.on_banner_loaded.connect(_on_banner_loaded) UnityAds.on_banner_failed_to_load.connect(_on_banner_failed) UnityAds.on_banner_clicked.connect(_on_banner_clicked) # 2. Pass the player's real consent choice (call before initialize) UnityAds.set_consent(has_gdpr_consent, has_privacy_consent) # 3. Initialize ONCE per app launch — uses GAME_ID + TEST_MODE from UnityAds.gd if not UnityAds.is_initialized(): UnityAds.initialize() else: _on_ads_ready() func _on_ads_ready() -> void: print("Unity Ads ready — loading all ad types") # 4. Load ads AFTER init completes — not before UnityAds.load_interstitial() UnityAds.load_rewarded() UnityAds.load_banner("bottom") # "top" or "bottom" # Banner displays automatically once on_banner_loaded fires func _on_ads_failed(error: String, message: String) -> void: print("Unity Ads init failed: ", error, " — ", message) # ── Banner ────────────────────────────────────────────────────── func _on_banner_loaded(placement_id: String) -> void: print("Banner visible: ", placement_id) # No extra call needed — banner is already showing func _on_banner_failed(placement_id: String, error: String) -> void: print("Banner failed: ", error) func _on_banner_clicked(placement_id: String) -> void: print("Banner clicked: ", placement_id) func toggle_banner(show: bool) -> void: if show: UnityAds.load_banner("bottom") # loads and shows automatically else: UnityAds.hide_banner() # ── Interstitial ──────────────────────────────────────────────── func _on_interstitial_loaded(placement_id: String) -> void: print("Interstitial ready: ", placement_id) func _on_interstitial_failed(placement_id: String, error: String, message: String) -> void: print("Interstitial load failed: ", error) func on_level_complete() -> void: if UnityAds.is_interstitial_ready(): UnityAds.show_interstitial() # Do NOT change scene here — wait for completed OR failed_to_show else: change_scene() # Ad not ready — proceed without it func _on_interstitial_completed(placement_id: String) -> void: # Ad closed by user — now safe to change scene # UnityAds.gd auto-reloads interstitial here change_scene() func _on_interstitial_failed_to_show(placement_id: String, error: String, message: String) -> void: # The ad never appeared, so on_interstitial_completed will NOT fire. # Continue anyway or the player is stuck on this screen. print("Interstitial failed to show: ", error) change_scene() # ── Rewarded ──────────────────────────────────────────────────── func _on_rewarded_loaded(placement_id: String) -> void: print("Rewarded ready: ", placement_id) func _on_rewarded_failed(placement_id: String, error: String, message: String) -> void: print("Rewarded load failed: ", error) func offer_revive() -> void: if UnityAds.is_rewarded_ready(): UnityAds.show_rewarded() # Reward is given in _on_reward_earned, NOT here else: print("Rewarded not ready yet — requesting a new load") UnityAds.load_rewarded() # safe fallback, see note below func _on_rewarded_failed_to_show(placement_id: String, error: String, message: String) -> void: print("Rewarded failed to show: ", error) # Tell the player the ad isn't available — do NOT give the reward func _on_reward_earned(placement_id: String) -> void: # Only fires when user COMPLETES the video — safe to give reward # UnityAds.gd auto-reloads rewarded here give_player_coins(100)
✓ UnityAds.on_rewarded_earned.connect(_on_reward_earned)✗ UnityAds.connect("on_rewarded_earned", _on_reward_earned)
Notes on the Example
initialize() again in each scene re-runs the SDK start-up and stacks up signal connections. The is_initialized() check in the example guards against this.UnityAds.gd reloads the rewarded ad after on_rewarded_earned and after a failed show. If a player skips or closes the video early, neither signal fires, so nothing triggers a new load and is_rewarded_ready() stays false. Call load_rewarded() whenever your "watch ad" button is pressed while the ad is not ready (as offer_revive() does above), and verify this behaviour on a real device.set_consent(gdpr_consent, privacy_consent) takes two booleans: the player's GDPR consent and their privacy-law consent. Pass the real answer from your own consent screen. Do not hardcode true. If your game is aimed at children, check Unity's child-directed / COPPA requirements and the Play Console families policy before you ship ads.Other Functions Available
| FUNCTION | RETURNS | WHAT IT DOES |
|---|---|---|
initialize() | — | Starts the SDK with GAME_ID and TEST_MODE |
is_initialized() | bool | True once the SDK has started (false on non-Android) |
set_consent(gdpr, privacy) | — | Send the player's consent choice. Call before initialize() |
load_interstitial() / show_interstitial() | — | Load, then show. Show does nothing unless the ad is ready |
is_interstitial_ready() | bool | True after on_interstitial_loaded, false after show |
load_rewarded() / show_rewarded() | — | Same pattern as interstitial |
is_rewarded_ready() | bool | True after on_rewarded_loaded, false after show |
load_banner(position) | — | "top" or "bottom". Loads and shows automatically |
set_banner_position(position) | — | Move the banner without reloading it |
hide_banner() | — | Removes the banner from the screen |
is_banner_ready() | bool | True after on_banner_loaded, false after hide |
Switching to Production
Before your release build, check these two constants in UnityAds.gd before your release build:
# DEVELOPMENT const GAME_ID = "YOUR_GAME_ID_HERE" ← your real Game ID from Unity Dashboard const TEST_MODE = true ← test ads only # PRODUCTION (same Game ID, only the flag changes) const GAME_ID = "YOUR_GAME_ID_HERE" const TEST_MODE = false ← must be false in the release build
TEST_MODE = true. Test mode serves test ads that generate no revenue. Also never click your own live ads while testing: switch TEST_MODE back to true for development builds.Signals Reference
All Available Signals
Connect to these from any script using Godot 4 dot syntax: UnityAds.signal_name.connect(your_func)
| SIGNAL | ARGS | WHEN IT FIRES |
|---|---|---|
on_initialization_complete | — | SDK ready — safe to load ads |
on_initialization_failed | error, message | SDK failed to initialize |
on_interstitial_loaded | placement_id | Interstitial ready to show |
on_interstitial_shown | placement_id | Interstitial appeared on screen |
on_interstitial_completed | placement_id | User closed interstitial ← change scene here |
on_interstitial_failed_to_load | placement_id, error, msg | Auto-retries after 5 seconds |
on_interstitial_failed_to_show | placement_id, error, msg | Show failed — reload and use fallback navigation |
on_interstitial_clicked | placement_id | User tapped the interstitial ad |
on_rewarded_loaded | placement_id | Rewarded ad ready to show |
on_rewarded_earned | placement_id | User completed the video ← give reward here |
on_rewarded_shown | placement_id | Rewarded video started |
on_rewarded_failed_to_load | placement_id, error, msg | Auto-retries after 5 seconds |
on_rewarded_failed_to_show | placement_id, error, msg | Show failed — handle gracefully |
on_rewarded_clicked | placement_id | User tapped the rewarded ad |
on_banner_loaded | placement_id | Banner visible on screen — no extra call needed |
on_banner_failed_to_load | placement_id, error | Banner failed — check placement ID in dashboard |
on_banner_clicked | placement_id | User tapped the banner ad |
await retry lines in UnityAds.gd if you want.Debugging & Common Issues
Step-by-Step Diagnostic — Ads Not Showing
| STEP | WHAT TO CHECK |
|---|---|
|
ST 1
Correct method
|
Use the singleton correctly. Call UnityAds.show_interstitial() not a local variable. Check UnityAds.is_interstitial_ready() returns true before showing. If it returns false, the ad hasn't loaded yet — wait for on_interstitial_loaded signal.
|
|
ST 2
Unity dashboard stats
|
Unity Ads takes time to serve real ads. Open Unity Dashboard → Monetization → Reporting. Check if ad requests are arriving. Zero requests means the SDK isn't initializing properly. Low fill rate is normal in the first days. |
|
ST 3
Play Store listing
|
Add your Play Store ID. It is not strictly required, and test ads (TEST_MODE = true) work without it. But in practice it highly affects fill rate, and without it you will rarely see real ads. Publish the app on the Play Store (at least internal testing) and add its Store ID in Unity Dashboard → Project Settings. Unity's docs note that some advertising partners require it. If the app was just published, Unity may not find it for 5 to 7 days; try again then.
|
|
ST 4
TEST_MODE check
|
Confirm TEST_MODE matches your build type. TEST_MODE = true shows dummy ads (good for development). TEST_MODE = false required for real revenue in production APK.
|
Common Error Reference
| SYMPTOM | CAUSE & FIX |
|---|---|
| UnityAds singleton not found | Plugin not enabled. Go to Project Settings → Plugins → enable UnityAdsPlugin. Confirm folder name is exactly unity_ads_plugin. |
| Initialization fails immediately | Wrong or empty Game ID. Open UnityAds.gd and verify GAME_ID matches your Unity Dashboard. Never leave it as the default test value in production. |
| Banner never appears | Banner placement not created in dashboard. Go to Unity Dashboard → Monetization → Ad Units → Add Ad Unit. Create a Banner type with name exactly Banner_Android. |
| Ads work in test, not production | TEST_MODE still true, or no Store ID (most common). Set TEST_MODE = false and make sure the app is published with its Play Store ID added in the Unity dashboard, since without it real ads rarely fill. Export with your release keystore so the app installs normally. Also check the Game ID and placement names match the dashboard exactly, that Reporting shows requests, and that your consent values are passed correctly. A new app can take days to get consistent fill. |
| Gradle build fails | Gradle Build not enabled in export. Check "Use Gradle Build" in your Android export preset. Also confirm INTERNET and ACCESS_NETWORK_STATE permissions are enabled. Make sure you are building with JDK 17 and Min SDK 24 or higher — see the Export Guide error table. |
| App crashes on launch (Android) | Build templates not installed. Run Project → Install Android Build Template. Without it, the AAR cannot be bundled. |
| show_interstitial() does nothing | Called before loading or wrong signal syntax. Always call initialize() → wait for on_initialization_complete → load_interstitial() → wait for on_interstitial_loaded → then show. Also confirm you're using Godot 4 dot syntax for signals: UnityAds.on_interstitial_loaded.connect(func) |
| Player stuck after an interstitial | You changed scene only in on_interstitial_completed. If the show fails, that signal never fires. Connect on_interstitial_failed_to_show and continue there too. |
| Rewarded button works once, then never again | No new load after a skipped video. Call load_rewarded() when the ad is not ready (see the notes in Step 5). |
| Every signal fires twice | UnityAds.gd was also added to a scene as a Node. Remove it from the scene. It must exist only as the autoload. |
| Signals never fire | Using old Godot 3 connect syntax. Replace UnityAds.connect("signal_name", func) with UnityAds.signal_name.connect(func) throughout your scripts. |
Logcat — Reading Android Logs
# Connect device via USB, then: adb logcat | grep -i "UnityAds" adb logcat | grep -i "unity3d" adb logcat | grep -i "Godot" # Key log messages to look for: "[UnityAds] Plugin found" ← plugin loaded ✓ "[UnityAds] Initialized successfully" ← ready to load ads ✓ "[UnityAds] Plugin NOT found" ← plugin missing ✗ "[UnityAds] Init failed" ← wrong Game ID ✗
Unity Ads vs AdMob — Which to Use?
🎮 Unity Ads — Best For
- Games with young / gaming audience
- Rewarded video heavy monetization
- Simpler setup (no manifest editing)
- Strong fill rate for game genres
📊 AdMob — Best For
- Maximum ad variety (5 ad types)
- Mediation across all networks
- Higher CPM for general apps
- Better analytics via Firebase
Mistakes to Avoid
The 19 Mistakes That Break Most Setups
Almost every "my ads don't work" report comes from one of these. Skim the list before you export, and again before you publish.
Adding UnityAds.gd to a scene as well as the autoload
A second copy connects to the native plugin again, so every signal fires twice (double rewards, double scene changes).
Do this instead: Use only the UnityAds autoload that the plugin registers.
Exporting without Gradle Build or the Android build template
The .aar cannot be bundled, so the app crashes on launch or the singleton is never found.
Do this instead: Install the build template, turn on Use Gradle Build in the Android preset, and reinstall the template after every Godot upgrade.
Using the wrong JDK, SDK or Min SDK
JDK 21+ with Godot 4.4 gives Gradle errors, and a Min SDK below 24 breaks the manifest merge.
Do this instead: Use JDK 17 for Godot 4.4, set Min SDK to 24 or higher, and check the Godot docs for the versions your editor needs.
Hand-editing AndroidManifest.xml to add Unity activities or permissions
The export plugin already injects them, so your copy causes a Manifest merger failed error.
Do this instead: Remove manual copies and let the plugin do it.
Releasing with TEST_MODE = true
You get test ads and no revenue.
Do this instead: Set TEST_MODE = false in UnityAds.gd before your release export, and set it back to true for development.
Clicking your own live ads
Self-clicks look like invalid traffic and can get your Unity account flagged.
Do this instead: Test with TEST_MODE = true. Never tap live ads on your own device.
Loading before init finishes, or showing before the ad is loaded
Loads fail and show_*() silently does nothing.
Do this instead: Wait for on_initialization_complete before load_*(), and check is_*_ready() before show_*().
Calling initialize() in every scene
It re-runs SDK start-up and stacks signal connections each time the scene loads.
Do this instead: Initialize once from a boot scene, guarded by is_initialized().
Changing scene only in on_interstitial_completed
If the ad fails to show, that signal never fires and the player is stuck.
Do this instead: Also connect on_interstitial_failed_to_show and continue from there.
Giving the reward when you call show_rewarded()
Players get the reward without watching, and failed shows still pay out.
Do this instead: Give rewards only in on_rewarded_earned.
Trusting auto-reload for rewarded ads
A skipped video can leave the rewarded ad unloaded, so the button stops working.
Do this instead: Call load_rewarded() when you need the ad and is_rewarded_ready() is false.
Forgetting to create the Banner_Android placement
Banners never load. Interstitial and Rewarded are created for you, Banner is not.
Do this instead: Create it under Monetization → Ad Units, named exactly Banner_Android (case-sensitive).
Hardcoding set_consent(true, true)
You tell Unity the player consented when they may not have, which is a privacy-law problem.
Do this instead: Pass the player's real choice from a consent screen, and check child-directed rules if your game targets kids.
Using Godot 3 signal syntax
UnityAds.connect("on_x", fn) is the old style, so your handlers never run.
Do this instead: Use UnityAds.on_x.connect(fn).
Testing in the editor or on desktop
There is no native plugin there, so nothing loads and the log says Plugin NOT found.
Do this instead: Export to a real Android device and read adb logcat.
Renaming the addon folder
The AAR path and autoload path are hardcoded to unity_ads_plugin.
Do this instead: Keep the folder at res://addons/unity_ads_plugin/.
Showing interstitials at the wrong moments
Ads at app launch or mid-gameplay hurt retention and reviews.
Do this instead: Show them at natural breaks such as level complete or game over, and keep rewarded ads optional.
Losing your release keystore
You cannot publish updates to the same Play Store app.
Do this instead: Back it up with its alias and passwords in more than one safe place.
Skipping the Play Store ID, or shipping with a debug keystore
The Store ID is optional, but without it you will rarely see real ads because fill drops sharply. A debug keystore doesn't block ads, but debug-signed builds cause installation problems as a normal app, which is why a release keystore is required.
Do this instead: Sign with your release keystore, publish the app on the Play Store, and add its Store ID under Unity Dashboard → Project Settings (retry after 5 to 7 days if Unity can't find a new app).