In-App Ads - Banner Ads (WebView)

For service introduction and console setup instructions, In-app ad introduction documentplease 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

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.

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)

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)

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

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

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

tsx[React]

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 <div>{isInitialized ? 'Ads ready' : 'Preparing ads...' };
}

tsx[ReactNative]

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 (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      <Text>{isInitialized ? 'Ads ready' : 'Preparing ads...'}</Text>
    </View>
  );
}

---

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.initializeYou must initialize the SDK by calling this first before use.

Ad attachment guide

• The inside of the element where the ad is attached must be empty.
• The container's widthmust always be equal to the screen width (100%).
• when using a fixed type height: 96px recommended

Signature

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

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. autoautomatically switches according to system dark mode
tone	'blackAndWhite' | 'grey'	'blackAndWhite'	Background color tone
variant	'card' | 'expanded'	'expanded'	Banner format. cardhas left and right padding + border-radius applied
callbacks	TossAdsBannerSlotCallbacks	-	Ad event callbacks

TossAdsAttachBannerResult

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

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

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

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

import { TossAds, TossAdsAttachBannerOptions } from '@apps-in-toss/web-framework';
import { useCallback, useEffect, useRef, useState } from 'react';

function BannerAdComponent({ adGroupId }: { adGroupId: string }) {
  const containerRef = useRef<HTMLDivElement>(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 <div ref={containerRef} style={{ width: '100%', height: '96px' }} />;
}

// 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

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

// 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

// ✅ Good example: initialize at app start
function App() {
  useEffect(() => {
    if (TossAds.initialize.isSupported()) {
      TossAds.initialize({
        callbacks: {
          onInitialized: () => console.log('SDK ready'),
        },
      });
    }
  }, []);

  return <Router />;
}

// ❌ 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.

// ✅ Fixed type: width 100% + height 96px recommended
<div ref={containerRef} style={{ width: '100%', height: '96px' }} />

// ✅ Inline: width 100% + no specified height
<div ref={containerRef} style={{ width: '100%' }} />

// ❌ Wrong example: fixed width
<div ref={containerRef} style={{ width: '320px', height: '96px' }} />

Memory management

You can prevent memory leaks by removing the banner when the component unmounts.

TossAds.attachBanneris destroy() Since it returns an object that includes the method, just call it during cleanup.

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 onInitializationFailedand onAdFailedToRender callback to prepare for errors.

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.

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

import { useRef, useEffect } from 'react';

function MyPage() {
  const bannerRef = useRef<HTMLDivElement>(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 (
    <div>
      <h1>My Page</h1>
      {/* Fixed banner: width 100% + height 96px */}
      <div ref={bannerRef} style={{ width: '100%', height: '96px' }} />

  );
}

Note: useTossBannerIt 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 daysYou 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 appropriateand 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 startedcan 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.initializeCall first and onInitialized Please check whether you received the callback.
2. Please check whether the DOM element actually exists. In React, useEffectin ref.currentis nullmake sure it is not null.
3. onAdFailedToRender or onNoFill Check for errors in the callback.
4. adGroupIdPlease 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-containeryou can pass it like this.
3. In React's case ref.currentis nullmake sure it is not null.

The ad is displayed, but the callback is not called

1. callbacks the option TossAds.attachBannerPlease 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.attachBannerin the object returned by destroy()call it. If you need to remove the banner slot for the entire screen, TossAds.destroyAllyou 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.