> 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 instructions, [In-app ad introduction document](https://developers-apps-in-toss.toss.im/guide/monetization/in-app-ad)please refer to. This is an ad library that can display banner ads in WebView. ### Get started The banner ad API can be used 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" %} **Handling versions below 5.241.0** In Toss app versions below 5.241.0, a blank screen may be shown, so be sure to handle this case. Use the Toss app version retrieval feature to handle exceptions. {% 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` | ### API reference **Overview** | API | Description | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `TossAds.initialize` | Initializes the banner ad SDK. It 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 `isSupported()` property lets you 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 does the banner refresh?** The SDK automatically refreshes the banner ad when both of the following conditions are met. * More than 10 seconds have passed since the ad was rendered * When the screen visibility changes from false to true (for example, when returning after clicking an ad or when the app returns from the background to the foreground) {% endhint %} **Initializing the banner ad SDK (`initialize`)** Initializes the banner ad SDK. The initialization process runs 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 when initializing the SDK. You can set callbacks for initialization success/failure. * **options.callbacks** · `{ onInitialized?: () => void; onInitializationFailed?: (error: Error) => void; }` An object that defines callbacks 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 failure reason is passed as `Error` 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 current runtime environment `TossAds.initialize` This function checks whether the feature is available. You must check support before calling the 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 functionality is not available.'); return; } // Initialize the 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 functionality is not available.'); return; } // Initialize the 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 users/developers Alert.alert('Banner ad initialization failed', String(error?.message ?? error)); }, }, }); }, []); return ( {isInitialized ? 'Ads ready' : 'Preparing ads...'} ); } ``` {% endtab %} {% endtabs %} *** **Banner ad attachment (`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`You must initialize the SDK by calling this first 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 be equal to the screen width (`100%`). * when using a fixed type `height: 96px` recommended {% endhint %} **Signature** ```tsx TossAds.attachBanner( adGroupId: string, target: string | HTMLElement, options?: TossAdsAttachBannerOptions ): TossAdsAttachBannerResult; ``` **Parameters** * **adGroupId** · Required · `string` The ad group ID. Enter the value issued in the console. * **target** · Required · `string | HTMLElement` The DOM element to attach the ad to. `HTMLElement` You can pass the object directly, or pass a CSS selector string. * **options** · `TossAdsAttachBannerOptions` An options object for configuring the banner style 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 background tone. The default is `'blackAndWhite'`. * **options.variant** · `'expanded' | 'card'` Sets the banner format. The default is `'expanded'`. * **options.callbacks** · `AttachBannerCallbacks` An object of callbacks 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 ad exposure 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 are no ads 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 format (default: 'expanded') callbacks?: TossAdsBannerSlotCallbacks; } ``` `TossAds.attachBanner` This is the option type for the function. | Option | Type | Default | Description | | ----------- | ----------------------------- | ----------------- | ------------------------------------------------------------------------- | | `theme` | `'auto' \| 'light' \| 'dark'` | `'auto'` | Theme setting. `auto`automatically switches according to system dark mode | | `tone` | `'blackAndWhite' \| 'grey'` | `'blackAndWhite'` | Background color tone | | `variant` | `'card' \| 'expanded'` | `'expanded'` | Banner format. `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 return type of the function. * `destroy()`: Removes the attached banner. It is recommended to call this when the 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; } ``` These are banner ad event callbacks. * `onAdRendered`: The ad has been rendered. * `onAdImpression`: The ad has been displayed on screen. * `onAdViewable`: Ad exposure has been recorded. (Revenue generation point) * `onAdClicked`: The user clicked the ad. * `onAdFailedToRender`: Ad rendering failed. * `onNoFill`: There are no ads 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 current runtime environment `TossAds.attachBanner` This function checks whether the feature is available. You must 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 format callbacks: { onAdRendered: (payload) => { console.log('Ad rendering complete:', payload.slotId); }, onAdImpression: (payload) => { console.log('Ad displayed:', payload.slotId); }, onAdViewable: (payload) => { console.log('Ad exposure recorded (revenue generated):', payload.slotId); }, onAdClicked: (payload) => { console.log('Ad clicked:', payload.slotId); }, onNoFill: (payload) => { console.warn('No ads 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 current runtime environment `TossAds.destroyAll` This function checks whether the feature is available. 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 best to initialize the SDK only once at app start. Initialization is recommended at the following times: * When the app's top-level component (App.tsx) mounts * Before entering the first screen that will display ads ```tsx // ✅ Good example: initialize at app start function App() { useEffect(() => { if (TossAds.initialize.isSupported()) { TossAds.initialize({ callbacks: { onInitialized: () => console.log('SDK ready'), }, }); } }, []); return ; } // ❌ Bad example: initialize in every component function BannerComponent() { useEffect(() => { TossAds.initialize({ /* ... */ }); // Attempt duplicate initialization }, []); } ``` **Container size settings** The ad container must be set to the correct size. ```tsx // ✅ Fixed type: width 100% + height 96px recommended
// ✅ Inline: width 100% + no specified height
// ❌ Wrong example: fixed width
``` **Memory management** You can prevent memory leaks by removing the banner when the component unmounts. `TossAds.attachBanner`is `destroy()` Since it returns an object that includes the method, 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` callback to prepare for errors. ```tsx TossAds.initialize({ callbacks: { onInitialized: () => { Initialization succeeded }, onInitializationFailed: (error) => { Initialization failed: // Provide appropriate feedback to the user }, }, }); TossAds.attachBanner(adGroupId, element, { callbacks: { onAdFailedToRender: (payload) => { console.error('Ad rendering failed:', payload.error.message); // Show 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 }; } ``` **Example usage** ```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 already initialized, it will not attempt duplicate initialization. *** ### 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 |

  • Disguising ads as "recommended services", "financial tips", etc.
  • Changing the color or font of ad units outside the Toss Ads guide
  • Arbitrarily modifying the ad title, label, CTA copy, and design
  • A structure that places ads adjacent to user interaction elements (buttons, gameplay areas, etc.) so that unintended clicks occur
  • 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 the functions of the ad and the service CTA
  • A structure that makes it difficult to notice or access the CTA needed for normal service use
|

  • Ads must always retain the "Ad" label
  • All ad UIs must use web-based standard components
  • Prohibited to design UI/UX that artificially drives ad performance or harms the user experience
| | Tampering with ad call behavior | Changing or bypassing the SDK's default event flow or ad call method |
  • Tampering with SDK Click / Impression events
  • Calling ads with custom logic without going through the ad SDK, or implementing them by bypassing SDK events
  • Blocking or abnormally controlling the Back button to prevent users from exiting the screen normally or navigating back
|

  • Prohibited to tamper with the structure of SDK default events (Click / Impression)
  • No external API calls outside the SDK
| | Abnormal traffic and performance manipulation | Distorting traffic and ad performance through automated or artificial methods |
  • Periodically refreshing the ad area
  • Activities that artificially generate performance (clicks, impressions, etc.)
|
  • If abnormal patterns based on traffic quality are detected, ads may be restricted, penalized, or settlement withheld
| | Reward-based / engagement-based click prompting | Providing rewards or benefits at the same time as an ad click |
  • "Rewards provided immediately after clicking the ad"
  • "Points provided when you click the ad"
|
  • Prohibited to directly tie ad consumption to rewards
  • Prohibited to use click-rewarding copy or event tie-ins
| | 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 may result in penalties. The WebView 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
The "This feature is not supported in the current environment" error occurs 1. Please check whether it is running in the Toss app environment. 2. Please check whether 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 the network connection. 3. If already initialized `[toss-ad] Already initialized.` An error occurs. Initialization should only be done once in the app, so manage the state globally to prevent duplicate calls.
I called TossAds.attachBanner, but the ad is not displayed 1. `TossAds.initialize`Call first and `onInitialized` Please check whether you received the callback. 2. Please check whether 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 whether it is correct. You must use the ID issued in the Apps in Toss console.
The "[toss-ad] Failed to find target element" error occurs 1. Please check whether the DOM element actually exists. 2. Please check whether the selector string is correct. For example, `#banner`, `.ad-container`you can pass it like this. 3. In React's case `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 whether you passed it to 2. Please check whether the callback function is defined correctly. 3. Please check whether an error is output in the console.
I want to remove the banner `TossAds.attachBanner`in the object returned by `destroy()`call it. If you need to remove the banner slot for the entire screen, `TossAds.destroyAll`you can use
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/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.