In-App Ads - Interstitial/Rewarded Ads

For an introduction to the service and how to configure the console, the in-app ads introduction documentplease refer to it.

In-app Ads 2.0 ver2 is Toss Ads and Google AdMob integrates an integrated ad solution that automatically selects and displays the most suitable ad based on the environmentIt is an integrated ad solution. Partners only need to integrate one SDK, and the SDK automatically chooses which network to use based on the environment. You can expect more stable revenue by increasing ad display success rates.

Interstitial and Rewarded ads use the same API (loadFullScreenAd, showFullScreenAd), and the ad type is automatically determined based on the ad group ID (adGroupId).

Supported versions

The integrated ad API works differently depending on the Toss app version:

Toss app version	Supported features	Description
5.247.0 or later	In-app Ads 2.0 ver2	Toss Ads + AdMob
5.227.0 to below 5.247.0	In-app Ads 2.0	AdMob only
Below 5.227.0	Not supported	In-app Ads 2.0 ver2 cannot be used

isSupported() With this method, you can check whether In-app Ads 2.0 ver2 can be used in the current environment.

---

API overview

• loadFullScreenAd(params: LoadFullScreenAdParams): () => void — Preloads an ad. It provides a function that unregisters the callback (noop form) as the return value.
• showFullScreenAd(params: ShowFullScreenAdParams): () => void — Displays the loaded ad on the screen. It also returns an unregister function.

Each API isSupported() You can check whether the feature is available in the current environment through the property.

---

Load ad

SDK function: loadFullScreenAd

function loadFullScreenAd(params: LoadFullScreenAdParams): () => void;

Preloads an ad. You must call it before displaying the ad.

Please implement it like this for stable operation

• Preload ads on a page (or screen) basis.
• Ads must load → show → (next load) be called in this order.
• loadFullScreenAd After calling after receiving the event showFullScreenAdyou must call it.
• If the adGroupId is the same, only one ad can be preloaded at a time.
• When using multiple adGroupIds, you can preload one for each adGroupId.
• After displaying an ad, the pattern of preloading the next ad (load → show → load → show) is recommended.

Not loading on iOS?

If ads fail to load on iOS App Tracking Transparency (App Tracking Transparency) Please check the settings. If app tracking is not allowed, some ad loads may not work properly.

Parameters

• params · Required · LoadFullScreenAdParams

  This is the configuration object used when preloading ads. You can set the ad group ID and ad load event/error callbacks.

  • params.options · Required · LoadFullScreenAdOptions

    This is the options object passed when loading ads.

    • params.options.adGroupId · Required · string

      This is the ad group ID. You must enter the ID issued in the console.
  • params.onEvent · (event: LoadFullScreenAdEvent) => void

    This is a callback that receives events occurring during ad loading. You can receive various events such as ad load success events.
  • params.onError · (error: unknown) => void

    Called when loading the ad fails. Network errors or an unsupported environment may be the cause.

Property

isSupported

loadFullScreenAd.isSupported(): boolean

Checks whether In-app Ads 2.0 ver2 ads can be used in the current environment.

Example

tsx[React]

import { loadFullScreenAd } from '@apps-in-toss/web-framework';
import { useState, useEffect } from 'react';

function AdComponent() {
  const [isAdLoaded, setIsAdLoaded] = useState(false);

  useEffect(() => {
    // Check support
    if (!loadFullScreenAd.isSupported()) {
      console.warn('Ad functionality is not available.');
      return;
    }

    // Load ad
    const unregister = loadFullScreenAd({
      options: {
        adGroupId: 'ait.dev.43daa14da3ae487b',
      },
      onEvent: (event) => {
        if (event.type === 'loaded') {
          console.log('Ad load complete');
          setIsAdLoaded(true);
        }
      },
      onError: (error) => {
        console.error('Ad load failed:', error);
      },
    });

    // Cleanup
    return () => unregister();
  }, []);

  return (
    <button disabled={!isAdLoaded}>
      {isAdLoaded ? 'View ad' : 'Loading ad...'}
    </button>
  );
}

React Native

import { loadFullScreenAd } from '@apps-in-toss/framework';
import { useEffect, useState } from 'react';
import { Alert, Button, View } from 'react-native';

function AdComponent() {
  const [isAdLoaded, setIsAdLoaded] = useState(false);

  useEffect(() => {
    // Check support
    if (!loadFullScreenAd.isSupported()) {
      Alert.alert('Ad functionality is not available.');
      return;
    }

    // Load ad
    const unregister = loadFullScreenAd({
      options: {
        adGroupId: 'ait.dev.43daa14da3ae487b',
      },
      onEvent: (event) => {
        if (event.type === 'loaded') {
          Alert.alert('Ad load complete');
          setIsAdLoaded(true);
        }
      },
      onError: (error) => {
        Alert.alert('Ad load failed', String(error));
      },
    });

    // Cleanup
    return () => unregister();
  }, []);

  return (
    <View>
      <Button
        title={isAdLoaded ? 'View ad' : 'Loading ad...'}
        disabled={!isAdLoaded}
      />
    </View>
  );
}

LoadFullScreenAdParams

interface LoadFullScreenAdParams {
  options: LoadFullScreenAdOptions;
  onEvent: (data: LoadFullScreenAdEvent) => void;
  onError: (err: unknown) => void;
}

loadFullScreenAdThese are the parameter types.

LoadFullScreenAdOptions

interface LoadFullScreenAdOptions {
  adGroupId: string;
}

These are the ad load options.

LoadFullScreenAdEvent

interface LoadFullScreenAdEvent {
  type: 'loaded';
}

This is the ad load event. When the ad is successfully loaded, loaded a type event occurs.

---

Showing ads

SDK function: showFullScreenAd

function showFullScreenAd(params: ShowFullScreenAdParams): () => void;

Displays the loaded ad on the screen. loadFullScreenAdPlease use the ad preloaded with `loadFullScreenAd`.

Parameters

• params.options · Required · ShowFullScreenAdOptions

  These are the options passed when displaying ads.

  • params.options.adGroupId · Required · string

    This is the ad group ID. It must be the same as the ID used in `loadFullScreenAd`.
• params.onEvent · Required · (event: ShowFullScreenAdEvent) => void

  This is a callback that receives events that occur during ad display. You can receive various events such as ad impressions, clicks, and reward payouts.
• params.onError · Required · (error: unknown) => void

  This callback is called when the ad display request fails.

Property

isSupported

showFullScreenAd.isSupported(): boolean

Checks whether integrated ads can be used in the current environment.

Example

tsx[React]

import { loadFullScreenAd, showFullScreenAd } from '@apps-in-toss/web-framework';
import { useState, useEffect } from 'react';

function AdComponent() {
  const AD_GROUP_ID = 'ait.dev.43daa14da3ae487b';
  const [isAdLoaded, setIsAdLoaded] = useState(false);

  useEffect(() => {
    // Load ads when the component mounts
    const unregister = loadFullScreenAd({
      options: { adGroupId: AD_GROUP_ID },
      onEvent: (event) => {
        if (event.type === 'loaded') {
          setIsAdLoaded(true);
        }
      },
      onError: (error) => {
        console.error('Ad load failed:', error);
      },
    });

    return () => unregister();
  }, []);

  const handleShowAd = () => {
    showFullScreenAd({
      options: { adGroupId: AD_GROUP_ID },
      onEvent: (event) => {
        switch (event.type) {
          case 'requested':
            console.log('Ad display requested');
            break;
          case 'show':
            console.log('Ad displayed on screen');
            break;
          case 'impression':
            console.log('Ad impression recorded (revenue generated)');
            break;
          case 'clicked':
            console.log('Ad clicked');
            break;
          case 'dismissed':
            console.log('Ad closed');
            setIsAdLoaded(false);
            // Load the next ad
            loadNextAd();
            break;
          case 'failedToShow':
            console.error('Ad display failed');
            break;
          case 'userEarnedReward':
            console.log('Reward earned:', event.data);
            // Grant reward to the user
            grantReward(event.data.unitType, event.data.unitAmount);
            break;
        }
      },
      onError: (error) => {
        console.error('Ad display failed:', error);
      },
    });
  };

  const loadNextAd = () => {
    loadFullScreenAd({
      options: { adGroupId: AD_GROUP_ID },
      onEvent: (event) => {
        if (event.type === 'loaded') setIsAdLoaded(true);
      },
      onError: console.error,
    });
  };

  const grantReward = (unitType: string, unitAmount: number) => {
    // Reward granting logic
    console.log(`Granted ${unitAmount} ${unitType}`);
  };

  return (
    <button onClick={handleShowAd} disabled={!isAdLoaded}>
      View ad
    </button>
  );
}

React Native

import { loadFullScreenAd, showFullScreenAd } from '@apps-in-toss/framework';
import { useEffect, useState } from 'react';
import { Alert, Button, View } from 'react-native';

function AdComponent() {
  const AD_GROUP_ID = 'ait.dev.43daa14da3ae487b';
  const [isAdLoaded, setIsAdLoaded] = useState(false);

  useEffect(() => {
    // Load ads when the component mounts
    const unregister = loadFullScreenAd({
      options: { adGroupId: AD_GROUP_ID },
      onEvent: (event) => {
        if (event.type === 'loaded') {
          setIsAdLoaded(true);
        }
      },
      onError: (error) => {
        Alert.alert('Ad load failed', String(error));
      },
    });

    return () => unregister();
  }, []);

  const handleShowAd = () => {
    showFullScreenAd({
      options: { adGroupId: AD_GROUP_ID },
      onEvent: (event) => {
        switch (event.type) {
          case 'requested':
            console.log('Ad display requested');
            break;
          case 'show':
            console.log('Ad displayed on screen');
            break;
          case 'impression':
            console.log('Ad impression recorded (revenue generated)');
            break;
          case 'clicked':
            console.log('Ad clicked');
            break;
          case 'dismissed':
            setIsAdLoaded(false);
            loadNextAd();
            break;
          case 'failedToShow':
            Alert.alert('Ad display failed');
            break;
          case 'userEarnedReward':
            console.log('Reward earned:', event.data);
            grantReward(event.data.unitType, event.data.unitAmount);
            break;
        }
      },
      onError: (error) => {
        Alert.alert('Ad display failed', String(error));
      },
    });
  };

  const loadNextAd = () => {
    loadFullScreenAd({
      options: { adGroupId: AD_GROUP_ID },
      onEvent: (event) => {
        if (event.type === 'loaded') setIsAdLoaded(true);
      },
      onError: (error) => Alert.alert('Error', String(error)),
    });
  };

  const grantReward = (unitType: string, unitAmount: number) => {
    Alert.alert('Reward earned', `${unitType} ${unitAmount} has been granted.`);
  };

  return (
    <View>
      <Button title="View ad" onPress={handleShowAd} disabled={!isAdLoaded} />
    </View>
  );
}

ShowFullScreenAdParams

interface ShowFullScreenAdParams {
  options: ShowFullScreenAdOptions;
  onEvent: (data: ShowFullScreenAdEvent) => void;
  onError: (err: unknown) => void;
}

showFullScreenAdThese are the parameter types.

ShowFullScreenAdOptions

interface ShowFullScreenAdOptions {
  adGroupId: string;
}

These are the options for displaying ads.

ShowFullScreenAdEvent

type ShowFullScreenAdEvent =
  | { type: 'requested' }
  | { type: 'show' }
  | { type: 'impression' }
  | { type: 'clicked' }
  | { type: 'dismissed' }
  | { type: 'failedToShow' }
  | { type: 'userEarnedReward'; data: { unitType: string; unitAmount: number } };

These are the ad display events.

Event description

Event type	Description
requested	The ad display request was successful.
show	The ad was displayed on screen.
impression	The ad impression was recorded. (revenue generation point)
clicked	The user clicked the ad.
dismissed	The user closed the ad.
failedToShow	Ad display failed.
userEarnedReward	The user earned a reward from a rewarded ad.• data.unitType: Reward type (e.g., coin, point)• data.unitAmount: Reward amount

---

Usage guide

Ad load timing

We recommend preloading ads before displaying them.

• Recommended load timing list

  • When the component mounts
  • Immediately after the previous ad closes
  • Before switching to the screen where the ad will be displayed

// Good example: preload when entering the screen
useEffect(() => {
  loadFullScreenAd({
    /* ... */
  });
}, []);

// Bad example: load on button click (causes user wait time)
const handleClick = () => {
  loadFullScreenAd({
    /* ... */
  }); // loading time occurs
  showFullScreenAd({
    /* ... */
  });
};

Rewarded ad handling

userEarnedReward Grant rewards only when the event occurs. dismissedDo not grant rewards based on this alone.

showFullScreenAd({
  options: { adGroupId: REWARDED_AD_ID },
  onEvent: (event) => {
    if (event.type === 'userEarnedReward') {
      // Grant reward
      grantReward(event.data);
    }

    if (event.type === 'dismissed') {
      // Do not grant rewards based on dismissed alone
    }
  },
  onError: console.error,
});

Memory management

To prevent memory leaks, unregister callbacks when the component unmounts.

useEffect(() => {
  const unregister = loadFullScreenAd({
    /* ... */
  });

  return () => {
    unregister(); // Cleanup
  };
}, []);

Error handling

Always onError Provide a callback to handle ad load/display failures.

loadFullScreenAd({
  options: { adGroupId: AD_GROUP_ID },
  onEvent: (event) => {
    /* ... */
  },
  onError: (error) => {
    console.error('Ad load failed:', error);
    // Provide appropriate feedback to the user or retry
  },
});

---

Event flow

Interstitial ad

loadFullScreenAd call
  ↓
loaded event occurs
  ↓
showFullScreenAd call
  ↓
requested event occurs
  ↓
show event occurs (ad screen displayed)
  ↓
impression event occurs (revenue generation)
  ↓
clicked event (on click) or dismissed event (on close)

Rewarded ad (Rewarded)

loadFullScreenAd call
  ↓
loaded event occurs
  ↓
showFullScreenAd call
  ↓
requested event occurs
  ↓
show event occurs (ad screen displayed)
  ↓
impression event occurs (revenue generation)
  ↓
[User finished watching the ad]
  ↓
userEarnedReward event occurs (reward granted)
  ↓
dismissed event occurs (ad closes)

Ad policy

Toss Ads SSP policy

Please be sure to follow the policy below. Violations may restrict ad impressions.

Even if it is not specified in this policy, actions that artificially induce ad impressions, clicks, or performance, or cause user confusion, may be considered policy violations.

If a service is terminated due to policy violations, all partners must comply with the service termination policy.

Type	Prohibited actions	Specific examples	Policy criteria
UI/UX degradation	Configuring the UI so that the distinction between ads and content is unclear, or to induce ad consumption or clicks unrelated to user intent, or to obstruct normal service use	Disguising ads as "Recommended service", "Financial tips", etc. Changing the color or font of ad units outside the Toss Ads guide Arbitrarily modifying the ad title, label, CTA copy, and design A structure that places ads adjacent to user interaction elements (buttons, gameplay areas, etc.) so that unintended clicks occur When two or more ads of the same format are placed on the same screen A dead-end structure that makes it difficult for users to exit the screen normally or move to the previous screen A structure that makes it difficult for users to distinguish between the functions of ads and service CTAs A structure that makes it difficult to recognize or access CTAs needed for normal service use	Ads must always keep the "Ad" label All ad UIs must use web-base standard components Prohibit UI/UX configurations that artificially drive ad performance or degrade the user experience
Ad call behavior tampering	Changing or bypassing the SDK's default event flow or ad call method	SDK Click / Impression event tampering When ads are called through in-house logic without going through the ad SDK, or implemented by bypassing SDK events When the Back button is blocked or abnormally controlled to interfere with the user's normal screen exit or move to the previous screen	Do not tamper with the SDK's default event (Click / Impression) structure Calls to APIs outside the SDK are not allowed
Abnormal traffic and performance manipulation	Activities that distort traffic and ad performance through automation or artificial means	Periodically refresh the ad area Activities that artificially generate performance (clicks, impressions, etc.)	If abnormal patterns based on traffic quality are detected, ads may be restricted, sanctioned, or settlement may be withheld
Reward/engagement-based click prompting	Providing rewards or benefits at the same time as an ad click	"Reward provided immediately upon ad click" "Points provided when you click the ad"	Structures that directly link ad consumption to rewards are prohibited No reward-related copy or event linkage for clicks
Ad hiding or overlap	The act of intentionally hiding an ad or covering it with other UI elements so that users have difficulty clearly recognizing the ad's presence	• Transparent ads • Insert ad DOM behind another card UI	• Ads must be clearly visible in their displayed state

---

UX / Product Principle operating principles

Ads must also follow Toss's UX principles.

Toss Principle	Application criteria	Examples
Simplicity	Ads must be clear and understandable without additional explanation	Clear CTA such as "View now" or "View ad"
Clear Action	Users should be able to predict what action will happen after clicking an ad	Provide disclosure text when moving to an external destination
No Deception (UX Red Rule)	Ads must not appear at unexpected times, in unexpected forms, or in unexpected positions, nor mislead users	When an ad is disguised as content
Value First	Ads must not interfere with the customer's service goals	No inserting ads during payment/account opening flows

Usage restrictions and sanctions

If an Apps in Toss ad placement or service violates this policy, sanctions may be applied

---

Restriction procedure

In principle, restrictions are applied step by step based on the cumulative extent of violations. However, depending on the type or severity of the violation, a single violation may result in an immediate 30-day restriction or a permanent restriction.

※ Violations identified at the same time are treated as one violation regardless of the number of violation slots. If violations are later identified separately, the number of violations will accumulate.

---

Improper revenue handling

Revenue generated through policy violations, invalid traffic, or other improper methods may be considered improper revenue.

If improper revenue is confirmed, payment may be withheld or denied for that amount, and any amount already paid may also be recovered.

---

Appeal procedure

• If you received a usage restriction notice Apply for an appeal within 30 dayscan be done.

  • Appeal materials can be submitted through Channel Talk.
• Submitted materials are reviewed according to internal standards, and additional materials may be requested if necessary.

  • Review may take about one week in business days.
  • For appeal requests, reviewing whether the sanction was appropriateand, simply correcting the violation or submitting a prevention plan does not lift the sanction.
  • The sanction may be lifted if the submitted appeal materials show that the violation that was the basis for the sanction is not recognized, or if there is a clear error in the sanction decision.
• In the case of repeated or serious violations, service use may be permanently restricted.

---

Testing

In the development stage, be sure to use the test ad ID. Testing with a real ad ID will be considered a policy violation and may result in disadvantages.

• Interstitial ad: ait-ad-test-interstitial-id
• Reward ad: ait-ad-test-rewarded-id
• Banner ad - list type: ait-ad-test-banner-id
• Banner ad - feed type: ait-ad-test-native-image-id

Please be sure to check the items below before release.

• Check whether the ad loads properly.
• Check whether tapping it moves to the intended screen.
• Check whether the back button works properly.
• Check that it does not interfere with payment or authentication flows.

---

Frequently asked questions

"This feature is not supported in the current environment" error occurs

1. Please check whether you are running in the Toss app environment.
2. Please check whether the app version meets the requirements.
3. isSupported() Please first check support using the method.

The ad isn't loading

1. Please check whether the adGroupId (the ID issued in the console) is correct.
2. Please check your network connection.
3. onError Please check the message in the callback.
4. In the development environment, please use the test adGroupId. (e.g.: ait.dev.43daa14da3ae487b)

After calling the ad load function, does the event usually arrive within a few seconds?

The time required varies depending on which network's ad is shown.

**Toss Ads**: Usually loads within 1–2 seconds. Depending on network conditions, it may take up to 10 seconds.
**Google AdMob**: It generally takes about 5–20 seconds, and may take longer. It is heavily affected by the user's network conditions and can be delayed up to the maximum network timeout of 60 seconds.

Which network will be selected is determined automatically by the SDK depending on the environment, so we recommend preloading it before entering the screen where the ad will be shown.

I called showFullScreenAd, but the ad is not displayed

1. loadFullScreenAdcall it first and loaded check whether the event was received.
2. Please check whether the same adGroupId was used.
3. An already displayed ad cannot be shown again, so it needs to be loaded again.
4. failedToShow event or onError Please check for errors in the callback.

The reward is not being paid

1. userEarnedReward Please check whether the event occurred.
2. Please check whether the user watched the ad to the end. (If they close it midway, the reward will not be paid.)
3. event.datain unitTypeand unitAmountPlease check.

The dismissed event does not occur

In Android Toss app version 5.255.0, dismissed the event does not occur. It works normally in versions other than that one.

The ad load event is intermittently not delivered

In Android Toss app version 5.266.0, there was an issue where if you called the ad load function and then called load again before receiving the event, the event for the additional call was intermittently not delivered.

We resolved the issue by rolling back the server logic, but if the cache remained intermittently and the same issue recurred, users might have needed to force-quit and relaunch the Toss app.

While the issue existed, the guidance below needed to be applied.

Please load ad group IDs one at a time, in sequence. If multiple ad group IDs are loaded at the same time in a mini app, they will not be processed properly. Interstitial/rewarded ads need to be loaded separately. (e.g.: load interstitial group ID → receive event → load rewarded group ID → receive event → display) Please call the ad display function after receiving the event following the ad load function call. This does not apply to banner ads.

From Android version 5.267.0, the above issue has been improved, so restarting the Toss app is no longer necessary, and it has been changed so that multiple interstitial ad instances can be preloaded in a single mini app.

The loaded event does not occur

On Android version 5.266.0 and later, when interstitial/rewarded ads and banner ads are loaded at the same time, the events for interstitial/rewarded ads are not delivered.

While the issue existed, the guidance below needed to be applied.

Please load ad group IDs one at a time, in sequence. If multiple ad group IDs are loaded at the same time in a mini app, they will not be processed properly. Interstitial/rewarded/banner ads need to be loaded separately. (e.g.: load interstitial group ID → receive event → load banner ID → receive event → display) Please call the ad display function after receiving the event following the ad load function call.

This is scheduled to be improved from Android 5.268.0 onward.

The in-app ad feature doesn't work in sandbox

The in-app ad feature is not supported in sandbox.

Sorry for the inconvenience, but please test using the QR code in the console.