> 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, please refer to [In-app Ads Introduction Document](https://developers-apps-in-toss.toss.im/guide/monetization/in-app-ad). In React Native, `TossAds.attachBanner` instead `InlineAd` Render a banner using the component. ### Getting Started `InlineAd`is available in 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" %} **Exception handling for versions below 5.241.0** In Toss app versions below 5.241.0, a blank screen may be shown, so be sure to handle exceptions. [Get Toss app version](/documentation/api-and-sdk-en/common/network-environment/version.md) Use the feature to handle exceptions. {% endhint %} Use test ad IDs during development. | 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` | | Main API | `InlineAd` Component | | Prerequisites | Toss app environment, 5.241.0 or later | RN `InlineAd` In the documentation, for WebView banner ads, `initialize`, `attachBanner`, `destroyAll`we don't guide you to use it 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 value. Pass the ad group ID issued from the console. | | `theme` | `InlineAdTheme` | Default is `auto`It is. | | `tone` | `InlineAdTone` | Default is `blackAndWhite`It is. | | `variant` | `InlineAdVariant` | Default is `expanded`It is. | | `impressFallbackOnMount` | `boolean` | `IOScrollView`Enable fallback handling for impression events when it's difficult to use. | **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 point. It is based on revenue events. | | `onAdViewable` | This is the point when 50% or more visibility has been maintained for 1 second. | | `onAdClicked` | This is when the user clicks the ad area. | | `onNoFill` | Called when there is no ad inventory. | | `onAdFailedToRender` | Render failure, unsupported environment, or parameter error. | **Event Flow** ``` InlineAd mount or adGroupId change ↓ Ad load (loadAd) ↓ onAdRendered ↓ onAdImpression (IMP_1PX) ↓ onAdViewable (50% visibility + 1 second maintained) ↓ onAdClicked (when user clicks) ``` **Refresh behavior** * When app/screen visibility `visible`returns to, and the last `IMP_1PX` if more than 10 seconds have passed since then, it reloads. **Error Handling** * Unsupported environment: `This feature is not supported in the current environment` * `adGroupId` Missing/invalid value: `onAdFailedToRender`Pass the error payload to * No ads: `onNoFill` * Server/network/internal error: `onAdFailedToRender` ### Impression and layout `InlineAd`For impression measurement, `IOContext.Provider` uses the context. You must satisfy one of the following two conditions. | Condition | Recommended setup | | ---------------------------------------------- | ------------------------------------------------------------- | | You can control the top-level scroll container | `@granite-js/react-native`the `IOScrollView`Wrap with | | `IOScrollView` Difficult to apply | `InlineAd`are set to `impressFallbackOnMount={true}` Settings | **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 makes InlineAd perform impression fallback logic when it 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 unspecified (content height auto) ```tsx import { View } from 'react-native'; import { InlineAd } from '@apps-in-toss/framework'; export function FixedBanner() { return ( ); } export function InlineBanner() { return ( ); } ``` ### Advertising policy #### Toss Ads SSP policy Please make sure to follow the policies below. Violations may restrict ad impressions. **Even if not specified in this policy, any act that artificially induces ad impressions, clicks, or performance, or causes user confusion, may be considered a policy violation.** If any partner service is terminated for violating policy, all partners must comply with the service termination policy. | Type | Prohibited actions | Specific examples | Policy criteria | | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Degradation of UI/UX quality | Structuring the UI in a way that blurs the distinction between ads and content, induces ad consumption or clicks unrelated to user intent, or interferes with normal service use |

|

| | Ad call manipulation | Changing or bypassing the SDK's default event flow or ad call method | |

| | Abnormal traffic and performance manipulation | Any act that distorts traffic and ad performance through automation or artificial means | | | | Reward-based / participation-based click inducement | Providing rewards or benefits at the same time as ad clicks | | | | Ad hiding or overlap | Any act of intentionally hiding ads or obscuring them with other UI elements so users cannot clearly recognize the presence of the ads |

• Transparent ads

• Inserting ad DOM behind another card UI

| • Ads must have clearly verifiable visible status | *** #### **UX / Product Principle Operating Guidelines** Ads must also follow Toss's UX principles. | **Toss Principle** | **Application criteria** | **Examples** | | ------------------------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | **Simplicity** | Ads should be clear and understandable without additional explanation | "Use clear CTAs such as \\"View now\\" or \\"View ad\\"" | | **Clear Action** | Users should be able to predict what will happen after clicking the ad | Show notice text 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 | Prohibit full-screen banners immediately after entering the service | | **Value First** | Ads should not interfere with the customer's service goals | Prohibit inserting ads during payment/account opening flows | #### Usage restrictions and sanctions Sanctions may be applied if the App in Toss ad placement or service violates this policy. *** **Restriction procedures** As a rule, restrictions are applied step by step 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 identified at the same time are treated as one violation, regardless of the number of violating slots. If violations are later identified separately, the number of violations accumulates.
*** **Handling of unjust gains** Revenue generated through policy violations, invalid traffic, or other fraudulent means may be considered unjust gains. If unjust gains are identified, payment for the amount may be withheld or denied, and any amount already paid may also be recovered in the same way. *** **Appeal procedure** * If you have received a notice of usage restriction **You may file an appeal within 30 days**You can. * Appeal materials can be submitted via Channel Talk. * Submitted materials are reviewed according to internal criteria, and additional materials may be requested if necessary. * Review may take about one week on business days. * For appeal requests **review focuses on whether the sanction was appropriate**and simply correcting the violation or submitting a recurrence prevention plan will not lift the sanction. * If the submitted appeal materials show that the violation underlying the sanction is not recognized or that there is a clear error in the sanction decision, the sanction may be lifted. * In cases of repeated or serious violations, service use may be permanently restricted. *** **Testing** During development, always 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 [Getting Started](#시작하기)here. Please make sure to check the items below before launch. * Check that the ad loads properly. * Check that clicking takes you to the intended screen. * Check that the back button works properly. * Check that it does not interfere with payment or authentication flows. *** ### Frequently asked questions
The ad isn't showing 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 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 recommended as the default path. For RN, `InlineAd` please use it centered around the component.
The error "ImpressionArea was used outside IOContext.Provider" occurs 1. The top-level scroll component `@granite-js/react-native`the `IOScrollView`check whether it is 2. `IOScrollView` If it's difficult to apply `InlineAd`are set to `impressFallbackOnMount={true}` Settings 3. After applying `onAdImpression` check whether events are being collected properly
The in-app ad feature doesn't work in the sandbox The in-app ad feature is not supported in the sandbox. Sorry for the inconvenience, but please run the test 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.