> 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/rn-banner.md). # In-app Ads - Banner Ads (React Native) For service introduction and console setup instructions, [In-app ad introduction document](https://developers-apps-in-toss.toss.im/guide/monetization/in-app-ad)please refer to. In React Native, `TossAds.attachBanner` instead `InlineAd` Render the banner using the component. ### Get started `InlineAd`Can be used in the Toss app 5.241.0 or later. | Toss app version | Support status | Description | | -------------------- | -------------- | ------------------------- | | **5.241.0 or later** | Supported | Banner ads available | | **Below 5.241.0** | Not supported | Banner ad API unavailable | {% hint style="info" %} **Handling versions below 5.241.0** If used in Toss app versions below 5.241.0, a blank screen may appear, so be sure to handle exceptions. [Get Toss app version](/documentation/api-and-sdk-en/common/network-environment/version.md) Please handle exceptions using the function. {% endhint %} During development, use test ad IDs. | Type | Test ID | | --------------------- | ----------------------------- | | Banner ad - list type | `ait-ad-test-banner-id` | | Banner ad - feed type | `ait-ad-test-native-image-id` | **Quick start** ```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 reference **Overview** | Item | Value | | ------------- | -------------------------------------- | | Package | `@apps-in-toss/framework` | | Key APIs | `InlineAd` Component | | Prerequisites | Toss app environment, 5.241.0 or later | RN `InlineAd` In the documentation, the WebView banner ad `initialize`, `attachBanner`, `destroyAll`is not introduced as the default path. **Props** ```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; } ``` | Prop | Type | Description | | ------------------------ | ----------------- | ------------------------------------------------------------------------------- | | `adGroupId` | `string` | Required. Pass the ad group ID issued from the console. | | `theme` | `InlineAdTheme` | The default value is `auto`. | | `tone` | `InlineAdTone` | The default value is `blackAndWhite`. | | `variant` | `InlineAdVariant` | The default value is `expanded`. | | `impressFallbackOnMount` | `boolean` | `IOScrollView`When it is hard to use, turn on exposure event fallback handling. | **Callbacks and payloads** ```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; }; } ``` | Callback | When it occurs | | -------------------- | --------------------------------------------------------------------------------- | | `onAdRendered` | Right after the ad data becomes renderable. | | `onAdImpression` | `IMP_1PX` This is the timing. It is based on revenue events. | | `onAdViewable` | This is the moment when exposure of 50% or more has been maintained for 1 second. | | `onAdClicked` | This is when the user clicked the ad area. | | `onNoFill` | Called when there is no ad inventory. | | `onAdFailedToRender` | Render failure, unsupported environment, parameter error. | **Event flow** ``` InlineAd mount or adGroupId change ↓ Ad load (loadAd) ↓ onAdRendered ↓ onAdImpression (IMP_1PX) ↓ onAdViewable (50% exposure + 1 second held) ↓ onAdClicked (when the user clicks) ``` **Refresh behavior** * When app/screen visibility `visible`returns, after the last `IMP_1PX` if 10 seconds or more have passed since then, it reloads. **Error handling** * Unsupported environments: `This feature is not supported in the current environment` * `adGroupId` Missing/invalid values: `onAdFailedToRender`Send an error payload to * No ad: `onNoFill` * Server/network/internal errors: `onAdFailedToRender` ### Exposure and layout `InlineAd`is for exposure measurement `IOContext.Provider` The context is used. You must satisfy one of the following two conditions. | Condition | Recommended setting | | ------------------------------------------ | ---------------------------------------------------------- | | Can control the top-level scroll container | `@granite-js/react-native`of `IOScrollView`Wrap with | | `IOScrollView` Difficult to apply | `InlineAd`to `impressFallbackOnMount={true}` Configuration | **Recommended pattern: `IOScrollView` Usage** ```tsx import { IOScrollView } from '@granite-js/react-native'; import { InlineAd } from '@apps-in-toss/framework'; export function Screen() { return ( ); } ``` **Alternative pattern: use fallback** {% hint style="info" %} **Use prop** `impressFallbackOnMount` The prop runs impression fallback logic when InlineAd mounts even without an IOScrollView context. {% endhint %} ```tsx import { ScrollView } from 'react-native'; import { InlineAd } from '@apps-in-toss/framework'; export function Screen() { return ( ); } ``` **Layout guide** * Fixed: width `100%`, height `96` Recommended * Inline: width `100%`, height not specified (content height auto) ```tsx import { View } from 'react-native'; import { InlineAd } from '@apps-in-toss/framework'; export function FixedBanner() { return ( ); } export function InlineBanner() { return ( ); } ``` ### Ad Policy #### Toss Ads SSP Policy Please strictly follow the policy below. Violations may restrict ad exposure. **Even if not specified in this policy, actions that artificially induce ad impressions, clicks, or performance, or mislead users, may be considered policy violations.** All partners must comply with the service termination policy if the service is terminated due to policy violations. | Type | Prohibited actions | Specific examples | Policy criteria | | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | UI/UX degradation | Designing the UI to blur the distinction between ads and content, induce ad consumption or clicks unrelated to user intent, or interfere with normal service use |

|

| | Tampering with ad call behavior | Changing or bypassing the SDK's default event flow or ad call method | |

| | Abnormal traffic and performance manipulation | Distorting traffic and ad performance through automated or artificial methods | | | | Reward-based / engagement-based click prompting | Providing rewards or benefits at the same time as an ad click | | | | Ad hiding or overlap | Intentionally hiding ads or obscuring them with other UI elements so users cannot clearly recognize their presence |

• Transparent ad

• Inserting ad DOM behind another card UI

| • Ads must have a clearly verifiable visible state | *** #### **UX / Product Principle operating guidelines** Ads must also follow Toss's UX principles. | **Toss Principle** | **Application criteria** | **Example** | | ------------------------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | **Simplicity** | Ads must be clear and understandable without additional explanation | Use clear CTAs such as "View now" and "View ad" | | **Clear Action** | Users should be able to predict what action will occur after clicking the ad | Show a disclosure message when redirecting or opening a new window | | **No Deception (UX Red Rule)** | Ads should not appear at unexpected moments, in unexpected forms, or in unexpected locations | No full-screen banner immediately upon entering the service | | **Value First** | Ads should not interfere with the customer's service goals | No ad insertion during payment / account opening flows | #### Usage restrictions and sanctions If an Apps in Toss ad placement or service violates this policy, sanctions may be applied. *** **Restriction procedure** Restrictions are generally applied in stages 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 confirmed at the same time are treated as a single violation regardless of the number of violation slots. If violations are confirmed separately afterward, the violation count accumulates.
*** **Handling of improper revenue** Revenue generated through policy violations, invalid traffic, or other improper means may be considered improper revenue. If improper revenue is confirmed, payment may be withheld or denied for that amount, and amounts already paid may also be recovered. *** **Appeal procedure** * If you receive a notice of usage restriction **Apply for an appeal within 30 days**You can. * Appeal materials can be submitted through Channel Talk. * Submitted materials will be reviewed according to internal standards, and additional materials may be requested if needed. * Review may take about one business week. * Regarding appeal applications **review focusing on whether the sanction was appropriate**and sanctions will not be lifted merely because the violation has been corrected or a recurrence prevention plan has been submitted. * Sanctions may be lifted if the submitted appeal materials show that the violation forming the basis for the sanction is not substantiated, or that there is a clear error in the sanction decision. * In cases of repeated or serious violations, service use may be permanently restricted. *** **Test** During development, be sure to use a test ad ID. Testing with a real ad ID may be considered a policy violation and can result in penalties. The RN banner ad test ID is [Get started](#시작하기)can be found in Please make sure to check the following items before release. * Check whether the ad loads properly. * Check whether clicking takes you to the intended screen. * Check whether the back action works properly. * Check whether it does not interfere with payment or authentication flows. *** ### Frequently asked questions
Ads are not visible 1. Please check the Toss app environment and minimum version. 2. `adGroupId`Please check whether it is valid. 3. `onNoFill()` or `onAdFailedToRender` Please check the payload.
The callback order seems different from the documentation `onAdImpression`is defined as the 1px impression point, `onAdViewable`is defined as the 50%+1 second point.
Can I use the existing web API (TossAds.initialize/attachBanner/destroyAll) as-is in RN? In the RN InlineAd path, that API is not introduced as the default path. RN is `InlineAd` Please use it centered on the component.
"The ImpressionArea was used outside IOContext.Provider" error occurs 1. Top-level scroll component `@granite-js/react-native`of `IOScrollView`check whether it is 2. `IOScrollView` If it is difficult to apply, `InlineAd`to `impressFallbackOnMount={true}` Configuration 3. After applying, `onAdImpression` check whether events are being collected properly
In-app ad functionality does not work in the sandbox In-app ad functionality is not supported in the sandbox. Sorry for the inconvenience, but please proceed with testing 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/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.