# Unity

Source: https://docs.ezoic.com/docs/mobileapps/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:

```json
{
  "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](https://github.com/googlesamples/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`:

```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](/docs/mobileapps/ios/#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)`.

```csharp
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.

```csharp
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.

## Banner Sizes

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"`:

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

## Banner Events

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

```csharp
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.

```csharp
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](https://github.com/ezoic/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](https://game.ci).

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

## Privacy and Consent

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:

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

For platform-specific consent behavior, see the [Android privacy section](/docs/mobileapps/android/#privacy-and-consent) and [iOS privacy section](/docs/mobileapps/ios/#privacy-and-consent).

## Pageview Tracking

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

```csharp
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`.