📖 SETUP GUIDE

Unity Ads Plugin for
Godot 4.4 — Full Setup

Banner, Interstitial & Rewarded Ads 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
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/ │ └── unityadsplugin-release.aar ├── android/ ├── scenes/ └── project.godot
ℹ️
The folder name must stay unity_ads_plugin — the AAR path is hardcoded in the export plugin.

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 — line 2
# 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, banner ads will fail silently.
🖼️

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

🚨
Same rules as AdMob — both are critical:

1. Use a Release Keystore — debug keystore will not serve real ads.

2. Export as Release APK via Project → Export. Do NOT use One-Click Deploy.

Android Export Preset — Required Settings

Project → Export → Android Preset
── Gradle Build ──────────────────────────────
[✓] Use Gradle Build
[✓] Use Custom Build

── Permissions ───────────────────────────────
[✓] INTERNET
[✓] ACCESS_NETWORK_STATE

Note: AD_ID permission is auto-injected by plugin

── Keystore (REQUIRED for real ads) ──────────
Release Keystore:  path/to/your-release.keystore
Release User:      your_key_alias
Release Password:  your_password

── Export ────────────────────────────────────
Export Format:  APK
Build Mode:     Release
🖼️

Screenshot: Export dialog — Gradle Build enabled, permissions checked, Release keystore set

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.
your_scene.gd — complete example (Godot 4 syntax)
extends Node

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_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_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. Set GDPR consent if needed (call before initialize)
    UnityAds.set_consent(true, true)

    # 3. Now initialize — uses GAME_ID + TEST_MODE from UnityAds.gd
    UnityAds.initialize()

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

# ── 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")

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)

Switching to Production

Two changes needed in UnityAds.gd before your release build:

addons/unity_ads_plugin/UnityAds.gd
# DEVELOPMENT
const GAME_ID = "6020875"      ← replace with your real Game ID
const TEST_MODE = true         ← set to false for release

# PRODUCTION
const GAME_ID = "YOUR_REAL_ID" ← from Unity Dashboard
const TEST_MODE = false        ← must be false in release APK
⚠️
Never release with TEST_MODE = true. Test mode serves fake ads that don't generate revenue and will violate Unity Ads policies if left on in production.
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_completeSDK 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.
7

Debugging & Common Issues

⚠️
Before debugging: Confirm you exported a Release APK (not one-click deploy) with a Release Keystore, installed on a real Android device.

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
Your app must be published on the Play Store to serve real ads. Unity Ads verifies your app through the store. Publish to at least internal testing on Play Console to pass verification and enable full ad serving.
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 debug keystore used. Set TEST_MODE = false and re-export with your release keystore.
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.
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_completeload_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)
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.

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.

$4.00 Buy on itch.io →

One-time purchase · Instant download · Free updates