> 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-zh/common/monetization/iaa/interstitial-rewarded-ad.md).
# 应用内广告 - 插屏/激励广告
服务介绍和控制台设置方法请参考 [In-app 广告介绍文档](https://developers-apps-in-toss.toss.im/guide/monetization/in-app-ad)。
In-app 广告 2.0 ver2 是 **Toss Ads(Toss Ads)** 和 **Google AdMob(Google AdMob)** 集成后可根据环境 **自动选择并展示最适合广告的集成广告解决方案**。合作方只需接入一个 SDK，至于使用哪个网络，SDK 会根据环境自动选择。可提高广告展示成功率，期待更稳定的收益。
**插屏(Interstitial)** 和 **激励型(Rewarded)** 广告都使用相同的 API(`loadFullScreenAd`, `showFullScreenAd`)，广告类型会根据广告组 ID(adGroupId)自动决定。
### 支持版本
集成广告 API 会根据 Toss 应用版本不同而表现不同：
| Toss 应用版本 | 支持功能 | 说明 |
| ------------------------- | ------------------ | ----------------------- |
| **5.247.0 及以上** | In-app 广告 2.0 ver2 | Toss Ads + AdMob |
| **5.227.0 \~ 5.247.0 以下** | In-app 广告 2.0 | 仅支持 AdMob |
| **低于 5.227.0** | 不支持 | 无法使用 In-app 广告 2.0 ver2 |
> `isSupported()` 可通过该方法确认当前环境是否可使用 In-app 广告 2.0 ver2。
***
### API 概览
* `loadFullScreenAd(params: LoadFullScreenAdParams): () => void` — 预先加载广告。会以返回值提供用于取消注册回调的函数（noop 形式）。
* `showFullScreenAd(params: ShowFullScreenAdParams): () => void` — 将已加载的广告显示到屏幕上。同样会返回取消注册函数。
每个 API 都可以通过 `isSupported()` 属性确认当前环境下该功能是否可用。
***
### 加载广告
**SDK 函数：** `loadFullScreenAd`
{% code collapsedlinecount="10" %}
```typescript
function loadFullScreenAd(params: LoadFullScreenAdParams): () => void;
```
{% endcode %}
会预先加载广告。显示广告前必须调用。
{% hint style="info" %}
**若要稳定运营，请这样实现**
* 请按页面（或屏幕）维度预先加载广告。
* 广告必须 **`load → show → (下一次 load)`** 按该顺序调用。
* `loadFullScreenAd` 调用后 **收到事件后** `showFullScreenAd`才能调用。
* 若 adGroupId 相同，一次只能预加载一个广告。
* 若使用多个 adGroupId，则可分别为每个 adGroupId 预加载一个广告。
* 在展示广告后预先加载下一条广告的模式(`load → show → load → show`) 推荐采用。
{% endhint %}
{% hint style="info" %}
**在 iOS 上无法加载吗？**
如果 iOS 上广告无法加载 **应用跟踪透明度（App Tracking Transparency）** 请检查设置。在未允许应用跟踪的状态下，部分广告加载可能无法正常工作。
{% endhint %}
**参数**
* **params** · 必填 · `LoadFullScreenAdParams`
这是预加载广告时使用的配置对象。可设置广告组 ID 和广告加载事件/错误回调。
* **params.options** · 必填 · `LoadFullScreenAdOptions`
这是加载广告时传递的选项对象。
* **params.options.adGroupId** · 必填 · `string`
是广告组 ID。需要输入在控制台中发放的 ID。
* **params.onEvent** · `(event: LoadFullScreenAdEvent) => void`
这是接收广告加载过程中发生事件的回调。可接收广告加载成功等多种事件。
* **params.onError** · `(error: unknown) => void`
广告加载失败时调用。原因可能是网络错误或当前环境不支持等。
**属性**
**`isSupported`**
{% code collapsedlinecount="10" %}
```typescript
loadFullScreenAd.isSupported(): boolean
```
{% endcode %}
确认当前环境是否可以使用 In-app 广告 2.0 ver2。
**示例**
{% tabs %}
{% tab title="tsx\[React]" %}
{% code collapsedlinecount="10" %}
```tsx
import { loadFullScreenAd } from '@apps-in-toss/web-framework';
import { useState, useEffect } from 'react';
function AdComponent() {
const [isAdLoaded, setIsAdLoaded] = useState(false);
useEffect(() => {
// 检查支持情况
if (!loadFullScreenAd.isSupported()) {
console.warn('无法使用广告功能。');
return;
}
// 加载广告
const unregister = loadFullScreenAd({
options: {
adGroupId: 'ait.dev.43daa14da3ae487b',
},
onEvent: (event) => {
if (event.type === 'loaded') {
console.log('广告加载完成');
setIsAdLoaded(true);
}
},
onError: (error) => {
console.error('广告加载失败：', error);
},
});
// 清理
return () => unregister();
}, []);
return (
{isAdLoaded ? '查看广告' : '广告加载中...'}
);
}
```
{% endcode %}
{% endtab %}
{% tab title="React Native" %}
{% code collapsedlinecount="10" %}
```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(() => {
// 检查支持情况
if (!loadFullScreenAd.isSupported()) {
Alert.alert('无法使用广告功能。');
return;
}
// 加载广告
const unregister = loadFullScreenAd({
options: {
adGroupId: 'ait.dev.43daa14da3ae487b',
},
onEvent: (event) => {
if (event.type === 'loaded') {
Alert.alert('广告加载完成');
setIsAdLoaded(true);
}
},
onError: (error) => {
Alert.alert('广告加载失败', String(error));
},
});
// 清理
return () => unregister();
}, []);
return (
);
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
**`LoadFullScreenAdParams`**
{% code collapsedlinecount="10" %}
```typescript
interface LoadFullScreenAdParams {
options: LoadFullScreenAdOptions;
onEvent: (data: LoadFullScreenAdEvent) => void;
onError: (err: unknown) => void;
}
```
{% endcode %}
`loadFullScreenAd`的参数类型。
**`LoadFullScreenAdOptions`**
{% code collapsedlinecount="10" %}
```typescript
interface LoadFullScreenAdOptions {
adGroupId: string;
}
```
{% endcode %}
广告加载选项。
**`LoadFullScreenAdEvent`**
{% code collapsedlinecount="10" %}
```typescript
interface LoadFullScreenAdEvent {
type: 'loaded';
}
```
{% endcode %}
这是广告加载事件。广告成功加载后会发生 loaded 类型事件。 `loaded` 类型事件会发生。
***
### 展示广告
**SDK 函数：** `showFullScreenAd`
{% code collapsedlinecount="10" %}
```typescript
function showFullScreenAd(params: ShowFullScreenAdParams): () => void;
```
{% endcode %}
将已加载的广告显示到屏幕上。 `loadFullScreenAd`请使用预先加载的广告。
**参数**
* **params.options** · 必填 · `ShowFullScreenAdOptions`
这是展示广告时传递的选项。
* **params.options.adGroupId** · 必填 · `string`
是广告组 ID。必须与 \`loadFullScreenAd\` 中使用的 ID 相同。
* **params.onEvent** · 必填 · `(event: ShowFullScreenAdEvent) => void`
这是接收广告展示过程中发生事件的回调。可接收广告曝光、点击、奖励发放等多种事件。
* **params.onError** · 必填 · `(error: unknown) => void`
广告展示请求失败时调用的回调。
**属性**
**`isSupported`**
{% code collapsedlinecount="10" %}
```typescript
showFullScreenAd.isSupported(): boolean
```
{% endcode %}
确认当前环境是否可使用集成广告。
**示例**
{% tabs %}
{% tab title="tsx\[React]" %}
{% code collapsedlinecount="10" %}
```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(() => {
// 组件挂载时加载广告
const unregister = loadFullScreenAd({
options: { adGroupId: AD_GROUP_ID },
onEvent: (event) => {
if (event.type === 'loaded') {
setIsAdLoaded(true);
}
},
onError: (error) => {
console.error('广告加载失败：', error);
},
});
return () => unregister();
}, []);
const handleShowAd = () => {
showFullScreenAd({
options: { adGroupId: AD_GROUP_ID },
onEvent: (event) => {
switch (event.type) {
case 'requested':
console.log('广告展示请求已发出');
break;
case 'show':
console.log('广告画面已显示');
break;
case 'impression':
console.log('广告曝光已记录（产生收益）');
break;
case 'clicked':
console.log('广告已点击');
break;
case 'dismissed':
console.log('广告已关闭');
setIsAdLoaded(false);
// 加载下一条广告
loadNextAd();
break;
case 'failedToShow':
console.error('广告显示失败');
break;
case 'userEarnedReward':
console.log('获得奖励：', event.data);
// 向用户发放奖励
grantReward(event.data.unitType, event.data.unitAmount);
break;
}
},
onError: (error) => {
console.error('广告显示失败：', 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) => {
// 奖励发放逻辑
console.log(`${unitType} ${unitAmount}个发放`);
};
return (
查看广告
);
}
```
{% endcode %}
{% endtab %}
{% tab title="React Native" %}
{% code collapsedlinecount="10" %}
```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(() => {
// 组件挂载时加载广告
const unregister = loadFullScreenAd({
options: { adGroupId: AD_GROUP_ID },
onEvent: (event) => {
if (event.type === 'loaded') {
setIsAdLoaded(true);
}
},
onError: (error) => {
Alert.alert('广告加载失败', String(error));
},
});
return () => unregister();
}, []);
const handleShowAd = () => {
showFullScreenAd({
options: { adGroupId: AD_GROUP_ID },
onEvent: (event) => {
switch (event.type) {
case 'requested':
console.log('广告展示请求已发出');
break;
case 'show':
console.log('广告画面已显示');
break;
case 'impression':
console.log('广告曝光已记录（产生收益）');
break;
case 'clicked':
console.log('广告已点击');
break;
case 'dismissed':
setIsAdLoaded(false);
loadNextAd();
break;
case 'failedToShow':
Alert.alert('广告显示失败');
break;
case 'userEarnedReward':
console.log('获得奖励：', event.data);
grantReward(event.data.unitType, event.data.unitAmount);
break;
}
},
onError: (error) => {
Alert.alert('广告显示失败', String(error));
},
});
};
const loadNextAd = () => {
loadFullScreenAd({
options: { adGroupId: AD_GROUP_ID },
onEvent: (event) => {
if (event.type === 'loaded') setIsAdLoaded(true);
},
onError: (error) => Alert.alert('错误', String(error)),
});
};
const grantReward = (unitType: string, unitAmount: number) => {
Alert.alert('获得奖励', `${unitType} ${unitAmount}个已发放。`);
};
return (
);
}
```
{% endcode %}
{% endtab %}
{% endtabs %}
**`ShowFullScreenAdParams`**
{% code collapsedlinecount="10" %}
```typescript
interface ShowFullScreenAdParams {
options: ShowFullScreenAdOptions;
onEvent: (data: ShowFullScreenAdEvent) => void;
onError: (err: unknown) => void;
}
```
{% endcode %}
`showFullScreenAd`的参数类型。
**`ShowFullScreenAdOptions`**
{% code collapsedlinecount="10" %}
```typescript
interface ShowFullScreenAdOptions {
adGroupId: string;
}
```
{% endcode %}
这是展示广告的选项。
**`ShowFullScreenAdEvent`**
{% code collapsedlinecount="10" %}
```typescript
type ShowFullScreenAdEvent =
| { type: 'requested' }
| { type: 'show' }
| { type: 'impression' }
| { type: 'clicked' }
| { type: 'dismissed' }
| { type: 'failedToShow' }
| { type: 'userEarnedReward'; data: { unitType: string; unitAmount: number } };
```
{% endcode %}
这是广告展示事件。
**事件说明**
| 事件类型 | 说明 |
| ------------------ | --------------------------------------------------------------------------- |
| `requested` | 广告展示请求成功。 |
| `show` | 广告已显示在屏幕上。 |
| `impression` | 广告曝光已记录。（产生收益时点） |
| `clicked` | 用户点击了广告。 |
| `dismissed` | 用户关闭了广告。 |
| `failedToShow` | 广告显示失败。 |
| `userEarnedReward` | 用户在奖励广告中获得了奖励。• `data.unitType`：奖励类型（例如：coin、point）• `data.unitAmount`：奖励数量 |
***
### 使用指南
**广告加载时机**
建议在展示前预先加载广告。
* 推荐加载时机列表
* 组件挂载时
* 上一个广告关闭后立即
* 切换到展示广告的页面之前
{% code collapsedlinecount="10" %}
```tsx
// ✅ 好例子：进入页面时预加载
useEffect(() => {
loadFullScreenAd({
/* ... */
});
}, []);
// ❌ 坏例子：点击按钮时加载（会产生用户等待时间）
const handleClick = () => {
loadFullScreenAd({
/* ... */
}); // 产生加载时间
showFullScreenAd({
/* ... */
});
};
```
{% endcode %}
**奖励广告处理**
`userEarnedReward` 请仅在事件发生时发放奖励。 `dismissed`不能仅凭此发放。
{% code collapsedlinecount="10" %}
```tsx
showFullScreenAd({
options: { adGroupId: REWARDED_AD_ID },
onEvent: (event) => {
if (event.type === 'userEarnedReward') {
// ✅ 发放奖励
grantReward(event.data);
}
if (event.type === 'dismissed') {
// ❌ 不能仅凭 dismissed 发放奖励
}
},
onError: console.error,
});
```
{% endcode %}
**内存管理**
组件卸载时解除回调注册，以防止内存泄漏。
{% code collapsedlinecount="10" %}
```tsx
useEffect(() => {
const unregister = loadFullScreenAd({
/* ... */
});
return () => {
unregister(); // 清理
};
}, []);
```
{% endcode %}
**错误处理**
始终 `onError` 请提供回调，以应对广告加载/显示失败。
{% code collapsedlinecount="10" %}
```tsx
loadFullScreenAd({
options: { adGroupId: AD_GROUP_ID },
onEvent: (event) => {
/* ... */
},
onError: (error) => {
console.error('广告加载失败：', error);
// 向用户提供适当反馈或重试
},
});
```
{% endcode %}
***
### 事件流程
{% tabs %}
{% tab title="插屏广告 (Interstitial)" %}
{% code collapsedlinecount="10" %}
```
调用 loadFullScreenAd
↓
发生 loaded 事件
↓
调用 showFullScreenAd
↓
发生 requested 事件
↓
发生 show 事件（广告画面显示）
↓
发生 impression 事件（产生收益）
↓
clicked 事件（点击时）或 dismissed 事件（关闭时）
```
{% endcode %}
{% endtab %}
{% tab title="奖励广告 (Rewarded)" %}
{% code collapsedlinecount="10" %}
```
调用 loadFullScreenAd
↓
发生 loaded 事件
↓
调用 showFullScreenAd
↓
发生 requested 事件
↓
发生 show 事件（广告画面显示）
↓
发生 impression 事件（产生收益）
↓
[用户观看完广告]
↓
发生 userEarnedReward 事件（发放奖励）
↓
发生 dismissed 事件（关闭广告）
```
{% endcode %}
{% endtab %}
{% endtabs %}
### 广告政策
以“推荐服务”、“金融小贴士”等名义伪装广告 擅自更改 Toss Ads 指南之外广告单元的颜色·字体 擅自修改广告的标题·标签·CTA 文案及设计 将广告放置在用户交互元素（按钮、游戏区域等）附近，使其产生非故意点击的结构 在同一页面放置 2 个以上相同格式的广告 让用户难以正常关闭页面或返回上一页面的死胡同（Dead-end）结构 将广告与服务 CTA 的功能设计得难以让用户区分的结构 将正常使用服务所需的 CTA 设计得难以识别或访问的结构
广告必须保持 "Ad" 标识 所有广告 UI 都必须使用 web-base 标准组件 禁止以 UI/UX 设计人为诱导广告效果或损害用户体验 SDK Click / Impression 事件篡改 不通过广告 SDK，使用自有逻辑调用广告或绕过 SDK 事件进行实现的情况 阻止或异常控制 Back 按钮，从而妨碍用户正常关闭页面或返回上一页面的情况
禁止篡改 SDK 默认事件（Click / Impression）结构 不可调用 SDK 外部 API 定期刷新广告区域 人为制造效果（点击·曝光等）的活动 若确认基于流量质量的异常模式，将限制广告、进行制裁并暂缓结算 禁止将广告消费与奖励直接挂钩的结构 禁止联动点击奖励性文案·活动 • 透明广告
• 在其他卡片 UI 后插入广告 DOM
| • 广告必须能够明确确认其曝光状态 |
***
#### **UX / 产品原则 运营原则**
广告也应遵循 Toss 的 UX 原则。
| **Toss 原则** | **适用标准** | **示例** |
| ---------------- | -------------------------- | --------------------- |
| **简洁** | 广告应清晰明了，无需额外说明也能理解其含义 | “立即查看”、“查看广告”等明确的 CTA |
| **明确操作** | 用户应能预判点击广告后会发生什么动作 | 跳转到外部时提供提示文案 |
| **无欺骗（UX 红线规则）** | 广告不应在意料之外的时机、形式、位置出现，或误导用户 | 将广告伪装成内容的情况 |
| **价值优先** | 广告不应妨碍客户的服务目标 | 禁止在支付/开户流程中插入广告 |
#### **使用限制及制裁措施**
若 Apps in Toss 广告版位或服务违反本政策，可能会受到制裁。
***
**限制流程**
原则上，限制措施会根据违规行为的累计程度分阶段适用。不过，根据违规类型或严重程度，即使单次违规也可能立即适用 30 天使用限制或永久使用限制。
※ 同时确认的违规不论违规槽位数量，均按 1 次违规处理。之后如另行确认违规，则违规次数累计。
“This feature is not supported in the current environment” 错误会出现
1. 请确认是否在 Toss应用环境中运行。
2. 请确认应用版本是否满足要求。
3. `isSupported()` 请先通过方法确认是否支持。
广告没有加载
1. 请确认 adGroupId（在控制台中获取的 ID）是否正确。
2. 请检查网络连接状态。
3. `onError` 请查看回调中的消息。
4. 在开发环境中请使用测试用 adGroupId。（例如： `ait.dev.43daa14da3ae487b`)
调用广告加载函数后，事件通常会在几秒内到达吗？
所需时间会因展示哪个网络的广告而不同。
{% code collapsedlinecount="10" %}
```
**Toss Ads**：通常会在 1～2 秒内加载完成。根据网络状况，最多可能需要 10 秒。
**Google AdMob**：一般需要约 5～20 秒，也可能更久。受用户网络状况影响较大，最多可能延迟到网络超时时间 60 秒。
```
{% endcode %}
由于 SDK 会根据环境自动决定选择哪个网络，因此建议在进入展示广告的页面之前提前加载。
调用 showFullScreenAd 后广告没有显示
1. `loadFullScreenAd`请先调用 `loaded` 并确认是否收到了事件。
2. 请确认是否使用了相同的 adGroupId。
3. 已展示过的广告无法再次展示，因此需要重新加载。
4. `failedToShow` 事件或 `onError` 请在回调中确认错误。
奖励没有发放
1. `userEarnedReward` 请确认事件是否发生。
2. 请确认用户是否完整观看了广告。（中途关闭则不会发放奖励）
3. `event.data`中 `unitType`和 `unitAmount`请确认。
dismissed 事件没有发生
在 Android Toss应用 5.255.0 版本中 `dismissed` 该事件不会发生。除此版本外可正常运行。
广告加载事件偶尔不会传递
在 Android Toss应用 5.266.0 版本中，调用广告加载函数后，在收到事件之前再次调用加载时，针对后续调用的事件会偶尔无法传递。
虽然通过回滚服务器逻辑解决了问题，但若偶尔残留缓存导致同样现象再次发生，用户可能需要结束 Toss应用进程后重新启动。
在该问题存在期间，需要应用以下指南。
广告组 ID 请务必一次只顺序加载 1 个。在迷你应用中同时加载多个广告组 ID 不会被正常处理。全屏/奖励广告需要分别加载。（例如：加载全屏广告组 ID → 接收事件 → 加载奖励广告组 ID → 接收事件 → 展示）请在调用广告加载函数并收到事件后，再调用广告展示函数。横幅广告不适用。
从 Android 5.267.0 版本开始，上述问题已得到改善，不再需要重新启动 Toss应用，并且已修改为可在一个迷你应用中预先加载多个全屏广告实例。
loaded 事件没有发生
在 Android 5.266.0 及以上版本中，同时加载全屏/奖励广告和横幅广告时，全屏/奖励广告的事件不会传递。
在该问题存在期间，需要应用以下指南。
广告组 ID 请务必一次只顺序加载 1 个。在迷你应用中同时加载多个广告组 ID 不会被正常处理。全屏/奖励/横幅广告需要分别加载。（例如：加载全屏广告组 ID → 接收事件 → 加载横幅 ID → 接收事件 → 展示）请在调用广告加载函数并收到事件后，再调用广告展示函数。
从 Android 5.268.0 版本开始将得到改善。
沙盒中无法使用应用内广告功能
沙盒不支持应用内广告功能。
很抱歉给您带来不便，请通过控制台内的二维码进行测试。
---
# 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-zh/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.
