> 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/rn-banner.md). # 应用内广告 - 横幅广告（React Native） 服务介绍和控制台设置方法请参考 [应用内广告介绍文档](https://developers-apps-in-toss.toss.im/guide/monetization/in-app-ad)。 在 React Native 中， `TossAds.attachBanner` 改为 `InlineAd` 使用组件渲染横幅。 ### 开始使用 `InlineAd`可在 Toss App 5.241.0 及以上版本中使用。 | Toss 应用版本 | 支持情况 | 说明 | | --------------- | ---- | ------------ | | **5.241.0 及以上** | 支持 | 可使用横幅广告 | | **低于 5.241.0** | 不支持 | 无法使用横幅广告 API | {% hint style="info" %} **低于 5.241.0 版本的异常处理** 在 Toss App 5.241.0 以下版本中可能会显示空白页面，请务必做好异常处理。 [获取 Toss App 版本](/documentation/api-and-sdk-zh/common/network-environment/version.md) 请使用功能进行异常处理。 {% endhint %} 在开发阶段使用测试用广告 ID。 | 类型 | 测试 ID | | ----------- | ----------------------------- | | 横幅广告 - 列表型 | `ait-ad-test-banner-id` | | 横幅广告 - 信息流型 | `ait-ad-test-native-image-id` | **快速开始** ```tsx import { InlineAd } from '@apps-in-toss/framework'; export function BannerSection() { return ( 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 App 环境，5.241.0 及以上 | RN `InlineAd` 文档中关于 WebView 横幅广告的 `initialize`, `attachBanner`, `destroyAll`不作为默认路径进行说明。 **属性** ```tsx 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 处理。 | **回调和载荷** ```tsx 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 (用户点击时) ``` **刷新行为** * App/页面 visibility `visible`返回为 visible 时，最后 `IMP_1PX` 之后如果已超过 10 秒，则会重新加载。 **错误处理** * 不支持的环境： `此功能在当前环境中不受支持` * `adGroupId` 缺失/错误的值： `onAdFailedToRender`传入错误载荷 * 无广告： `onNoFill` * 服务器/网络/内部错误： `onAdFailedToRender` ### 曝光与布局 `InlineAd`为了曝光测量， `IOContext.Provider` 使用上下文。以下两种方式中必须满足其一。 | 条件 | 推荐设置 | | ------------------- | ---------------------------------------------- | | 能控制最上层滚动容器 | `@granite-js/react-native`的 `IOScrollView`用…包裹 | | `IOScrollView` 难以应用 | `InlineAd`中 `impressFallbackOnMount={true}` 设置 | **推荐模式： `IOScrollView` 使用** ```tsx import { IOScrollView } from '@granite-js/react-native'; import { InlineAd } from '@apps-in-toss/framework'; export function Screen() { return ( ); } ``` **替代模式：使用 fallback** {% hint style="info" %} **使用 prop** `impressFallbackOnMount` 即使没有 IOScrollView 上下文，prop 也会在 InlineAd 挂载时执行曝光（impression）fallback 逻辑。 {% endhint %} ```tsx import { ScrollView } from 'react-native'; import { InlineAd } from '@apps-in-toss/framework'; export function Screen() { return ( ); } ``` **布局指南** * 固定：宽度 `100%`，高度 `96` 建议 * 内联：宽度 `100%`，未指定高度（内容高度自动） ```tsx import { View } from 'react-native'; import { InlineAd } from '@apps-in-toss/framework'; export function FixedBanner() { return ( ); } export function InlineBanner() { return ( ); } ``` ### 广告政策 #### Toss Ads SSP 政策 请务必遵守以下政策。违规时，广告展示可能会受限。 **即使本政策未明确规定，刻意诱导广告展示、点击、效果，或造成用户误解的行为也可能被视为违反政策。** 如因违反政策而导致服务终止，所有合作方都必须遵守服务终止政策。 | 类型 | 禁止行为 | 具体示例 | 政策标准 | | ---------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | UI/UX 质量下降 | 使广告与内容的区分不清，诱导用户在与其意图无关的情况下消费或点击广告，或以影响正常服务使用的方式构建 UI 的行为 |

|

| | 篡改广告调用行为 | 更改或绕过 SDK 的默认事件流程或广告调用方式的行为 | |

| | 异常流量及效果操纵 | 通过自动化或人为方式扭曲流量及广告效果的行为 | | | | 奖励·参与型点击引导 | 在广告点击的同时提供奖励或福利的行为 | | | | 隐藏广告或重叠 | 故意隐藏广告或被其他 UI 元素遮挡，使用户难以明确感知广告存在的行为 |

• 透明广告

• 在其他卡片 UI 后插入广告 DOM

| • 广告的展示状态必须能够清楚确认 | *** #### **UX / Product Principle 运营原则** 广告也应遵循 Toss 的 UX 原则。 | **Toss Principle** | **适用标准** | **示例** | | ------------------------------ | ---------------------- | ---------------------- | | **Simplicity** | 广告应当清晰明了，无需额外说明即可理解其含义 | 使用“立即查看”“查看广告”等明确的 CTA | | **Clear Action** | 用户应能预测点击广告后会发生什么 | 在重定向·新窗口打开时显示提示文案 | | **No Deception (UX Red Rule)** | 广告不应在意外的时机、形式或位置出现 | 禁止在进入服务后立即展示全屏横幅 | | **Value First** | 广告不应妨碍客户的服务目标 | 禁止在支付/开户流程中插入广告 | #### 使用限制及制裁措施 如 App in Toss 广告版位或服务违反本政策，可能会受到制裁。 *** **限制流程** 限制措施原则上会根据违规行为的累积程度分阶段适用。不过，根据违规类型或严重程度，即使单次违规也可能立即适用 30 天使用限制或永久使用限制。 ※ 同时确认的违规，不论违规槽位数量，均按 1 次违规处理。之后若另有违规被确认，违规次数将累计。
*** **不当收益处理** 因政策违规、无效流量或其他不正当方式产生的收益，可能被视为不当收益。 一旦确认不当收益，相关金额可能会被暂缓支付或拒绝支付，且已支付金额也可能同样被追缴。 *** **申诉流程** * 若收到使用限制通知 **可在 30 天内申请申诉**可以。 * 申诉资料可通过 Channel Talk 提交。 * 提交的资料将依据内部标准进行审核，必要时可能会要求补充资料。 * 审核可能需要约 1 个工作周。 * 对于申诉申请 **将重点审查制裁是否适当**，且仅仅修改违规事项或提交防止复发计划，并不能解除制裁。 * 若通过提交的申诉资料确认，不成立作为制裁依据的违规事实，或制裁判断存在明显错误，则制裁可能会被解除。 * 若屡次或严重违规，服务使用可能会被永久限制。 *** **测试** 在开发阶段务必使用测试广告 ID。若使用真实广告 ID 进行测试，可能会被视为违反政策并受到不利影响。RN 横幅广告测试 ID 为 [开始使用](#시작하기)可在此处查看。 发布前请务必确认以下事项。 * 确认广告是否正常加载。 * 确认点击后是否跳转到预期页面。 * 确认返回操作是否正常工作。 * 确认不会干扰支付或认证流程。 *** ### 常见问题
广告不显示 1. 请确认 Toss App 环境及最低版本。 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` 确认事件是否正常采集
沙盒中应用内广告功能无法使用 沙盒中不支持应用内广告功能。 不便之处敬请谅解，请通过控制台内的二维码进行测试。
--- # 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/rn-banner.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.