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

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

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.Datacontains AdGroupId, AdUnitId, ResponseInfoso you can check which ad unit responded. This information is not available for full-screen ads.

Sample: 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

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

ShowThe 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. adGroupIdIf is empty, Showdoes not request an ad and OnErrorreports 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.

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, RequestIdtogether. When asking about display issues, RequestIdattaching it will speed up tracking.

Resizedcontains Width·Height(CSS px) and HeightFraction(ratio relative to the canvas) are FailedToRender·NoFillcontains ErrorCode·ErrorMessagefilled 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 falseto Resized in the view.RenderedHeightLocalevent and read LayoutElement.preferredHeightdirectly. Otherwise, the layout group and auto-adjustment will overwrite each other's height.

Sample: 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. adGroupIdDoes 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. onErrorAre you subscribing to the event callbacks? The banner FailedToRender·NoFillin ErrorCodeand ErrorMessagecontains the reason.

Sample project

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

• Shared script: Tests~/E2E/SharedScripts/Runtime/
• Sample Unity projects by version: Tests~/E2E/

Related documents

• API usage patterns — Callback-based APIs, unsubscribing, error handling
• Build profile — Turning off devtools and checking the actual ad flow
• Troubleshooting — Other troubleshooting