应用内广告 - 横幅广告(React Native)

服务介绍和控制台设置方法是 应用内广告介绍文档请参考。

在 React Native 中， TossAds.attachBanner 改为 InlineAd 使用组件渲染横幅广告。

开始使用

InlineAd可在 Toss 应用 5.241.0 及以上版本中使用。

Toss 应用版本	是否支持	说明
5.241.0 及以上	支持	可使用横幅广告
低于 5.241.0	不支持	无法使用横幅广告 API

低于 5.241.0 版本的异常处理

在 Toss 应用 5.241.0 以下版本中可能会显示空白页面，请务必做好异常处理。 获取 Toss 应用版本 请使用该功能进行异常处理。

在开发阶段使用测试用广告 ID。

类型	测试 ID
横幅广告 - 列表型	ait-ad-test-banner-id
横幅广告 - 信息流型	ait-ad-test-native-image-id

快速开始

import { InlineAd } from '@apps-in-toss/framework';

export function BannerSection() {
  return (
    <InlineAd
      adGroupId="ait-ad-test-banner-id"
      theme="auto"
      tone="blackAndWhite"
      variant="expanded"
      onAdRendered={(payload) => console.log('onAdRendered', payload)}
      onAdImpression={(payload) => console.log('onAdImpression', payload)}
      onAdViewable={(payload) => console.log('onAdViewable', payload)}
      onAdClicked={(payload) => console.log('onAdClicked', payload)}
      onNoFill={(payload) => console.log('onNoFill', payload)}
      onAdFailedToRender={(payload) => console.log('onAdFailedToRender', payload)}
    />
  );
}

API 参考

概述

项目	值
包	@apps-in-toss/framework
主要 API	InlineAd 组件
前提	Toss 应用环境，5.241.0 及以上

RN InlineAd 文档中不会将 WebView 横幅广告的 initialize, attachBanner, destroyAll作为默认路径进行说明。

Props

type InlineAdTheme = 'auto' | 'light' | 'dark';
type InlineAdTone = 'blackAndWhite' | 'grey';
type InlineAdVariant = 'expanded' | 'card';

interface InlineAdProps {
  adGroupId: string;
  theme?: InlineAdTheme;
  tone?: InlineAdTone;
  variant?: InlineAdVariant;
  impressFallbackOnMount?: boolean;
}

属性	类型	说明
adGroupId	string	这是必填值。请传入在控制台获取的广告组 ID。
theme	InlineAdTheme	默认值为 auto。
tone	InlineAdTone	默认值为 blackAndWhite。
variant	InlineAdVariant	默认值为 expanded。
impressFallbackOnMount	boolean	IOScrollView在难以使用时，开启曝光事件的 fallback 处理。

回调与负载

interface BannerSlotEventPayload {
  slotId: string;
  adGroupId: string;
  adMetadata: {
    creativeId: string;
    requestId: string;
    styleId: string;
  };
}

interface BannerSlotErrorPayload {
  slotId: string;
  adGroupId: string;
  adMetadata: {};
  error: {
    code: number;
    message: string;
    domain?: string;
  };
}

回调	发生时点
onAdRendered	广告数据变为可渲染状态后立即触发。
onAdImpression	IMP_1PX 该时点以收益事件为基准。
onAdViewable	曝光超过 50% 的状态持续 1 秒时触发。
onAdClicked	用户点击广告区域时触发。
onNoFill	当没有广告库存时调用。
onAdFailedToRender	渲染失败、不支持当前环境、参数错误。

事件流程

InlineAd 挂载或 adGroupId 变更
↓
广告加载(loadAd)
↓
onAdRendered
↓
onAdImpression (IMP_1PX)
↓
onAdViewable (50% 曝光 + 持续 1 秒)
↓
onAdClicked (用户点击时)

刷新行为

• 当应用/屏幕 visibility visible恢复为时，距离上一次 IMP_1PX 之后已超过 10 秒，则会重新加载。

错误处理

• 不支持的环境： This feature is not supported in the current environment
• adGroupId 缺失/错误值： onAdFailedToRender传递错误 payload
• 无广告： onNoFill
• 服务器/网络/内部错误： onAdFailedToRender

曝光与布局

InlineAd为了进行曝光测量， IOContext.Provider 会使用该上下文。以下两项中必须满足其中一项。

条件	推荐设置
可以控制最外层滚动容器	@granite-js/react-native中 IOScrollView包裹
IOScrollView 难以应用	InlineAd中 impressFallbackOnMount={true} 设置

推荐模式： IOScrollView 使用

import { IOScrollView } from '@granite-js/react-native';
import { InlineAd } from '@apps-in-toss/framework';

export function Screen() {
  return (
    <IOScrollView>
      <InlineAd adGroupId="ait-ad-test-banner-id" />
    </IOScrollView>
  );
}

替代模式：使用 fallback

使用 prop

impressFallbackOnMount 即使没有 IOScrollView 上下文，prop 也会在 InlineAd 挂载时执行曝光（impression）fallback 逻辑。

import { ScrollView } from 'react-native';
import { InlineAd } from '@apps-in-toss/framework';

export function Screen() {
  return (
    <ScrollView>
      <InlineAd adGroupId="ait-ad-test-banner-id" impressFallbackOnMount={true} />
    </ScrollView>
  );
}

布局指南

• 固定型：宽度 100%，高度 96 推荐
• 内联型：宽度 100%，不指定高度（内容高度自动）

import { View } from 'react-native';
import { InlineAd } from '@apps-in-toss/framework';

export function FixedBanner() {
  return (
    <View style={{ width: '100%', height: 96, overflow: 'hidden' }} >
      <InlineAd adGroupId="ait-ad-test-banner-id" />
    </View>
  );
}

export function InlineBanner() {
  return (
    <View style={{ width: '100%' }} >
      <InlineAd adGroupId="ait-ad-test-banner-id" />
    </View>
  );
}

广告政策

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 / Product Principle 运营原则

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

Toss Principle	适用标准	示例
Simplicity	广告应当清晰明确，且无需额外说明也能理解其含义	使用“立即查看”、“查看广告”等明确 CTA
Clear Action	用户应能预测点击广告后会发生什么行为	在重定向·跳转新窗口时显示告知文案
No Deception (UX Red Rule)	广告不应在意料之外的时机、形式或位置出现	禁止在进入服务后立即展示全屏横幅
Value First	广告不应妨碍客户的服务目标	禁止在支付/开户流程中插入广告

使用限制及制裁措施

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

---

限制流程

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

※ 同时确认的违规，无论违规槽位数量多少，都按 1 次违规处理。此后如另行确认违规，违规次数将累计。

---

不当收益处理

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

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

---

申诉流程

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

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

  • 审核可能需要约 1 个工作周。
  • 对于申诉申请 会重点审查处罚是否适当，仅因已修正违规事项或提交防止再发计划，并不会解除处罚。
  • 若通过提交的申诉资料确认，构成处罚依据的违规事实不成立，或处罚判断存在明显错误，则处罚可能会被解除。
• 对于重复或重大违规，服务使用可能会被永久限制。

---

测试

在开发阶段务必使用测试广告 ID。使用真实广告 ID 测试会被视为违反政策，可能会受到不利影响。RN 横幅广告测试 ID 为 开始使用可在其中确认。

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

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

---

常见问题

广告未显示

1. 请确认 Toss 应用环境及最低版本。
2. adGroupId请确认其是否有效。
3. onNoFill() 或 onAdFailedToRender 请检查 payload。

回调顺序看起来与文档不同

onAdImpression表示 1px 曝光时点， onAdViewable表示 50%+1 秒时点。

现有 Web API(TossAds.initialize/attachBanner/destroyAll)可以在 RN 中直接使用吗？

在 RN InlineAd 路径中，不会将该 API 作为默认路径进行说明。RN 请 InlineAd 以组件为中心使用。

会发生“ImpressionArea 在 IOContext.Provider 之外使用了”错误

1. 最外层滚动组件 @granite-js/react-native中 IOScrollView是否确认
2. IOScrollView 如果难以应用 InlineAd中 impressFallbackOnMount={true} 设置
3. 应用后 onAdImpression 确认事件是否正常采集

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

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

很抱歉，请通过控制台内的二维码进行测试。