> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/unity/add-features/advertising.md).

# Ad integration

Explains the three ad surfaces provided by the SDK and how to attach each one.

| Ad type        | Entry API                                       | Format                 | When to use                                                                    |
| -------------- | ----------------------------------------------- | ---------------------- | ------------------------------------------------------------------------------ |
| Full-screen ad | `AIT.LoadFullScreenAd` / `AIT.ShowFullScreenAd` | Interstitial, Rewarded | Directly display Toss ad network interstitial and rewarded ads                 |
| AdMob ads      | `AIT.GoogleAdMobLoadAppsInTossAdMob` / `…Show…` | Interstitial, Rewarded | Displayed through Google AdMob mediation                                       |
| Banner ad      | `AITBannerAd`, `AITBannerAdView`                | Banner                 | Always displayed at the top or bottom of the screen, or in any designated area |

Both full-screen ads and AdMob ads **Interstitial** and **Rewarded** are supported. Both use the same call API, and **`adGroupId`are distinguished by**; only rewarded ads additionally fire `userEarnedReward` events when the user earns a reward.

### Common premise

* **`adGroupId`** is the ad group ID issued from the Apps in Toss console. This value determines the ad type (interstitial/rewarded, banner emphasis type) and display policy.
* **Actual ad rendering works only inside the Toss app.** In a regular browser or Unity Editor, the ad network cannot be reached, so after initialization `FailedToRender`·`NoFill`(banner) or an error callback is received, which is normal. `AIT` > `Deploy (Test)`Deploy it and check on a real device via QR.
* In the Unity Editor and non-WebGL environments, all ad APIs `[AIT Mock]` only log messages and do not trigger real events. To verify behavior, build to WebGL and test inside the Toss app.
* All callback-based APIs **for unsubscribing `Action`** return. `OnDestroy` Call it in places like this to clean up.

### Full-screen ad

This is the native path for displaying Toss ad network interstitial and rewarded ads. **`Load` then `Show`** are called in two steps.

```csharp
using AppsInToss;

// adGroupId is the value issued by the console. Interstitial/rewarded ads are distinguished by adGroupId.
private const string AD_GROUP_ID = "your-ad-group-id";
private Action _unsubscribe;

// Step 1: pre-load
void Load()
{
    _unsubscribe = AIT.LoadFullScreenAd(
        adGroupId: AD_GROUP_ID,
        onEvent: e =>
        {
            if (e.Type == "loaded") Show();   // display after load completes
        },
        onError: err => Debug.LogError($"load failed: {err.ErrorCode} {err.Message}")
    );
}

// Step 2: display
void Show()
{
    AIT.ShowFullScreenAd(
        adGroupId: AD_GROUP_ID,
        onEvent: e =>
        {
            // When the user earns a reward in a rewarded ad
            if (e.Type == "userEarnedReward" && e.Data != null)
                Debug.Log($"Reward: {e.Data.UnitAmount} {e.Data.UnitType}");

            if (e.Type == "dismissed")
                Debug.Log("Ad closed — Load again for the next display");
        },
        onError: err => Debug.LogError($"show failed: {err.ErrorCode} {err.Message}")
    );
}

void OnDestroy() => _unsubscribe?.Invoke();
```

| Step | `e.Type`           | Meaning                                                                    |
| ---- | ------------------ | -------------------------------------------------------------------------- |
| Load | `loaded`           | Ad load complete — then `Show` possible                                    |
| Show | `userEarnedReward` | Rewarded only. User reward earned (`e.Data.UnitType`, `e.Data.UnitAmount`) |
| Show | `dismissed`        | Ad closed — before the next display, re `Load` required                    |

Sample: [FullScreenAdTester.cs](https://github.com/toss/apps-in-toss-unity-sdk/blob/main/Tests~/E2E/SharedScripts/Runtime/FullScreenAdTester.cs) — You can interactively check interstitial/rewarded selection, the Load → Show flow, and event logs.

### AdMob ads

Displays interstitial and rewarded ads via Google AdMob mediation. Like full-screen ads, **`Load` then `Show`** the flow is the same, and there is an additional API to check whether it is loaded.

```csharp
using AppsInToss;

private const string AD_GROUP_ID = "your-admob-ad-group-id";
private Action _unsubscribe;

void Load()
{
    _unsubscribe = AIT.GoogleAdMobLoadAppsInTossAdMob(
        options: new LoadAdMobOptions { AdGroupId = AD_GROUP_ID },
        onEvent: e =>
        {
            if (e.Type == "loaded" && e.Data != null)
                Debug.Log($"loaded: adUnitId={e.Data.AdUnitId}");
        },
        onError: err => Debug.LogError($"{err.ErrorCode} {err.Message}")
    );
}

void Show()
{
    AIT.GoogleAdMobShowAppsInTossAdMob(
        options: new ShowAdMobOptions { AdGroupId = AD_GROUP_ID },
        onEvent: e =>
        {
            if (e.Type == "userEarnedReward" && e.Data != null)
                Debug.Log($"Reward: {e.Data.UnitAmount} {e.Data.UnitType}");
            if (e.Type == "dismissed")
                Debug.Log("Ad closed — Load again");
        },
        onError: err => Debug.LogError($"{err.ErrorCode} {err.Message}")
    );
}

// Check whether loaded
async void CheckLoaded()
{
    bool loaded = await AIT.GoogleAdMobIsAppsInTossAdMobLoaded(
        new IsAdMobLoadedOptions { AdGroupId = AD_GROUP_ID });
    Debug.Log($"loaded = {loaded}");
}

void OnDestroy() => _unsubscribe?.Invoke();
```

In the load event's `e.Data`contains `AdGroupId`, `AdUnitId`, `ResponseInfo`so you can check which ad unit responded. This information is not available for full-screen ads.

Sample: [AdV2Tester.cs](https://github.com/toss/apps-in-toss-unity-sdk/blob/main/Tests~/E2E/SharedScripts/Runtime/AdV2Tester.cs) — Example of Load, Show, and IsLoaded calls for AdMob interstitial/rewarded ads, plus reward event handling.

### Banner ad

Since the SDK creates and manages the DOM container directly, you don't need to know HTML or CSS. There are two ways.

* **`AITBannerAd`** — Static helper. Displays in preset positions at the top or bottom of the screen with a single line of code. Keeps only one slot, and calling it again replaces the existing banner.
* **`AITBannerAdView`** — MonoBehaviour component. If you place a RectTransform under a Canvas as you normally would with uGUI, the banner overlays that area. It automatically tracks movement, resizing, and screen rotation, and because each instance has its own independent slot, **multiple banners at the same time** can be displayed.

Banner **emphasis type**(text emphasis is fixed at about 90px, image emphasis uses a variable 16:9 height) is determined not by code but by the ad group settings in the console. Variable height is `Resized` event.

#### Display at preset positions with AITBannerAd

```csharp
using AppsInToss;

AITBannerAd.OnAdEvent += evt => Debug.Log($"Banner event: {evt}");
AITBannerAd.OnError += msg => Debug.LogWarning($"Banner error: {msg}");

// Display at the bottom of the screen (default: Bottom / Auto theme / black-and-white tone / expanded)
AITBannerAd.Show("your-banner-ad-group-id", AITBannerPosition.Bottom);

// Hide
AITBannerAd.Hide();
```

`Show`The appearance is controlled by the optional arguments.

| Argument   | Value                                        | Default         |
| ---------- | -------------------------------------------- | --------------- |
| `position` | `Top`, `Bottom` (both reflect the safe area) | `Bottom`        |
| `theme`    | `Auto`, `Light`, `Dark`                      | `Auto`          |
| `tone`     | `BlackAndWhite`, `Grey`                      | `BlackAndWhite` |
| `variant`  | `Card`, `Expanded`                           | `Expanded`      |

To check whether it is currently displayed, use `AITBannerAd.IsShowing`. `adGroupId`If is empty, `Show`does not request an ad and `OnError`reports it and returns.

#### Display in a RectTransform area with AITBannerAdView

In the Inspector `Ad Group Id`, `Placement`, theme·tone·variant, `On Ad Event`(UnityEvent) or attach it in code.

```csharp
using AppsInToss;

// The banner overlays the RectTransform area where you want to show it (this GameObject).
var view = gameObject.AddComponent<AITBannerAdView>();
view.AdGroupId = "your-banner-ad-group-id";
view.Placement = AITBannerAdPlacement.FollowRectTransform; // or ScreenTop / ScreenBottom

// Passed both through C# events and Inspector UnityEvents.
view.OnAdEvent += evt =>
{
    if (evt.Kind == AITBannerAdEventKind.Resized)
        Debug.Log($"Rendered height {evt.Height}px (ratio {evt.HeightFraction:F3})");
};

view.Show();   // if showOnEnable is true (default) and AdGroupId is set, it is called automatically in OnEnable
// view.Hide();
```

#### Banner events

Both methods receive the same `AITBannerAdEvent`.

| `Kind`                                | Meaning                            |
| ------------------------------------- | ---------------------------------- |
| `Initialized`, `InitializationFailed` | Ad SDK initialized, failed         |
| `Rendered`                            | Banner rendering complete          |
| `Viewable`, `Impression`              | screen display, impression counted |
| `Clicked`                             | Banner clicked                     |
| `Resized`                             | Rendered banner size changed       |
| `FailedToRender`, `NoFill`            | Render failed, no ad to fill       |

The event object includes `AdGroupId`, `SlotId`, `CreativeId`, `RequestId`together. When asking about display issues, `RequestId`attaching it will speed up tracking.

`Resized`contains `Width`·`Height`(CSS px) and `HeightFraction`(ratio relative to the canvas) are `FailedToRender`·`NoFill`contains `ErrorCode`·`ErrorMessage`filled in.

> **Caution**: `FollowRectTransform` in mode `AutoResizeHeight`(default `true`) adjusts the RectTransform height to match the actual banner height. When placing it under a layout group, set this value to `false`to `Resized` in the `view.RenderedHeightLocal`event and read `LayoutElement.preferredHeight`directly. Otherwise, the layout group and auto-adjustment will overwrite each other's height.

Sample: [BannerAdTester.cs](https://github.com/toss/apps-in-toss-unity-sdk/blob/main/Tests~/E2E/SharedScripts/Runtime/BannerAdTester.cs) — You can display two components (text emphasis and image emphasis) together with the static helper to verify multi-slot and automatic height behavior.

### When the ad is not visible

1. **Is it running inside the Toss app?** Actual rendering works only inside the Toss app. In a regular browser and the Editor, it is normal to receive failed/no-fill events after initialization. `Deploy (Test)`Deploy it and check on a real device.
2. **`adGroupId`Does it match the value issued by the console?** An incorrect ID is rejected with a format/parameter error (for example: `code 1002`).
3. **Interstitial and AdMob ads `loaded` after `Show` have you done it?** `dismissed` After that, you must `Load` again.
4. **`onError`Are you subscribing to the event callbacks?** The banner `FailedToRender`·`NoFill`in `ErrorCode`and `ErrorMessage`contains the reason.

### Sample project

Interactive testers for the three ads are included in the repository samples.

* Shared script: [`Tests~/E2E/SharedScripts/Runtime/`](https://github.com/toss/apps-in-toss-unity-sdk/tree/main/Tests~/E2E/SharedScripts/Runtime)
* Sample Unity projects by version: [`Tests~/E2E/`](https://github.com/toss/apps-in-toss-unity-sdk/tree/main/Tests~/E2E)

### Related documents

* [API usage patterns](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/api-usage-patterns) — Callback-based APIs, unsubscribing, error handling
* [Build profile](https://developers-apps-in-toss.toss.im/documentation/unity/build/build-profiles) — Turning off devtools and checking the actual ad flow
* [Troubleshooting](https://developers-apps-in-toss.toss.im/documentation/unity/first-steps/faq) — Other troubleshooting


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/unity/add-features/advertising.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.