> 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/common/monetization/iaa/interstitial-rewarded-ad.md).
# In-app ads - interstitial/rewarded ads
For service introduction and console setup, please refer to [In-app Ads Introduction Document](https://developers-apps-in-toss.toss.im/guide/monetization/in-app-ad).
In-app Ads 2.0 ver2 **Toss Ads** and **Google AdMob** integrates them and, depending on the environment, **an integrated ad solution that automatically selects and displays the most suitable ad**It is. Partners only need to integrate one SDK, and the SDK automatically selects which network to use based on the environment. You can expect more stable revenue by improving ad display success rates.
**Interstitial** and **Rewarded** All ads use the same API (`loadFullScreenAd`, `showFullScreenAd`) and the ad type is **ad group ID (`adGroupId`)** is determined automatically based on it.
### Supported version
The integrated ad API behaves 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 supported |
| **below 5.227.0** | Not supported | In-app Ads 2.0 ver2 not available |
> `isSupported()` You can check whether In-app Ads 2.0 ver2 can be used in the current environment with a method.
***
### API overview
* `loadFullScreenAd(params: LoadFullScreenAdParams): () => void` — Preloads the ad. It returns a callback unregister function (noop).
* `showFullScreenAd(params: ShowFullScreenAdParams): () => void` — Displays the loaded ad on screen. It likewise returns an unregister function.
Each API can `isSupported()` use the property to check whether the feature is available in the current environment.
***
### Loading ads
**SDK function:** `loadFullScreenAd`
```typescript
function loadFullScreenAd(params: LoadFullScreenAdParams): () => void;
```
Preloads the ad. You must call this before displaying the ad.
{% hint style="info" %}
**For stable operation, please implement it like this**
* Preload ads on a page (or screen) basis.
* Ads must always **`load → show → (next load)`** be called in that order.
* `loadFullScreenAd` After calling **after receiving the event** `showFullScreenAd`you need to call it.
* such as `adGroupId` You can preload only one ad at a time as a rule.
* When using multiple `adGroupId`when using \[them], each `adGroupId`can be preloaded one by one.
* After displaying an ad, the pattern of preloading the next ad (`load → show → load → show`) is recommended.
{% endhint %}
{% hint style="info" %}
**Isn't it loading on iOS?**
If ads aren't loading on iOS **App Tracking Transparency (ATT)** Please check the settings. If app tracking is not allowed, some ad loads may not work properly.
{% endhint %}
**Parameters**
* **params** · Required · `LoadFullScreenAdParams`
This is the configuration object used when preloading an ad. You can set the ad group ID and the ad load event/error callbacks.
* **params.options** · Required · `LoadFullScreenAdOptions`
This is the options object passed when loading an ad.
* **params.options.adGroupId** · Required · `string`
This is the ad group ID. Enter the ID issued in the console.
* **params.onEvent** · `(event: LoadFullScreenAdEvent) => void`
This callback receives events that occur during ad loading. You can receive various events, such as ad load success.
* **params.onError** · `(error: unknown) => void`
Called when loading the ad fails. Causes may include network errors or unsupported environments.
**Properties**
**`isSupported`**
```typescript
loadFullScreenAd.isSupported(): boolean
```
Checks whether In-app Ads 2.0 ver2 can be used in the current environment.
**Example**
{% tabs %}
{% tab title="tsx\[React]" %}
```tsx
import { loadFullScreenAd } from '@apps-in-toss/web-framework';
import { useState, useEffect } from 'react';
function AdComponent() {
const [isAdLoaded, setIsAdLoaded] = useState(false);
useEffect(() => {
// Check support status
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 (
);
}
```
{% endtab %}
{% tab title="React Native" %}
```tsx
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 status
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 (
);
}
```
{% endtab %}
{% endtabs %}
**`LoadFullScreenAdParams`**
```typescript
interface LoadFullScreenAdParams {
options: LoadFullScreenAdOptions;
onEvent: (data: LoadFullScreenAdEvent) => void;
onError: (err: unknown) => void;
}
```
`loadFullScreenAd`is the parameter type.
**`LoadFullScreenAdOptions`**
```typescript
interface LoadFullScreenAdOptions {
adGroupId: string;
}
```
These are the ad load options.
**`LoadFullScreenAdEvent`**
```typescript
interface LoadFullScreenAdEvent {
type: 'loaded';
}
```
This is the ad load event. When the ad loads successfully, `loaded` a type event is triggered.
***
### Displaying ads
**SDK function:** `showFullScreenAd`
```typescript
function showFullScreenAd(params: ShowFullScreenAdParams): () => void;
```
Displays the loaded ad on screen. `loadFullScreenAd`Please use the ad preloaded with it.
**Parameters**
* **params.options** · Required · `ShowFullScreenAdOptions`
These are the options passed when displaying an ad.
* **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 callback receives events that occur during ad display. You can receive various events such as impressions, clicks, and reward grants.
* **params.onError** · Required · `(error: unknown) => void`
This callback is called when the ad display request fails.
**Properties**
**`isSupported`**
```typescript
showFullScreenAd.isSupported(): boolean
```
Checks whether integrated ads are available in the current environment.
**Example**
{% tabs %}
{% tab title="tsx\[React]" %}
```tsx
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 ad 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 shown 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 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}(s)`);
};
return (
);
}
```
{% endtab %}
{% tab title="React Native" %}
```tsx
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 ad 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 shown 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} units have been granted.`);
};
return (
);
}
```
{% endtab %}
{% endtabs %}
**`ShowFullScreenAdParams`**
```typescript
interface ShowFullScreenAdParams {
options: ShowFullScreenAdOptions;
onEvent: (data: ShowFullScreenAdEvent) => void;
onError: (err: unknown) => void;
}
```
`showFullScreenAd`is the parameter type.
**`ShowFullScreenAdOptions`**
```typescript
interface ShowFullScreenAdOptions {
adGroupId: string;
}
```
These are the ad display options.
**`ShowFullScreenAdEvent`**
```typescript
type ShowFullScreenAdEvent =
| { type: 'requested' }
| { type: 'show' }
| { type: 'impression' }
| { type: 'clicked' }
| { type: 'dismissed' }
| { type: 'failedToShow' }
| { type: 'userEarnedReward'; data: { unitType: string; unitAmount: number } };
```
These are ad display events.
**Event description**
| Event type | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `requested` | The ad display request succeeded. |
| `show` | The ad was displayed on screen. |
| `impression` | The ad impression was recorded. (Point at which revenue is generated) |
| `clicked` | The user clicked the ad. |
| `dismissed` | The user closed the ad. |
| `failedToShow` | Failed to display the ad. |
| `userEarnedReward` | The user earned a reward in 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 preload timing
* When the component mounts
* Immediately after the previous ad is closed
* Before navigating to the screen where the ad will be shown
```tsx
// ✅ 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. `dismissed`You should not grant rewards based on that alone.
```tsx
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**
Prevent memory leaks by unregistering callbacks when the component unmounts.
```tsx
useEffect(() => {
const unregister = loadFullScreenAd({
/* ... */
});
return () => {
unregister(); // Cleanup
};
}, []);
```
**Error Handling**
Always `onError` Provide callbacks to handle ad load/display failures.
```tsx
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
{% tabs %}
{% tab title="Interstitial ad" %}
```
Call loadFullScreenAd
↓
loaded event occurs
↓
Call showFullScreenAd
↓
requested event occurs
↓
show event occurs (ad displayed)
↓
impression event occurs (revenue generated)
↓
clicked event (on click) or dismissed event (on close)
```
{% endtab %}
{% tab title="Rewarded ad" %}
```
Call loadFullScreenAd
↓
loaded event occurs
↓
Call showFullScreenAd
↓
requested event occurs
↓
show event occurs (ad displayed)
↓
impression event occurs (revenue generated)
↓
[User has finished watching the ad]
↓
userEarnedReward event occurs (reward granted)
↓
dismissed event occurs (ad closed)
```
{% endtab %}
{% endtabs %}
### Advertising policy
#### Toss Ads SSP policy
Please make sure to follow the policies below. Violations may restrict ad impressions.
**Even if not specified in this policy, any act that artificially induces ad impressions, clicks, or performance, or causes user confusion, may be considered a policy violation.**
If any partner service is terminated for violating policy, all partners must comply with the service termination policy.
| Type | Prohibited actions | Specific examples | Policy criteria |
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Degradation of UI/UX quality | Structuring the UI in a way that blurs the distinction between ads and content, induces ad consumption or clicks unrelated to user intent, or interferes with normal service use |
Disguising ads as "Recommended services," "Financial tips," etc.
Changing the colors or fonts of ad units outside the Toss Ads guidelines
Arbitrarily modifying ad titles, labels, CTA copy, and design
Placing ads adjacent to user interaction elements (buttons, game play areas, etc.) to cause unintended clicks
Placing two or more ads of the same format on the same screen
A dead-end structure that makes it difficult for users to exit the screen normally or go back to the previous screen
A structure that makes it difficult for users to distinguish between ad functions and service CTAs
A structure that makes it difficult to recognize or access the CTA needed for normal service use
|
Ads must keep the "Ad" label
All ad UIs must use web-base standard components
Prohibit UI/UX setups that artificially drive ad performance or degrade user experience
|
| Ad call manipulation | Changing or bypassing the SDK's default event flow or ad call method |
SDK Click / Impression event manipulation
If ads are called through custom logic without going through the ad SDK, or SDK events are bypassed
If the Back button is blocked or improperly controlled, preventing the user from exiting the screen normally or returning to the previous screen
|
Prohibit manipulating the SDK's default event (Click / Impression) structure
No external API calls from the SDK
|
| Abnormal traffic and performance manipulation | Any act that distorts traffic and ad performance through automation or artificial means |
Periodically refreshing the ad area
Activities that artificially generate performance (clicks, impressions, etc.)
|
If abnormal patterns based on traffic quality are detected, ad restrictions, sanctions, and payment holds may be applied
|
| Reward-based / participation-based click inducement | Providing rewards or benefits at the same time as ad clicks |
"Rewards provided immediately after clicking the ad"
"Points provided when you click the ad"
|
Prohibit structures that directly link ad consumption to rewards
Prohibit reward-related copy and event linkage for clicks
|
| Ad hiding or overlap | Any act of intentionally hiding ads or obscuring them with other UI elements so users cannot clearly recognize the presence of the ads |
• Transparent ads
• Inserting ad DOM behind another card UI
| • Ads must have clearly verifiable visible status |
***
#### **UX / Product Principle Operating Guidelines**
Ads must also follow Toss's UX principles.
| **Toss Principle** | **Application criteria** | **Examples** |
| ------------------------------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| **Simplicity** | Ads should be clear and understandable without extra explanation | Clear CTAs like "Watch now" or "View ad" |
| **Clear Action** | Users should be able to predict what will happen after clicking the ad | Provide a notice for external navigation |
| **No Deception (UX Red Rule)** | Ads must not appear at unexpected moments, in unexpected forms or locations, or mislead users | When disguising an ad as content |
| **Value First** | Ads should not interfere with the customer's service goals | Prohibit inserting ads during payment/account opening flows |
#### **Usage restrictions and sanctions**
Sanctions may be applied if the App in Toss ad placement or service violates this policy.
***
**Restriction procedures**
As a rule, restrictions are applied step by step according to the accumulated degree of violations. However, depending on the type or severity of the violation, a single violation may result in an immediate 30-day suspension or permanent suspension.
※ Violations identified at the same time are treated as one violation, regardless of the number of violating slots. If violations are later identified separately, the number of violations accumulates.
***
**Handling of unjust gains**
Revenue generated through policy violations, invalid traffic, or other fraudulent means may be considered unjust gains.
If unjust gains are identified, payment for the amount may be withheld or denied, and any amount already paid may also be recovered in the same way.
***
**Appeal procedure**
* If you have received a notice of usage restriction **You may file an appeal within 30 days**You can.
* Appeal materials can be submitted via Channel Talk.
* Submitted materials are reviewed according to internal criteria, and additional materials may be requested if necessary.
* Review may take about one week on business days.
* For appeal requests **review focuses on whether the sanction was appropriate**and simply correcting the violation or submitting a recurrence prevention plan will not lift the sanction.
* If the submitted appeal materials show that the violation underlying the sanction is not recognized or that there is a clear error in the sanction decision, the sanction may be lifted.
* In cases of repeated or serious violations, service use may be permanently restricted.
***
### Testing
During development, you must use test ad IDs. Testing with real ad IDs may be considered a policy violation and result in disadvantages.
* Interstitial ads: `ait-ad-test-interstitial-id`
* Rewarded ads: `ait-ad-test-rewarded-id`
* Banner ads - list type: `ait-ad-test-banner-id`
* Banner ads - feed type: `ait-ad-test-native-image-id`
Please make sure to check the items below before launch.
* Check that the ad loads properly.
* Check that clicking takes you to the intended screen.
* Check that 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 that you are running in the Toss app environment.
2. Please check whether the app version meets the requirements.
3. `isSupported()` Please check support with the method first.
The ad is not loading
1. `adGroupId`Please check whether the ID (issued in the console) is correct.
2. Please check your network connection.
3. `onError` Please check the callback message.
4. In the development environment, use the test `adGroupId`please use it. (e.g., `ait.dev.43daa14da3ae487b`)
After calling the ad load function, does the event usually arrive within a few seconds?
The time taken varies depending on which network's ad is shown.
```
**Toss Ads**: Usually loads within 1–2 seconds. Depending on network conditions, it can take up to 10 seconds.
**Google AdMob**: Typically takes about 5–20 seconds and may take longer. It is highly affected by the user's network conditions and may be delayed up to the maximum network timeout of 60 seconds.
```
Since the SDK automatically determines which network to choose depending on the environment, we recommend preloading before entering the screen where the ad will be shown.
I called showFullScreenAd, but the ad isn't showing
1. `loadFullScreenAd`call it first and `loaded` Please check whether you received the event.
2. The same `adGroupId`Please check whether it was used.
3. An ad that has already been shown cannot be shown again, so it needs to be loaded again.
4. `failedToShow` Check the event or `onError` Please check the error in the callback.
The reward is not being granted
1. `userEarnedReward` Please check whether the event occurred.
2. Please check whether the user watched the ad to the end. (If closed midway, the reward is not granted)
3. `event.data`in `unitType`and `unitAmount`Please check.
The dismissed event is not occurring
In Android Toss app version 5.255.0, `dismissed` the event does not occur. It works normally in versions other than that one.
Ad load events are not being delivered intermittently
In Android Toss app version 5.266.0, if you called the ad load function and then made another load call before receiving the event, there was an issue where events for the additional call were intermittently not delivered.
We fixed the issue by rolling back the server logic, but if cached data occasionally remained and the same symptom recurred, the user might have needed to force-close the Toss app process and relaunch it.
While the issue was present, the guide below needed to be applied.
Please load ad group IDs sequentially, one at a time. If multiple ad group IDs are loaded at the same time in a mini app, they will not be processed correctly. Interstitial/rewarded ads must be loaded separately. (e.g., load interstitial group ID → receive event → load rewarded group ID → receive event → display) Please call the ad display function only after receiving the event after calling the ad load function. Banner ads do not apply.
From Android 5.267.0 onward, the issue above was improved, so restarting the Toss app is no longer necessary, and it was changed so that multiple interstitial ad instances can be preloaded in a single mini app.
The loaded event is not occurring
In Android 5.266.0 and later, if interstitial/rewarded ads and banner ads are loaded at the same time, the interstitial/rewarded ad events are not delivered.
While the issue was present, the guide below needed to be applied.
Please load ad group IDs sequentially, one at a time. If multiple ad group IDs are loaded at the same time in a mini app, they will not be processed correctly. Interstitial/rewarded/banner ads must be loaded separately. (e.g., load interstitial group ID → receive event → load banner ID → receive event → display) Please call the ad display function only after receiving the event after calling the ad load function.
It is planned to be improved starting from Android 5.268.0.
The in-app ad feature doesn't work in the sandbox
The in-app ad feature is not supported in the sandbox.
Sorry for the inconvenience, but please run the test using the QR code in the console.
---
# 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/common/monetization/iaa/interstitial-rewarded-ad.md?ask=&goal=
```
`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.