> 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/web-banner.md). # In-app ads - banner ads (WebView) 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). An ad library that can display banner ads in WebView. ### Getting Started The banner ad API is available in Toss app 5.241.0 and 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 appear, so be sure to handle exceptions. Please use the Toss app version retrieval 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` | ### API Reference **Overview** | API | Description | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `TossAds.initialize` | Initializes the banner ad SDK. Must be called once before displaying ads. | | `TossAds.attachBanner` | Attaches a banner ad to a specific DOM element. Style presets (theme, tone, variant) are applied, and the returned object's `destroy()` method can be used to remove the banner. | | `TossAds.destroyAll` | Removes all initialized banner slots. | Each API can `isSupported()` use the property to check whether the feature is available in the current environment. **Event Flow** ``` TossAds.initialize called ↓ onInitialized callback (initialization complete) ↓ TossAds.attachBanner called ↓ onAdRendered event (ad rendering complete) ↓ onAdImpression event (ad displayed on screen) ↓ onAdViewable event (ad impression recorded) ↓ onAdClicked event (optional - when user clicks) ``` {% hint style="info" %} **When is the banner refreshed?** The banner ad SDK automatically refreshes when both of the following conditions are met. * When 10 seconds or more have passed after the ad was rendered * When the screen's visibility changes from false → true (for example, returning after clicking the ad or when the app returns from background to foreground) {% endhint %} **Banner Ad SDK Initialization(`initialize`)** Initializes the banner ad SDK. Initialization proceeds asynchronously, and completion is delivered via a callback. You must initialize it once before using ads, and it is recommended to call it only once in the app's top-level component. **Signature** ```tsx TossAds.initialize(options: TossAdsInitializeOptions): void; ``` **Parameters** * **options** · `TossAdsInitializeOptions` An options object passed during SDK initialization. You can configure callbacks for initialization success/failure. * **options.callbacks** · `{ onInitialized?: () => void; onInitializationFailed?: (error: Error) => void; }` An object that defines callbacks to be invoked during SDK initialization. * **options.callbacks.onInitialized** · `() => void` Called when SDK initialization completes successfully. * **options.callbacks.onInitializationFailed** · `(error: Error) => void` Called when SDK initialization fails. The reason for failure is `Error` passed as an object. **TossAdsInitializeOptions** ```tsx interface TossAdsInitializeOptions { callbacks?: { onInitialized?: () => void; // Called when SDK initialization succeeds onInitializationFailed?: (error: Error) => void; // Called when SDK initialization fails }; } ``` **Properties** * isSupported() => boolean In the currently running environment, `TossAds.initialize` this is a function that checks whether the feature can be used. Be sure to check support before calling banner ad SDK initialization. **Example** {% tabs %} {% tab title="tsx\[React]" %} ```tsx import { TossAds } from '@apps-in-toss/web-framework'; import { useEffect, useState } from 'react'; function App() { const [isInitialized, setIsInitialized] = useState(false); useEffect(() => { // Check support status if (!TossAds.initialize.isSupported()) { console.warn('Banner ad feature is unavailable.'); return; } // Initialize SDK TossAds.initialize({ callbacks: { onInitialized: () => { console.log('SDK initialization complete'); setIsInitialized(true); }, onInitializationFailed: (error) => { console.error('SDK initialization failed:', error); }, }, }); }, []); return
{isInitialized ? 'Ads ready' : 'Preparing ads...'}; } ``` {% endtab %} {% tab title="tsx\[ReactNative]" %} ```tsx import React, { useEffect, useState } from 'react'; import { View, Text, Alert } from 'react-native'; import { TossAds } from '@apps-in-toss/framework'; export default function App() { const [isInitialized, setIsInitialized] = useState(false); useEffect(() => { // Check support status if (!TossAds.initialize.isSupported()) { console.warn('Banner ad feature is unavailable.'); return; } // Initialize SDK TossAds.initialize({ callbacks: { onInitialized: () => { console.log('SDK initialization complete'); setIsInitialized(true); }, onInitializationFailed: (error) => { console.error('SDK initialization failed:', error); // In a native environment, you can show an Alert to notify the user/developer Alert.alert('Banner ad initialization failed', String(error?.message ?? error)); }, }, }); }, []); return ( {isInitialized ? 'Ads ready' : 'Preparing ads...'} ); } ``` {% endtab %} {% endtabs %} *** **Attaching Banner Ads(`attachBanner`)** Attaches a banner ad to a specific DOM element. Style presets (theme, tone, variant) are applied, and the returned object's `destroy()` method can be used to remove the banner. `TossAds.initialize`must be called first to initialize the SDK before use. {% hint style="info" %} **Ad attachment guide** * The inside of the element where the ad is attached must be empty. * The container's `width`must always match the screen width (`100%`). * when used as fixed type `height: 96px` recommended {% endhint %} **Signature** ```tsx TossAds.attachBanner( adGroupId: string, target: string | HTMLElement, options?: TossAdsAttachBannerOptions ): TossAdsAttachBannerResult; ``` **Parameters** * **adGroupId** · Required · `string` The ID for the ad group. Enter the value issued from the console. * **target** · Required · `string | HTMLElement` The DOM element to which the ad will be attached. `HTMLElement` You can pass the object directly, or pass a CSS selector string. * **options** · `TossAdsAttachBannerOptions` An options object for configuring banner styles and ad event callbacks. * **options.theme** · `'auto' | 'light' | 'dark'` Sets the banner theme. The default is `'auto'`, and it automatically switches according to the system dark mode setting. * **options.tone** · `'blackAndWhite' | 'grey'` Sets the banner's background tone. The default is `'blackAndWhite'`It is. * **options.variant** · `'expanded' | 'card'` Sets the banner shape. The default is `'expanded'`It is. * **options.callbacks** · `AttachBannerCallbacks` A callback object that can receive ad lifecycle events. * **options.callbacks.onAdRendered** · `(payload) => void` Called when ad rendering is complete. * **options.callbacks.onAdImpression** · `(payload) => void` Called when the ad becomes visible to the user's screen. * **options.callbacks.onAdViewable** · `(payload) => void` Called when the ad impression is recorded and revenue is generated. * **options.callbacks.onAdClicked** · `(payload) => void` Called when the ad is clicked. * **options.callbacks.onNoFill** · `(payload) => void` Called when there is no ad to display. * **options.callbacks.onAdFailedToRender** · `(payload) => void` Called when ad rendering fails. **TossAdsAttachBannerOptions** ```tsx interface TossAdsAttachBannerOptions { theme?: 'auto' | 'light' | 'dark'; // Theme (default: 'auto') tone?: 'blackAndWhite' | 'grey'; // Background color tone (default: 'blackAndWhite') variant?: 'card' | 'expanded'; // Banner shape (default: 'expanded') callbacks?: TossAdsBannerSlotCallbacks; } ``` `TossAds.attachBanner` This is the function's option type. | Option | Type | Default value | Description | | ----------- | ----------------------------- | ----------------- | ----------------------------------------------------------------------------- | | `theme` | `'auto' \| 'light' \| 'dark'` | `'auto'` | Theme setting. `auto`automatically switches according to the system dark mode | | `tone` | `'blackAndWhite' \| 'grey'` | `'blackAndWhite'` | Background color tone | | `variant` | `'card' \| 'expanded'` | `'expanded'` | Banner shape. `card`has left and right padding + `border-radius` applied | | `callbacks` | `TossAdsBannerSlotCallbacks` | - | Ad event callbacks | **TossAdsAttachBannerResult** ```tsx interface TossAdsAttachBannerResult { destroy: () => void; } ``` `TossAds.attachBanner` This is the function's return type. * `destroy()`: removes the attached banner. It is recommended to call this when a component unmounts to prevent memory leaks. **TossAdsBannerSlotCallbacks** ```tsx interface TossAdsBannerSlotCallbacks { onAdRendered?: (payload: TossAdsBannerSlotEventPayload) => void; onAdViewable?: (payload: TossAdsBannerSlotEventPayload) => void; onAdClicked?: (payload: TossAdsBannerSlotEventPayload) => void; onAdImpression?: (payload: TossAdsBannerSlotEventPayload) => void; onAdFailedToRender?: (payload: TossAdsBannerSlotErrorPayload) => void; onNoFill?: (payload: { slotId: string; adGroupId: string; adMetadata: {} }) => void; } ``` Banner ad event callbacks. * `onAdRendered`: Ad rendered. * `onAdImpression`: Ad displayed on screen. * `onAdViewable`: Ad impression recorded. (revenue generation point) * `onAdClicked`: The user clicked the ad. * `onAdFailedToRender`: Ad rendering failed. * `onNoFill`: No ad to display. **TossAdsBannerSlotEventPayload** ```tsx interface TossAdsBannerSlotEventPayload { slotId: string; adGroupId: string; adMetadata: { creativeId: string; requestId: string; }; } ``` Banner ad event payload. * `slotId`: Generated slot ID * `adGroupId`: Ad group ID * `adMetadata`: Ad metadata (creativeId, requestId) **TossAdsBannerSlotErrorPayload** ```tsx interface TossAdsBannerSlotErrorPayload { slotId: string; adGroupId: string; adMetadata: {}; error: { code: number; message: string; domain?: string; }; } ``` Banner ad error payload. **Return value** `TossAdsAttachBannerResult` Returns an object. You can remove the banner by calling the `destroy()` method. **Properties** * isSupported() => boolean In the currently running environment, `TossAds.attachBanner` This is a function that checks whether the feature can be used. Be sure to check support before attaching a banner ad. **Example** ```tsx import { TossAds, TossAdsAttachBannerOptions } from '@apps-in-toss/web-framework'; import { useCallback, useEffect, useRef, useState } from 'react'; function BannerAdComponent({ adGroupId }: { adGroupId: string }) { const containerRef = useRef(null); const { isInitialized, attachBanner } = useTossBanner(); useEffect(() => { if (!isInitialized || !containerRef.current) return; // Attach banner const attached = attachBanner(adGroupId, containerRef.current, { theme: 'auto', // Automatically switches according to system settings tone: 'blackAndWhite', // White/black background variant: 'expanded', // Full-width expanded layout callbacks: { onAdRendered: (payload) => { console.log('Ad rendering complete:', payload.slotId); }, onAdImpression: (payload) => { console.log('Ad displayed:', payload.slotId); }, onAdViewable: (payload) => { console.log('Ad impression recorded (revenue generated):', payload.slotId); }, onAdClicked: (payload) => { console.log('Ad clicked:', payload.slotId); }, onNoFill: (payload) => { console.warn('No ad available to display:', payload.slotId); }, onAdFailedToRender: (payload) => { console.error('Ad rendering failed:', payload.error.message); }, }, }); // Cleanup: call destroy return () => { attached?.destroy(); }; }, [isInitialized, adGroupId, attachBanner]); // Fixed type banner: width 100% + height 96px return
; } // Custom hook for initialization and banner attachment function useTossBanner() { const [isInitialized, setIsInitialized] = useState(false); useEffect(() => { if (isInitialized) return; TossAds.initialize({ callbacks: { onInitialized: () => setIsInitialized(true), onInitializationFailed: (error) => { console.error('Toss Ads SDK initialization failed:', error); }, }, }); }, [isInitialized]); const attachBanner = useCallback( (adGroupId: string, element: HTMLElement, options?: TossAdsAttachBannerOptions) => { if (!isInitialized) return; return TossAds.attachBanner(adGroupId, element, options); }, [isInitialized], ); return { isInitialized, attachBanner }; } ``` Banner ad error payload. *** **Remove all banner slots(`destroyAll`)** Removes all initialized banner slots. **Signature** ```tsx TossAds.destroyAll(): void; ``` **Properties** * isSupported() => boolean In the currently running environment, `TossAds.destroyAll` This is a function that checks whether the feature can be used. It can be used to check support before removing all banner ad instances. **Example** ```tsx // Remove all banners when navigating pages useEffect(() => { return () => { TossAds.destroyAll(); }; }, []); ``` *** ### Usage Patterns **Initialization Timing** It is recommended to initialize the SDK only once when the app starts. Initialization is recommended at the following times: * When the app's top-level component (App.tsx) mounts * Before entering the first screen that displays ads ```tsx // ✅ Good example: initialize when the app starts function App() { useEffect(() => { if (TossAds.initialize.isSupported()) { TossAds.initialize({ callbacks: { onInitialized: () => console.log('SDK ready'), }, }); } }, []); return ; } // ❌ Bad example: initializing in every component function BannerComponent() { useEffect(() => { TossAds.initialize({ /* ... */ }); // attempted duplicate initialization }, []); } ``` **Set container size** The ad container must be set to the correct size. ```tsx // ✅ Fixed type: width 100% + height 96px recommended
// ✅ Inline: width 100% + no height specified
// ❌ Incorrect example: width is fixed
``` **Memory management** You need to remove the banner when the component unmounts to prevent memory leaks. `TossAds.attachBanner`is `destroy()` It returns an object including the method, so just call it during cleanup. ```tsx useEffect(() => { if (!isInitialized || !containerRef.current) return; // Attach banner const attached = TossAds.attachBanner(adGroupId, containerRef.current, { callbacks: { ... }, }); // Cleanup: call destroy return () => { attached?.destroy(); }; }, [isInitialized, adGroupId]); ``` **Error Handling** Always `onInitializationFailed`and `onAdFailedToRender` callbacks to prepare for errors. ```tsx TossAds.initialize({ callbacks: { onInitialized: () => { console.log('Initialization successful'); }, onInitializationFailed: (error) => { console.error('Initialization failed:', error); // Provide appropriate feedback to the user }, }, }); TossAds.attachBanner(adGroupId, element, { callbacks: { onAdFailedToRender: (payload) => { console.error('Ad rendering failed:', payload.error.message); // Display fallback content or retry }, }, }); ``` *** **Reusable custom hook** It's convenient to separate it into a custom hook when using banner ads across multiple screens. **useTossBanner** A hook that handles SDK initialization and banner attachment together. ```tsx import { useCallback, useEffect, useRef, useState } from 'react'; import { TossAds, type TossAdsAttachBannerOptions } from '@apps-in-toss/web-framework'; export function useTossBanner() { const [isInitialized, setIsInitialized] = useState(false); useEffect(() => { if (isInitialized) return; TossAds.initialize({ callbacks: { onInitialized: () => setIsInitialized(true), onInitializationFailed: (error) => { console.error('Toss Ads SDK initialization failed:', error); }, }, }); }, [isInitialized]); const attachBanner = useCallback( (adGroupId: string, element: HTMLElement, options?: TossAdsAttachBannerOptions) => { if (!isInitialized) return; return TossAds.attachBanner(adGroupId, element, options); }, [isInitialized], ); return { isInitialized, attachBanner }; } ``` **Usage example** ```tsx import { useRef, useEffect } from 'react'; function MyPage() { const bannerRef = useRef(null); const { isInitialized, attachBanner } = useTossBanner(); useEffect(() => { if (!isInitialized || !bannerRef.current) return; const attached = attachBanner('your-ad-group-id', bannerRef.current, { theme: 'auto', tone: 'blackAndWhite', variant: 'expanded', callbacks: { onAdRendered: (payload) => console.log('Ad rendered:', payload.slotId), onAdImpression: () => console.log('Ad impression'), }, }); return () => { attached?.destroy(); }; }, [isInitialized, attachBanner]); return (

My Page

{/* Fixed banner: width 100% + height 96px */}
); } ``` > **Note**: `useTossBanner`It is safe to call from multiple components. If it's already initialized, it will not attempt to initialize again. *** ### 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 |

  • Disguising ads as "Recommended services," "Financial tips," etc.
  • Changing the colors or fonts of ad units outside the Toss Ads guidelines
  • Arbitrarily modifying ad titles, labels, CTA copy, and design
  • Placing ads adjacent to user interaction elements (buttons, game play areas, etc.) to cause unintended clicks
  • Placing two or more ads of the same format on the same screen
  • A dead-end structure that makes it difficult for users to exit the screen normally or go back to the previous screen
  • A structure that makes it difficult for users to distinguish between ad functions and service CTAs
  • A structure that makes it difficult to recognize or access the CTA needed for normal service use
|

  • Ads must keep the "Ad" label
  • All ad UIs must use web-base standard components
  • Prohibit UI/UX setups that artificially drive ad performance or degrade user experience
| | Ad call manipulation | Changing or bypassing the SDK's default event flow or ad call method |
  • SDK Click / Impression event manipulation
  • If ads are called through custom logic without going through the ad SDK, or SDK events are bypassed
  • If the Back button is blocked or improperly controlled, preventing the user from exiting the screen normally or returning to the previous screen
|

  • Prohibit manipulating the SDK's default event (Click / Impression) structure
  • No external API calls from the SDK
| | Abnormal traffic and performance manipulation | Any act that distorts traffic and ad performance through automation or artificial means |
  • Periodically refreshing the ad area
  • Activities that artificially generate performance (clicks, impressions, etc.)
|
  • If abnormal patterns based on traffic quality are detected, ad restrictions, sanctions, and payment holds may be applied
| | Reward-based / participation-based click inducement | Providing rewards or benefits at the same time as ad clicks |
  • "Rewards provided immediately after clicking the ad"
  • "Points provided when you click the ad"
|
  • Prohibit structures that directly link ad consumption to rewards
  • Prohibit reward-related copy and event linkage for 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, you must use test ad IDs. Testing with real ad IDs may be considered a policy violation and result in disadvantages. The WebView banner ad test ID can be found [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
\"This feature is not supported in the current environment\" error occurs 1. Please check that it is running in the Toss app environment. 2. Please check that the app version meets the requirements. 3. `isSupported()` Please first check support using the method.
SDK initialization failed 1. `onInitializationFailed` Please check the specific error message in the callback. 2. Please check your network connection. 3. If already initialized `[toss-ad] Already initialized.` An error occurs. Initialization must only be done once in the app, so manage the state globally to prevent duplicate calls.
I called TossAds.attachBanner, but the ad isn't displayed 1. `TossAds.initialize`call it first and `onInitialized` Please check whether you received the callback. 2. Please check that the DOM element actually exists. In React, `useEffect`in `ref.current`is `null`make sure it is not null. 3. `onAdFailedToRender` or `onNoFill` Check for errors in the callback. 4. `adGroupId`Please check that the ID is correct. You must use the ID issued in the App in Toss console.
\"[toss-ad] Failed to find target element\" error occurs 1. Please check that the DOM element actually exists. 2. Please check whether the selector string is correct. For example, `#banner`, `.ad-container`can be passed like this. 3. In the case of React `ref.current`is `null`make sure it is not null.
The ad is displayed, but the callback is not called 1. `callbacks` the option `TossAds.attachBanner`Please check that you passed the option to it. 2. Please check that the callback function is defined correctly. 3. Please check whether an error is printed in the console.
I want to remove the banner `TossAds.attachBanner`Please call the method of the object returned by `destroy()`it. If you need to remove the banner slot for the entire screen, `TossAds.destroyAll`you can use it.
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/web-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.