Ragendom Ad Mediation

A lightweight, modular AdMob ad mediation system for Unity.

Overview

Ragendom Ad Mediation provides a clean, production-ready abstraction layer for Google AdMob advertisements in Unity. It supports Banner, Interstitial, Rewarded Video, and App Open Ad formats, with built-in UMP/GDPR consent handling, iOS IDFA tracking, a no-ads purchase system, interstitial timing controls, and a fully functional Dummy provider for editor testing — all without requiring any external SDK to compile.

Key Features

• Zero dependencies at compile time — the project compiles and runs with the built-in Dummy provider. The Google Mobile Ads SDK is only required when building for a real device.
• Automatic SDK detection — when you import the Google Mobile Ads Unity Plugin, the MODULE_ADMOB scripting define is added automatically. No manual setup required.
• All ad formats — Banner, Interstitial, Rewarded Video, and App Open Ads.
• UMP/GDPR consent flow — built-in Google User Messaging Platform support with configurable debug geography.
• iOS IDFA tracking — App Tracking Transparency (ATT) dialog support.
• No-ads purchase support — a single method call disables banners and interstitials while keeping rewarded videos available.
• Interstitial timing system — configurable first-launch delay, per-session delay, and minimum cooldown between ads.
• Thread-safe callbacks — all ad SDK callbacks are marshalled to the Unity main thread automatically.
• Exponential retry — failed ad loads are retried with exponential backoff (up to 5 attempts).
• Assembly Definitions — proper .asmdef structure for fast compilation and Asset Store compliance.

Requirements

Project Structure

Quick Start (5 Minutes)

Get up and running with Dummy ads in the Unity Editor in 5 minutes.

Testing

Testing with Dummy Ads (Editor)

The Dummy provider lets you test the entire ad lifecycle without any external SDK. It works in the Unity Editor on any platform.

1. In your MonetizationSettings asset, set all three provider slots (Banner, Interstitial, Rewarded Video) to Dummy.
2. Press Play in the Unity Editor.
3. The console should show:

   [UMP]: AdMob module not available, skipping UMP.
   [Monetization]: Loading task 'UMP Consent' completed with status: Skipped
   [AdsManager]: Dummy ad provider initialized.
   [AdsManager]: Dummy provider initialized successfully.
   [AdsManager]: First ads loaded.
   [AdsManager]: Module initialized.
   [AdsManager]: Provider initialized: Dummy

4. Call AdsManager.ShowBanner() to see a simulated banner overlay at the bottom (or top) of the screen.
5. Call AdsManager.RequestInterstitial() followed by AdsManager.ShowInterstitial(callback) to see a fullscreen simulated interstitial with a Close button.
6. Call AdsManager.RequestRewardBasedVideo() followed by AdsManager.ShowRewardBasedVideo(callback) to see a simulated rewarded video with "Watch" and "Close" buttons.

Testing with Real AdMob Ads (On Device)

Follow these steps to test with actual Google AdMob test ads on a physical Android or iOS device.

Testing Checklist

Integration Guide

Setting Up in Your Project

Banner Ads

using Ragendom;

// Show a banner ad
AdsManager.ShowBanner();

// Hide the banner (keeps it in memory for fast re-show)
AdsManager.HideBanner();

// Fully destroy the banner (frees memory, will reload on next ShowBanner)
AdsManager.DestroyBanner();

Interstitial Ads

using Ragendom;

// Pre-load an interstitial (called automatically on init if loadAdsOnStart is true)
AdsManager.RequestInterstitial();

// Check if an interstitial is ready
bool ready = AdsManager.IsInterstitialLoaded();

// Show an interstitial with a result callback
AdsManager.ShowInterstitial((bool success) =>
{
    if (success)
    {
        // Ad was shown and closed
        Debug.Log("Interstitial completed");
    }
    else
    {
        // Ad could not be shown (not loaded, on cooldown, no-ads purchased, etc.)
        Debug.Log("Interstitial not shown");
    }
});

// Show interstitial ignoring cooldown timer and custom conditions
AdsManager.ShowInterstitial(callback, ignoreConditions: true);

Interstitials are automatically re-requested after being shown. The system enforces:

• First launch delay (interstitialFirstStartDelay) — seconds before the first interstitial on first-ever app launch
• Session delay (interstitialStartDelay) — seconds before the first interstitial on subsequent launches
• Cooldown (interstitialShowingDelay) — minimum seconds between consecutive interstitials

Rewarded Video Ads

using Ragendom;

// Pre-load a rewarded video
AdsManager.RequestRewardBasedVideo();

// Check if a rewarded video is ready
bool ready = AdsManager.IsRewardBasedVideoLoaded();

// Show a rewarded video
AdsManager.ShowRewardBasedVideo((bool rewarded) =>
{
    if (rewarded)
    {
        // User watched the full video - grant the reward!
        GiveCoins(100);
    }
    else
    {
        // User closed early or ad failed to show
        ShowMessage("Watch the full video to earn your reward.");
    }
});

Using the AdsRewardsHolder Component

For simple cases, you can use the pre-built AdsRewardsHolder component instead of writing code:

1. Add AdsRewardsHolder to any GameObject.
2. Assign a UI Button to the rewardButton field.
3. Create a subclass overriding ApplyReward() with your reward logic:

public class CoinRewardHolder : AdsRewardsHolder
{
    protected override void ApplyReward()
    {
        // This is called only when the user earns the reward
        PlayerData.AddCoins(100);
    }
}

No-Ads / Remove Ads Purchase

// Call this when the user successfully purchases "Remove Ads" via IAP
AdsManager.DisableForcedAd();

// Check if the user has already purchased no-ads
bool hasPurchased = !AdsManager.IsForcedAdEnabled();

// Listen for the no-ads event
AdsManager.ForcedAdDisabled += () =>
{
    // Hide the "Remove Ads" button
    removeAdsButton.SetActive(false);
};

When DisableForcedAd() is called:

• The state is saved to PlayerPrefs (persists across sessions)
• Banners are immediately destroyed
• Interstitials will no longer show
• Rewarded videos remain available
• The ForcedAdDisabled event fires

Using the NoAdsReward Component

The pre-built NoAdsReward component simplifies the UI:

1. Add NoAdsReward to any GameObject.
2. Assign your "Remove Ads" UI panel/button to the noAdsOfferObject field.
3. Call noAdsReward.ApplyReward() from your IAP purchase success callback.
4. The component automatically hides the offer UI when ads are disabled.

Custom Interstitial Conditions

You can add custom conditions that must be met before an interstitial will show:

// Add a condition: don't show interstitials during gameplay
AdsManager.InterstitialConditions += () => !GameManager.IsInGameplay;

// Add another condition: require at least 3 levels completed
AdsManager.InterstitialConditions += () => PlayerData.LevelsCompleted >= 3;

// All conditions must return true for the interstitial to show.
// Any single condition returning false blocks the ad.
// These conditions are skipped when ignoreConditions: true is passed.

Settings Reference

MonetizationSettings

The root settings asset. Created via Create > Data > Core > Monetization Settings.

AdsSettings

Embedded sub-asset inside MonetizationSettings. Contains all ad-specific configuration.

Provider Selection

Interstitial Timing

UMP / GDPR Consent

IDFA / iOS Tracking

AdMob Configuration

These fields appear in the Inspector when you select the MonetizationSettings asset and have at least one provider set to AdMob.

App IDs

Ad Unit IDs

Banner Settings

App Open Ad Settings

API Reference

AdsManager (Static Class)

All ad operations go through this single static class. Add using Ragendom; to your script.

Initialization

Banner

Interstitial

Rewarded Video

No-Ads / Forced Ad Control

Events

Subscribe to these events to react to ad lifecycle changes:

// Fired when a provider finishes async initialization
AdsManager.AdProviderInitialized += (AdProvider provider) =>
{
    Debug.Log($"Provider ready: {provider}");
};

// Fired when any ad finishes loading
AdsManager.AdLoaded += (AdProvider provider, AdType adType) =>
{
    Debug.Log($"{adType} loaded from {provider}");
};

// Fired when any ad is displayed on screen
AdsManager.AdDisplayed += (AdProvider provider, AdType adType) =>
{
    // Pause game audio, timers, etc.
};

// Fired when any ad is closed/dismissed
AdsManager.AdClosed += (AdProvider provider, AdType adType) =>
{
    // Resume game audio, timers, etc.
};

// Fired when no-ads is purchased
AdsManager.ForcedAdDisabled += () =>
{
    // Update UI: hide "Remove Ads" button
};

UMP / GDPR Consent

These methods wrap the Google User Messaging Platform (UMP) SDK for GDPR compliance. They only function when the AdMob SDK is present (MODULE_ADMOB defined). Without the SDK, they return safe defaults.

IDFA Tracking (iOS)

These methods are only available when both conditions are met: the build target is iOS (UNITY_IOS) and the Unity iOS Support package is installed (MODULE_IDFA).

Advanced Topics

Automatic SDK Detection (Define System)

The system uses a custom [Define] attribute and an editor-time DefineManager to automatically detect installed SDKs and add the corresponding scripting define symbols.

The AdsManager class is decorated with:

[Define("MODULE_ADMOB", "GoogleMobileAds.Api.MobileAds")]

On every Unity domain reload (script compile, entering Play mode, etc.), the DefineManager:

1. Scans all loaded assemblies for classes with [Define] attributes.
2. For each attribute, checks if the target type (e.g. GoogleMobileAds.Api.MobileAds) exists in any assembly.
3. If found: adds the define symbol (MODULE_ADMOB) to Player Settings.
4. If not found: removes the define symbol.

This means:

• Importing the Google Mobile Ads Unity Plugin automatically enables MODULE_ADMOB.
• Removing the plugin automatically disables MODULE_ADMOB.
• You can view and manually toggle defines via Window > Ragendom Core > Define Manager.

Thread Safety

Ad SDKs (especially AdMob) fire their callbacks on background threads, but Unity APIs can only be called from the main thread. The system handles this transparently:

• All ad callbacks in AdMobHandler use AdsManager.CallEventInMainThread() to enqueue actions.
• The internal AdEventExecutor MonoBehaviour flushes this queue every Update().
• Your callbacks (e.g. ShowInterstitial(callback)) are always called on the main thread — you can safely call Unity APIs from them.

Retry & Exponential Backoff

When an ad fails to load (network error, no fill, etc.), the system retries automatically:

App Open Ads

App Open Ads are fullscreen ads shown when the user returns to your app from the background. To enable:

1. In your MonetizationSettings → AdMob settings, check Use App Open Ad.
2. Set the Android and iOS App Open Ad unit IDs (or keep the defaults for testing).
3. Set the Expiration Hours (default: 4). A loaded ad older than this will not be shown.

Behavior:

• An App Open Ad is loaded at initialization and re-loaded after each display.
• When the app returns to the foreground, if an ad is loaded and not expired, it displays automatically.
• The banner is automatically hidden while the App Open Ad is visible and restored when it closes.
• App Open Ads are suppressed while an interstitial or rewarded video is being shown.

Creating a Custom Ad Provider

To add support for a different ad network, create a new class extending AdProviderHandler:

public class MyCustomHandler : AdProviderHandler
{
    public MyCustomHandler()
    {
        providerType = AdProvider.AdMob; // or add a new enum value
    }

    protected override async Task<bool> InitProviderAsync()
    {
        // Initialize your SDK here
        return true;
    }

    public override void ShowBanner() { /* ... */ }
    public override void HideBanner() { /* ... */ }
    public override void DestroyBanner() { /* ... */ }

    public override void RequestInterstitial() { /* ... */ }
    public override void ShowInterstitial(AdvertisementCallback callback) { /* ... */ }
    public override bool IsInterstitialLoaded() { /* ... */ }

    public override void RequestRewardedVideo() { /* ... */ }
    public override void ShowRewardedVideo(AdvertisementCallback callback) { /* ... */ }
    public override bool IsRewardedVideoLoaded() { /* ... */ }
}

Use the protected helpers for callbacks:

• OnProviderAdLoaded(AdType) — call when an ad finishes loading
• OnProviderAdDisplayed(AdType) — call when an ad appears on screen
• OnProviderAdClosed(AdType) — call when an ad is dismissed
• HandleAdLoadFailure(adType, errorMessage, ref retryAttempt, retryAction) — call on load failure for automatic exponential retry
• AdsManager.CallEventInMainThread(callback) — use to marshal SDK callbacks to the main thread

Troubleshooting

Common Issues

Going to Production

Before publishing your app with real ads, complete this checklist:

Appendix

Enums Reference

AdProvider

AdType

BannerPosition

ConsentRequirementStatus

AuthorizationTrackingStatus (iOS only)

DebugGeography

PlayerPrefs Keys

Assembly Definitions

The asset uses Assembly Definitions (.asmdef) for proper compilation isolation. If your project uses asmdef files and you need to reference the ad system, add Ragendom.Monetization to your assembly's references.

Ragendom Ad Mediation — Built by Ragendom