应用内广告 - 插屏/激励广告

服务介绍和控制台设置方法请参考 In-app 广告介绍文档。

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

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

会预先加载广告。显示广告前必须调用。

若要稳定运营，请这样实现

• 请按页面（或屏幕）维度预先加载广告。
• 广告必须 load → show → (下一次 load) 按该顺序调用。
• loadFullScreenAd 调用后 收到事件后 showFullScreenAd才能调用。
• 若 adGroupId 相同，一次只能预加载一个广告。
• 若使用多个 adGroupId，则可分别为每个 adGroupId 预加载一个广告。
• 在展示广告后预先加载下一条广告的模式(load → show → load → show) 推荐采用。

在 iOS 上无法加载吗？

如果 iOS 上广告无法加载 应用跟踪透明度（App Tracking Transparency） 请检查设置。在未允许应用跟踪的状态下，部分广告加载可能无法正常工作。

参数

• params · 必填 · LoadFullScreenAdParams

  这是预加载广告时使用的配置对象。可设置广告组 ID 和广告加载事件/错误回调。

  • params.options · 必填 · LoadFullScreenAdOptions

    这是加载广告时传递的选项对象。

    • params.options.adGroupId · 必填 · string

      是广告组 ID。需要输入在控制台中发放的 ID。
  • params.onEvent · (event: LoadFullScreenAdEvent) => void

    这是接收广告加载过程中发生事件的回调。可接收广告加载成功等多种事件。
  • params.onError · (error: unknown) => void

    广告加载失败时调用。原因可能是网络错误或当前环境不支持等。

属性

isSupported

loadFullScreenAd.isSupported(): boolean

确认当前环境是否可以使用 In-app 广告 2.0 ver2。

示例

tsx[React]

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 (
    <button disabled={!isAdLoaded}>
      {isAdLoaded ? '查看广告' : '广告加载中...'}
    </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(() => {
    // 检查支持情况
    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 (
    <View>
      <Button
        title={isAdLoaded ? '查看广告' : '广告加载中...'}
        disabled={!isAdLoaded}
      />
    </View>
  );
}

LoadFullScreenAdParams

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

loadFullScreenAd的参数类型。

LoadFullScreenAdOptions

interface LoadFullScreenAdOptions {
  adGroupId: string;
}

广告加载选项。

LoadFullScreenAdEvent

interface LoadFullScreenAdEvent {
  type: 'loaded';
}

这是广告加载事件。广告成功加载后会发生 loaded 类型事件。 loaded 类型事件会发生。

---

展示广告

SDK 函数： showFullScreenAd

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

将已加载的广告显示到屏幕上。 loadFullScreenAd请使用预先加载的广告。

参数

• params.options · 必填 · ShowFullScreenAdOptions

  这是展示广告时传递的选项。

  • params.options.adGroupId · 必填 · string

    是广告组 ID。必须与 `loadFullScreenAd` 中使用的 ID 相同。
• params.onEvent · 必填 · (event: ShowFullScreenAdEvent) => void

  这是接收广告展示过程中发生事件的回调。可接收广告曝光、点击、奖励发放等多种事件。
• params.onError · 必填 · (error: unknown) => void

  广告展示请求失败时调用的回调。

属性

isSupported

showFullScreenAd.isSupported(): boolean

确认当前环境是否可使用集成广告。

示例

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(() => {
    // 组件挂载时加载广告
    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 (
    <button onClick={handleShowAd} disabled={!isAdLoaded}>
      查看广告
    </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(() => {
    // 组件挂载时加载广告
    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 (
    <View>
      <Button title="查看广告" onPress={handleShowAd} disabled={!isAdLoaded} />
    </View>
  );
}

ShowFullScreenAdParams

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

showFullScreenAd的参数类型。

ShowFullScreenAdOptions

interface ShowFullScreenAdOptions {
  adGroupId: string;
}

这是展示广告的选项。

ShowFullScreenAdEvent

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

这是广告展示事件。

事件说明

事件类型	说明
requested	广告展示请求成功。
show	广告已显示在屏幕上。
impression	广告曝光已记录。（产生收益时点）
clicked	用户点击了广告。
dismissed	用户关闭了广告。
failedToShow	广告显示失败。
userEarnedReward	用户在奖励广告中获得了奖励。• data.unitType：奖励类型（例如：coin、point）• data.unitAmount：奖励数量

---

使用指南

广告加载时机

建议在展示前预先加载广告。

• 推荐加载时机列表

  • 组件挂载时
  • 上一个广告关闭后立即
  • 切换到展示广告的页面之前

// ✅ 好例子：进入页面时预加载
useEffect(() => {
  loadFullScreenAd({
    /* ... */
  });
}, []);

// ❌ 坏例子：点击按钮时加载（会产生用户等待时间）
const handleClick = () => {
  loadFullScreenAd({
    /* ... */
  }); // 产生加载时间
  showFullScreenAd({
    /* ... */
  });
};

奖励广告处理

userEarnedReward 请仅在事件发生时发放奖励。 dismissed不能仅凭此发放。

showFullScreenAd({
  options: { adGroupId: REWARDED_AD_ID },
  onEvent: (event) => {
    if (event.type === 'userEarnedReward') {
      // ✅ 发放奖励
      grantReward(event.data);
    }

    if (event.type === 'dismissed') {
      // ❌ 不能仅凭 dismissed 发放奖励
    }
  },
  onError: console.error,
});

内存管理

组件卸载时解除回调注册，以防止内存泄漏。

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

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

错误处理

始终 onError 请提供回调，以应对广告加载/显示失败。

loadFullScreenAd({
  options: { adGroupId: AD_GROUP_ID },
  onEvent: (event) => {
    /* ... */
  },
  onError: (error) => {
    console.error('广告加载失败：', error);
    // 向用户提供适当反馈或重试
  },
});

---

事件流程

插屏广告 (Interstitial)

调用 loadFullScreenAd
  ↓
发生 loaded 事件
  ↓
调用 showFullScreenAd
  ↓
发生 requested 事件
  ↓
发生 show 事件（广告画面显示）
  ↓
发生 impression 事件（产生收益）
  ↓
clicked 事件（点击时）或 dismissed 事件（关闭时）

奖励广告 (Rewarded)

调用 loadFullScreenAd
  ↓
发生 loaded 事件
  ↓
调用 showFullScreenAd
  ↓
发生 requested 事件
  ↓
发生 show 事件（广告画面显示）
  ↓
发生 impression 事件（产生收益）
  ↓
[用户观看完广告]
  ↓
发生 userEarnedReward 事件（发放奖励）
  ↓
发生 dismissed 事件（关闭广告）

广告政策

Toss Ads SSP 政策

请务必遵守以下政策。若违反，广告展示可能会受限。

即使本政策未明示，若人为诱导广告曝光、点击、效果，或造成用户误解，也可能被视为违反政策。

所有合作方如因违反政策而导致服务终止，均需遵守服务终止政策。

类型	禁止行为	具体示例	政策标准
UI/UX 质量下降	使广告与内容的区分不明确，或诱导与用户意图无关的广告消费/点击，或通过 UI 结构妨碍正常服务使用	以“推荐服务”、“金融小贴士”等名义伪装广告 擅自更改 Toss Ads 指南之外广告单元的颜色·字体 擅自修改广告的标题·标签·CTA 文案及设计 将广告放置在用户交互元素（按钮、游戏区域等）附近，使其产生非故意点击的结构 在同一页面放置 2 个以上相同格式的广告 让用户难以正常关闭页面或返回上一页面的死胡同（Dead-end）结构 将广告与服务 CTA 的功能设计得难以让用户区分的结构 将正常使用服务所需的 CTA 设计得难以识别或访问的结构	广告必须保持 "Ad" 标识 所有广告 UI 都必须使用 web-base 标准组件 禁止以 UI/UX 设计人为诱导广告效果或损害用户体验
篡改广告调用行为	修改或绕过 SDK 的默认事件流程或广告调用方式的行为	SDK Click / Impression 事件篡改 不通过广告 SDK，使用自有逻辑调用广告或绕过 SDK 事件进行实现的情况 阻止或异常控制 Back 按钮，从而妨碍用户正常关闭页面或返回上一页面的情况	禁止篡改 SDK 默认事件（Click / Impression）结构 不可调用 SDK 外部 API
异常流量及效果操纵	通过自动化或人为方式扭曲流量及广告效果的行为	定期刷新广告区域 人为制造效果（点击·曝光等）的活动	若确认基于流量质量的异常模式，将限制广告、进行制裁并暂缓结算
奖励·参与型点击引导	在广告点击的同时提供奖励或优惠的行为	“点击广告立即发放奖励” “点击广告即可获得积分”	禁止将广告消费与奖励直接挂钩的结构 禁止联动点击奖励性文案·活动
广告隐藏或重叠	故意隐藏广告或被其他 UI 元素遮挡，使用户难以明确识别广告存在的行为	• 透明广告 • 在其他卡片 UI 后插入广告 DOM	• 广告必须能够明确确认其曝光状态

---

UX / 产品原则 运营原则

广告也应遵循 Toss 的 UX 原则。

Toss 原则	适用标准	示例
简洁	广告应清晰明了，无需额外说明也能理解其含义	“立即查看”、“查看广告”等明确的 CTA
明确操作	用户应能预判点击广告后会发生什么动作	跳转到外部时提供提示文案
无欺骗（UX 红线规则）	广告不应在意料之外的时机、形式、位置出现，或误导用户	将广告伪装成内容的情况
价值优先	广告不应妨碍客户的服务目标	禁止在支付/开户流程中插入广告

使用限制及制裁措施

若 Apps in Toss 广告版位或服务违反本政策，可能会受到制裁。

---

限制流程

原则上，限制措施会根据违规行为的累计程度分阶段适用。不过，根据违规类型或严重程度，即使单次违规也可能立即适用 30 天使用限制或永久使用限制。

※ 同时确认的违规不论违规槽位数量，均按 1 次违规处理。之后如另行确认违规，则违规次数累计。

---

不当收益处理

通过违反政策、无效流量或其他不正当方式产生的收益，可能会被视为不当收益。

一旦确认存在不当收益，相关金额可能会被暂缓支付或拒绝支付，且已支付金额也可能同样被追回。

---

申诉流程

• 收到使用限制通知时 可在 30 天内提出申诉可以。

  • 申诉资料可通过 Channel Talk 提交。
• 提交的资料将根据内部标准进行审查，必要时可能会要求补充资料。

  • 审查可能需要约 1 个工作周。
  • 关于申诉申请 将以制裁是否适当为重点进行审查，仅仅修正了违规事项或提交了防止再次发生的计划，并不会解除制裁。
  • 如果通过提交的申诉资料确认，作为制裁依据的违规事实不成立，或制裁判断存在明显错误，则制裁可能会被解除。
• 对于重复或严重违规，服务使用可能会被永久限制。

---

测试

在开发阶段，请务必使用测试用广告 ID。如果使用真实广告 ID 进行测试，可能会被视为违反政策并受到不利影响。

• 全屏广告： ait-ad-test-interstitial-id
• 奖励广告： ait-ad-test-rewarded-id
• 横幅广告 - 列表型： ait-ad-test-banner-id
• 横幅广告 - 信息流型： ait-ad-test-native-image-id

上线前请务必确认以下项目。

• 确认广告是否能正常加载。
• 确认点击后是否会跳转到预期页面。
• 确认返回操作是否正常工作。
• 确认不会干扰支付或认证流程。

---

常见问题

“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)

调用广告加载函数后，事件通常会在几秒内到达吗？

所需时间会因展示哪个网络的广告而不同。

**Toss Ads**：通常会在 1～2 秒内加载完成。根据网络状况，最多可能需要 10 秒。
**Google AdMob**：一般需要约 5～20 秒，也可能更久。受用户网络状况影响较大，最多可能延迟到网络超时时间 60 秒。

由于 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 版本开始将得到改善。

沙盒中无法使用应用内广告功能

沙盒不支持应用内广告功能。

很抱歉给您带来不便，请通过控制台内的二维码进行测试。