📖 SETUP GUIDE

Unity Ads Plugin for
Godot 4.4 — Full Setup

Banner, Interstitial & Rewarded Ads for Android with auto-retry, signals, and zero manifest editing required. Step-by-step guide based on the actual plugin code.

Start Setup →
3AD TYPES
AutoMANIFEST
4.12SDK VERSION
17JDK VERSION
4.4+GODOT VERSION
1

Installation

Folder Structure After Install

After purchasing, download the zip, extract it, and copy the addons/ folder into your Godot project root.

res:// ├── addons/ │ └── unity_ads_plugin/ │ ├── UnityAds.gd ← wrapper (autoloaded as UnityAds) │ ├── unity_ads_plugin.gd ← export plugin │ ├── plugin.cfg ← plugin manifest │ ├── *.gd.uid ← Godot 4.4+ ID files — keep them │ └── plugin/ │ └── unityadsplugin-release.aar ├── android/ ├── scenes/ └── project.godot
ℹ️
The folder name must stay 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.

🚨
Do not also drag 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.
ℹ️
Android only. The native plugin exists only in Android builds. In the editor or on desktop, UnityAds still exists but every call just prints "Plugin NOT found" and does nothing. Test ads on a real Android device.

Enable the Plugin

  1. Open your project in Godot 4.4
  2. Go to Project → Project Settings → Plugins
  3. Find UnityAdsPlugin in the list and toggle it ON
  4. Godot automatically adds UnityAds as a global autoload singleton
🖼️

Screenshot: Project Settings → Plugins → UnityAdsPlugin enabled

✅
Big difference from AdMob: This plugin automatically injects all required Android permissions and Unity Ads Activity declarations into your manifest at build time. No manual manifest editing needed.
2

Unity Dashboard Setup

Get Your Game ID

  1. Go to cloud.unity.com and sign in
  2. Select your project (or create a new one)
  3. Go to Monetization → Ad Units in the left menu
  4. Your Game ID is shown at the top of this page — copy it
  5. Open UnityAds.gd and replace the GAME_ID constant
addons/unity_ads_plugin/UnityAds.gd — constants at the top of the file
# 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 TypeDefault Placement IDCreated By
Interstitial Interstitial_Android AUTO
Rewarded Rewarded_Android AUTO
Banner Banner_Android MANUAL
⚠️
Banner requires manual creation. Go to Monetization → Ad Units → Add Ad Unit. Set the name to 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

ℹ️
These placement IDs are already set as constants in 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).
3

Install Android Build Templates

  1. Go to Project → Install Android Build Template…
  2. Click Install and wait for Godot to finish
  3. The android/build/ folder will now exist in your project
  4. Requires JDK 17 and the Android SDK — see Step 4: Export Guide
✅
Unlike AdMob, you do NOT need to edit AndroidManifest.xml. The Unity Ads export plugin automatically injects all 5 required Activity declarations and permissions at build time via Godot's plugin API.
🖼️

Screenshot: Project → Install Android Build Template menu

4

Export Guide

Requirements Checklist

ItemRequiredWhy
Godot4.4 (4.2+ works)Plugin uses the Godot v2 Android plugin format
JDKJDK 17Godot 4.4 Gradle build and the compiled AAR both target Java 17. JDK 21+ can cause Gradle errors
Android SDKPlatform 35, Build-Tools 35.0.1, Platform-Tools, Cmdline-ToolsGodot 4.4 export defaults
Min SDK24 or higherThe plugin AAR declares minSdkVersion 24. Lower values break the manifest merge
Unity Ads SDK4.12.3Downloaded from Maven Central automatically on first build
InternetOn first buildGradle downloads the Unity Ads SDK and its dependencies
Build templateInstalled (Step 3)Must match your editor version — reinstall after upgrading Godot
⚠️
Versions above are for Godot 4.4. The JDK and Android SDK / Build-Tools versions are the defaults for that release. On a newer Godot (4.5, 4.6, 4.7…) the required JDK and SDK versions can change, so check the Android export page in the official Godot docs for your version, and do a clean Gradle build after changing editors.

A. Install JDK 17 and the Android SDK

  1. Install JDK 17 (Temurin or OpenJDK 17). Verify in a terminal with java -version — it should print 17.x
  2. Install the Android SDK, either through Android Studio → SDK Manager or the command-line tools
  3. In the SDK Manager, install Android SDK Platform 35, Build-Tools 35.0.1, Platform-Tools and Command-line Tools
  4. If Godot asks for extra SDK components (such as NDK or CMake) during setup, install the versions it names
Terminal — command-line install (optional)
# Run from your cmdline-tools/latest/bin folder
sdkmanager "platform-tools" "platforms;android-35" "build-tools;35.0.1" "cmdline-tools;latest"
sdkmanager --licenses
⚠️
Do not use JDK 21 or newer. Godot 4.4's Gradle setup expects JDK 17. If your system default is another version, that is fine — Godot uses the path you set in Editor Settings (next step), not the system default.

B. Point Godot at the JDK and SDK

  1. Open Editor → Editor Settings → Export → Android
  2. Set Java SDK Path to your JDK 17 folder (the folder that contains bin)
  3. Set Android SDK Path to your Android SDK folder
  4. 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.

Terminal — release keystore (keep this file safe)
keytool -genkey -v -keystore release.keystore -alias my_alias -keyalg RSA -keysize 2048 -validity 10000
Terminal — debug keystore (only if you don't have one)
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
🚨
Back up your release keystore and its passwords. If you lose them you cannot publish updates to the same Play Store app.

D. Android Export Preset

  1. Go to Project → Export → Add… → Android
  2. Turn on Use Gradle Build
  3. Set Min SDK to 24 or higher
  4. Under Architectures, enable arm64-v8a (add armeabi-v7a if you support older devices)
  5. Enable the INTERNET and ACCESS_NETWORK_STATE permissions
  6. Fill in the Release keystore, user and password
Project → Export → Android Preset
── 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

  1. In the Export dialog, uncheck "Export With Debug" for a release build
  2. Click Export Project… (not One-Click Deploy) and choose a file name
  3. Choose APK for direct install and testing, or AAB for Play Store upload (AAB needs Gradle Build, which you already enabled)
  4. Wait for Gradle. The first build is slow because it downloads Gradle, the Unity Ads SDK and other dependencies
  5. Install the APK on a real Android device and test with TEST_MODE = true first
🚨
Before you publish:

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 / SYMPTOMCAUSE & 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.
ℹ️
For any other build failure, copy the full Gradle output from Godot's output panel. The first "What went wrong" block usually names the exact problem.
5

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

🚨
Always wait for 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.
boot_scene.gd — complete example (Godot 4 syntax)
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)
⚠️
Godot 4 signal syntax changed from Godot 3. Always use the dot syntax:
✓ UnityAds.on_rewarded_earned.connect(_on_reward_earned)
✗ UnityAds.connect("on_rewarded_earned", _on_reward_earned)

Notes on the Example

⚠️
Initialize once, not in every scene. Put the code above in your first (boot) scene or in another autoload. Calling 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.
⚠️
Rewarded: don't rely on auto-reload alone. 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.
⚠️
Consent. 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.
ℹ️
Don't spam interstitials. Show them at natural breaks (level complete, game over), not at app launch or mid-gameplay. Rewarded ads should always be the player's choice.

Other Functions Available

FUNCTIONRETURNSWHAT IT DOES
initialize()—Starts the SDK with GAME_ID and TEST_MODE
is_initialized()boolTrue 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()boolTrue after on_interstitial_loaded, false after show
load_rewarded() / show_rewarded()—Same pattern as interstitial
is_rewarded_ready()boolTrue 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()boolTrue 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:

addons/unity_ads_plugin/UnityAds.gd
# 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
⚠️
Never release with 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.
6

Signals Reference

All Available Signals

Connect to these from any script using Godot 4 dot syntax: UnityAds.signal_name.connect(your_func)

SIGNALARGSWHEN IT FIRES
on_initialization_complete—SDK ready — safe to load ads
on_initialization_failederror, messageSDK failed to initialize
on_interstitial_loadedplacement_idInterstitial ready to show
on_interstitial_shownplacement_idInterstitial appeared on screen
on_interstitial_completedplacement_idUser closed interstitial ← change scene here
on_interstitial_failed_to_loadplacement_id, error, msgAuto-retries after 5 seconds
on_interstitial_failed_to_showplacement_id, error, msgShow failed — reload and use fallback navigation
on_interstitial_clickedplacement_idUser tapped the interstitial ad
on_rewarded_loadedplacement_idRewarded ad ready to show
on_rewarded_earnedplacement_idUser completed the video ← give reward here
on_rewarded_shownplacement_idRewarded video started
on_rewarded_failed_to_loadplacement_id, error, msgAuto-retries after 5 seconds
on_rewarded_failed_to_showplacement_id, error, msgShow failed — handle gracefully
on_rewarded_clickedplacement_idUser tapped the rewarded ad
on_banner_loadedplacement_idBanner visible on screen — no extra call needed
on_banner_failed_to_loadplacement_id, errorBanner failed — check placement ID in dashboard
on_banner_clickedplacement_idUser tapped the banner ad
ℹ️
Auto-retry is built in. If interstitial or rewarded fails to load, the plugin automatically retries after 5 seconds — you don't need to write any retry logic yourself. Note that the retry has no limit: with no fill it keeps trying every 5 seconds, so on a very new app you will see repeated failed-to-load messages in the log. That is normal, but you can cap it by editing the await retry lines in UnityAds.gd if you want.
7

Debugging & Common Issues

⚠️
Before debugging: Confirm you exported a Release build signed with your Release Keystore (via Project → Export, not one-click deploy) and installed it on a real Android device. Ads never run in the editor or on desktop. A debug keystore does not block ads, but debug-signed builds often cause installation problems as a normal app, so use a release keystore for anything beyond quick tests.

Step-by-Step Diagnostic — Ads Not Showing

STEPWHAT 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

SYMPTOMCAUSE & 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

Terminal — filter Unity Ads 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
💡
Pro tip: Use both plugins together. Add Unity Ads as a mediation source inside AdMob dashboard for maximum fill rate and revenue. Both plugins can run in the same Godot project simultaneously.
!

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.

1

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.

2

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.

3

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.

4

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.

5

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.

6

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.

7

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_*().

8

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().

9

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.

10

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.

11

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.

12

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).

13

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.

14

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).

15

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.

16

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/.

17

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.

18

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.

19

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).

Get the Unity Ads Plugin

Includes UnityAds.gd, unity_ads_plugin.gd, the compiled AAR and all 3 ad types with auto-retry built in.

$5.00 Buy on itch.io →

One-time purchase · Instant download · Free updates