View as Markdown

Unity

The Ezoic Unity SDK lets you show Ezoic banner, rewarded, and interstitial ads in Unity games while relying on the native Android and iOS SDKs for ad loading, Prebid, Google Ad Manager, consent handling, pageview tracking, and remote configuration.

The Unity package is a C# bridge over the native SDKs. It does not reimplement the ad stack in C#, so your game code stays platform-agnostic and the same calls run as safe no-ops in the editor.

Requirements

  • Unity 2021.3 LTS or higher
  • Android SDK 24 or higher for Android apps
  • iOS 14.0 or higher for iOS apps
  • External Dependency Manager for Unity (EDM4U) recommended to resolve the native libraries
  • Google Mobile Ads application ID provided by Ezoic

Installation

In Unity, open Window → Package Manager → + → Add package from git URL… and enter the package git URL pinned to a released version:

https://github.com/ezoic/ezoic-unity-sdk.git#v1.0.1

Or add it to your project's Packages/manifest.json dependencies:

{
  "dependencies": {
    "com.ezoic.ads": "https://github.com/ezoic/ezoic-unity-sdk.git#v1.0.1"
  }
}

Platform Setup

Unity games still need the native platform setup required by Android and iOS. The package ships an Editor/EzoicDependencies.xml manifest so the External Dependency Manager for Unity (EDM4U) can resolve the native libraries automatically. Install EDM4U from the Unity Jar Resolver project.

Android

With EDM4U installed, the Android Resolver adds the native com.ezoic.sdk:ezoic-ads-sdk:1.5.0 library (from Maven Central) to your generated Gradle build — no manual dependency needed.

The native SDK serves through Google Ad Manager, which requires your application ID in the Android manifest. Enable Custom Main Manifest under Project Settings → Player → Android → Publishing Settings and add the meta-data entry inside the <application> tag of Assets/Plugins/Android/AndroidManifest.xml:

<manifest>
  <application>
    <meta-data
        android:name="com.google.android.gms.ads.APPLICATION_ID"
        android:value="ca-app-pub-XXXXXXXXXXXXXXXX~YYYYYYYYYY" />
  </application>
</manifest>

Replace the value with the Google Mobile Ads application ID provided for your account. A missing or incorrect app ID causes the app to crash on start. The application ID is usually provided by Ezoic and can be found in your Ezoic dashboard.

iOS

With EDM4U installed, the iOS Resolver adds pod 'EzoicAdsSDK', '~> 1.5.0' to the generated Xcode project's Podfile. After Unity builds the Xcode project, run pod install in the build output directory if EDM4U has not already done so. iOS requires a deployment target of 14.0 or higher, set under Project Settings → Player → iOS → Other Settings → Target minimum iOS Version.

Follow the Required App Setup for Ads to Serve in the iOS guide. These steps live in your app's Info.plist and directly affect fill, so complete all of them:

  • Adding the Google Mobile Ads application ID (GADApplicationIdentifier) and GADIsAdManagerApp to Info.plist
  • Adding NSUserTrackingUsageDescription to Info.plist (the SDK presents the App Tracking Transparency prompt for you before loading ads — biggest impact on fill)
  • Adding the SKAdNetworkItems identifiers to Info.plist (Apple does not read these from frameworks/SDKs)

app-ads.txt

For both platforms, host an app-ads.txt file at the root of the developer website listed on your app's store page (for example, https://example.com/app-ads.txt). It authorizes the buyers that may sell your inventory; a missing or incomplete file causes most programmatic demand to be filtered out. Ezoic provides the required entries — confirm the file is published and current.

Initialize the SDK

Initialize Ezoic once, early in your game's lifecycle, with your Ezoic-registered domain. Make the call from the Unity main thread (for example from a MonoBehaviour's Start). The optional callback reports (success, error).

using Ezoic.Ads;
using UnityEngine;

public class AdsBootstrap : MonoBehaviour
{
    void Start()
    {
        EzoicAds.Initialize("example.com", (success, error) =>
        {
            if (success)
            {
                Debug.Log("Ezoic Ads initialized. SDK version: " + EzoicAds.Version);
            }
            else
            {
                Debug.LogWarning("Ezoic Ads init failed: " + error);
            }
        });
    }
}

domain must match the domain configured for your site in Ezoic. The native Android and iOS SDKs both authenticate using the configured domain plus the app's bundle/package identifier — there is no client-side API key. EzoicAds.IsInitialized becomes true once initialization succeeds.

Add a Banner Ad

Construct an EzoicBannerAd with your ad unit id and a screen position, subscribe to its events, then call Load(). Show it once it loads.

using Ezoic.Ads;

// Adaptive banner anchored to the bottom of the screen.
var banner = new EzoicBannerAd(adUnitId: 12345, position: BannerPosition.Bottom);

banner.OnLoaded     += () => banner.Show();
banner.OnLoadFailed += error => Debug.LogWarning("Banner failed: " + error);
banner.OnClicked    += () => Debug.Log("Banner clicked");
banner.OnImpression += () => Debug.Log("Banner impression");

banner.Load();

// later: banner.Hide(); banner.Show();
// when done: banner.Destroy();

Replace 12345 with your Ezoic ad unit id. Use Show() / Hide() to toggle visibility without reloading, and always call Destroy() when you are done with a banner to release the native ad.

The banner constructor takes an optional size string. Pass null (the default) to request an adaptive banner sized by the native SDK, or a fixed size string such as "320x50":

// Fixed 320x50 banner at the top of the screen.
var banner = new EzoicBannerAd(adUnitId: 12345, position: BannerPosition.Top, size: "320x50");

Common fixed size strings include:

  • "320x50": standard banner
  • "320x100": large banner
  • "300x250": medium rectangle
  • "468x60": full banner
  • "728x90": leaderboard

BannerPosition supports Top, Bottom, TopLeft, TopRight, BottomLeft, BottomRight, and Center.

EzoicBannerAd raises these events, all delivered on the Unity main thread:

  • OnLoaded
  • OnLoadFailed(string error)
  • OnClicked
  • OnImpression

Add a Rewarded Ad

Rewarded ads are full-screen ads that grant an in-app reward when the user finishes watching. Load one imperatively ahead of time (for example, at the start of a level), subscribe to its events, then present it at a natural break. The static Load hands you a ready instance through its onLoaded callback.

using Ezoic.Ads;

EzoicRewardedAd.Load(
    adUnitId: 34567,
    onLoaded: ad =>
    {
        ad.OnUserEarnedReward += (type, amount) =>
            Debug.Log($"Reward earned: {amount} {type}");
        ad.OnShown        += () => Debug.Log("Rewarded shown");
        ad.OnDismissed    += () => Debug.Log("Rewarded dismissed");
        ad.OnFailedToShow += error => Debug.LogWarning("Show failed: " + error);
        ad.OnImpression   += () => Debug.Log("Rewarded impression");
        ad.OnClicked      += () => Debug.Log("Rewarded clicked");

        if (ad.IsLoaded)
        {
            ad.Show();
        }
        // when finished with it: ad.Destroy();
    },
    onFailed: error => Debug.LogWarning("Rewarded load failed: " + error));

Replace 34567 with your Ezoic ad unit id. The reward type and amount come from the reward configured on the Google Ad Manager rewarded ad unit. Load and Show() are separate steps; guard Show() behind IsLoaded. Load a new EzoicRewardedAd for each reward opportunity, and call Destroy() when you are done with an instance.

Add an Interstitial Ad

Interstitial ads are full-screen ads shown at natural transition points (for example, between levels or screens). They grant no reward. Like rewarded ads, load one ahead of time and present it at a break.

using Ezoic.Ads;

EzoicInterstitialAd.Load(
    adUnitId: 23456,
    onLoaded: ad =>
    {
        ad.OnShown        += () => Debug.Log("Interstitial shown");
        ad.OnDismissed    += () => Debug.Log("Interstitial dismissed");
        ad.OnFailedToShow += error => Debug.LogWarning("Show failed: " + error);
        ad.OnImpression   += () => Debug.Log("Interstitial impression");
        ad.OnClicked      += () => Debug.Log("Interstitial clicked");

        if (ad.IsLoaded)
        {
            ad.Show();
        }
        // when finished with it: ad.Destroy();
    },
    onFailed: error => Debug.LogWarning("Interstitial load failed: " + error));

Replace 23456 with your Ezoic ad unit id. Load and Show() are separate steps; guard Show() behind IsLoaded. Load a new EzoicInterstitialAd for each opportunity, and call Destroy() when you are done with an instance.

Try the Sample

The package ships a Basic Integration sample: a single MonoBehaviour with an on-screen control panel that initializes the SDK and loads, shows, hides, and destroys every ad type while logging each ad event.

To import it, open Window → Package Manager, select Ezoic Ads in the package list, open the Samples tab, and click Import next to Basic Integration. Then attach the imported EzoicAdsDemo script to a GameObject in an empty scene, set your domain and ad unit ids in the Inspector, and build to a device.

Example Project

For a complete, ready-to-open project, see the Ezoic Unity SDK example on GitHub. It is a minimal Unity project that installs this SDK through the UPM git URL and shows how to test your ad code without a device:

  • Assets/App/AdsBootstrap.cs: an app-style integration that initializes the SDK, then loads a banner, an interstitial, and a rewarded ad, recording every outcome.
  • Assets/Tests/EditMode/: tests for the synchronous API surface (nothing throws, IsInitialized and Version defaults are correct).
  • Assets/Tests/PlayMode/: tests that initialization and load callbacks are always delivered on the Unity main thread, never inline.
  • .github/workflows/ci.yml: runs both test suites headlessly on every push with GameCI.

Open the folder in Unity Hub (Unity 6000.3 LTS; any 2021.3 or newer editor works if you adjust ProjectSettings/ProjectVersion.txt). Unity resolves the SDK from GitHub automatically. Run the tests from Window → General → Test Runner.

The native SDKs can automatically read platform consent signals when they are set by a consent management platform. You can also set consent manually, any time after initialization:

EzoicAds.SetGDPRConsent(true, "TCF_CONSENT_STRING");
EzoicAds.SetGPPConsent("GPP_STRING", "7");
EzoicAds.SetSubjectToCOPPA(false);

For platform-specific consent behavior, see the Android privacy section and iOS privacy section.

Pageview Tracking

The native SDKs handle their platform-specific automatic pageview tracking. If your game changes screens, you can also track a pageview manually:

EzoicAds.TrackPageview();

Troubleshooting

Native library unresolved

If the build fails to find the native Ezoic library, confirm the External Dependency Manager for Unity (EDM4U) is installed. It reads the package's dependency manifest and resolves the native Android library and iOS CocoaPod for you; without it you must add the Gradle dependency and Podfile line manually.

No ads in the editor

Ads only serve on Android and iOS devices. In the Unity editor (and any other platform) the SDK runs as a safe no-op stub: calls never throw, load callbacks report failure, EzoicAds.IsInitialized is false, and EzoicAds.Version is an empty string. Build to a device to see ads.

iOS pods not installed

After Unity generates the Xcode project, EDM4U writes the EzoicAdsSDK pod into the Podfile. If pods are missing, run pod install in the Xcode build output directory. Also confirm the Google Mobile Ads application ID and the App Tracking Transparency description are present in Info.plist.