In-App Ads - Banner Ads (React Native)

For service introduction and console setup instructions, In-app ad introduction documentplease refer to.

In React Native, TossAds.attachBanner instead InlineAd Render the banner using the component.

Get started

InlineAdCan be used in the Toss app 5.241.0 or later.

Toss app version	Support status	Description
5.241.0 or later	Supported	Banner ads available
Below 5.241.0	Not supported	Banner ad API unavailable

Handling versions below 5.241.0

If used in Toss app versions below 5.241.0, a blank screen may appear, so be sure to handle exceptions. Get Toss app version Please handle exceptions using the function.

During development, use test ad IDs.

Type	Test ID
Banner ad - list type	ait-ad-test-banner-id
Banner ad - feed type	ait-ad-test-native-image-id

Quick start

import { InlineAd } from '@apps-in-toss/framework';

export function BannerSection() {
  return (
    <InlineAd
      adGroupId="ait-ad-test-banner-id"
      theme="auto"
      tone="blackAndWhite"
      variant="expanded"
      onAdRendered={(payload) => console.log('onAdRendered', payload)}
      onAdImpression={(payload) => console.log('onAdImpression', payload)}
      onAdViewable={(payload) => console.log('onAdViewable', payload)}
      onAdClicked={(payload) => console.log('onAdClicked', payload)}
      onNoFill={(payload) => console.log('onNoFill', payload)}
      onAdFailedToRender={(payload) => console.log('onAdFailedToRender', payload)}
    />
  );
}

API reference

Overview

Item	Value
Package	@apps-in-toss/framework
Key APIs	InlineAd Component
Prerequisites	Toss app environment, 5.241.0 or later

RN InlineAd In the documentation, the WebView banner ad initialize, attachBanner, destroyAllis not introduced as the default path.

Props

type InlineAdTheme = 'auto' | 'light' | 'dark';
type InlineAdTone = 'blackAndWhite' | 'grey';
type InlineAdVariant = 'expanded' | 'card';

interface InlineAdProps {
  adGroupId: string;
  theme?: InlineAdTheme;
  tone?: InlineAdTone;
  variant?: InlineAdVariant;
  impressFallbackOnMount?: boolean;
}

Prop	Type	Description
adGroupId	string	Required. Pass the ad group ID issued from the console.
theme	InlineAdTheme	The default value is auto.
tone	InlineAdTone	The default value is blackAndWhite.
variant	InlineAdVariant	The default value is expanded.
impressFallbackOnMount	boolean	IOScrollViewWhen it is hard to use, turn on exposure event fallback handling.

Callbacks and payloads

interface BannerSlotEventPayload {
  slotId: string;
  adGroupId: string;
  adMetadata: {
    creativeId: string;
    requestId: string;
    styleId: string;
  };
}

interface BannerSlotErrorPayload {
  slotId: string;
  adGroupId: string;
  adMetadata: {};
  error: {
    code: number;
    message: string;
    domain?: string;
  };
}

Callback	When it occurs
onAdRendered	Right after the ad data becomes renderable.
onAdImpression	IMP_1PX This is the timing. It is based on revenue events.
onAdViewable	This is the moment when exposure of 50% or more has been maintained for 1 second.
onAdClicked	This is when the user clicked the ad area.
onNoFill	Called when there is no ad inventory.
onAdFailedToRender	Render failure, unsupported environment, parameter error.

Event flow

InlineAd mount or adGroupId change
↓
Ad load (loadAd)
↓
onAdRendered
↓
onAdImpression (IMP_1PX)
↓
onAdViewable (50% exposure + 1 second held)
↓
onAdClicked (when the user clicks)

Refresh behavior

• When app/screen visibility visiblereturns, after the last IMP_1PX if 10 seconds or more have passed since then, it reloads.

Error handling

• Unsupported environments: This feature is not supported in the current environment
• adGroupId Missing/invalid values: onAdFailedToRenderSend an error payload to
• No ad: onNoFill
• Server/network/internal errors: onAdFailedToRender

Exposure and layout

InlineAdis for exposure measurement IOContext.Provider The context is used. You must satisfy one of the following two conditions.

Condition	Recommended setting
Can control the top-level scroll container	@granite-js/react-nativeof IOScrollViewWrap with
IOScrollView Difficult to apply	InlineAdto impressFallbackOnMount={true} Configuration

Recommended pattern: IOScrollView Usage

import { IOScrollView } from '@granite-js/react-native';
import { InlineAd } from '@apps-in-toss/framework';

export function Screen() {
  return (
    <IOScrollView>
      <InlineAd adGroupId="ait-ad-test-banner-id" />
    </IOScrollView>
  );
}

Alternative pattern: use fallback

Use prop

impressFallbackOnMount The prop runs impression fallback logic when InlineAd mounts even without an IOScrollView context.

import { ScrollView } from 'react-native';
import { InlineAd } from '@apps-in-toss/framework';

export function Screen() {
  return (
    <ScrollView>
      <InlineAd adGroupId="ait-ad-test-banner-id" impressFallbackOnMount={true} />
    </ScrollView>
  );
}

Layout guide

• Fixed: width 100%, height 96 Recommended
• Inline: width 100%, height not specified (content height auto)

import { View } from 'react-native';
import { InlineAd } from '@apps-in-toss/framework';

export function FixedBanner() {
  return (
    <View style={{ width: '100%', height: 96, overflow: 'hidden' }}>
      <InlineAd adGroupId="ait-ad-test-banner-id" />
    </View>
  );
}

export function InlineBanner() {
  return (
    <View style={{ width: '100%' }}>
      <InlineAd adGroupId="ait-ad-test-banner-id" />
    </View>
  );
}

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 can result in penalties. The RN 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

Ads are not visible

1. Please check the Toss app environment and minimum version.
2. adGroupIdPlease check whether it is valid.
3. onNoFill() or onAdFailedToRender Please check the payload.

The callback order seems different from the documentation

onAdImpressionis defined as the 1px impression point, onAdViewableis defined as the 50%+1 second point.

Can I use the existing web API (TossAds.initialize/attachBanner/destroyAll) as-is in RN?

In the RN InlineAd path, that API is not introduced as the default path. RN is InlineAd Please use it centered on the component.

"The ImpressionArea was used outside IOContext.Provider" error occurs

1. Top-level scroll component @granite-js/react-nativeof IOScrollViewcheck whether it is
2. IOScrollView If it is difficult to apply, InlineAdto impressFallbackOnMount={true} Configuration
3. After applying, onAdImpression check whether events are being collected properly

In-app ad functionality does not work in the sandbox

In-app ad functionality is not supported in the sandbox.

Sorry for the inconvenience, but please proceed with testing using the QR code in the console.