> 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/common/monetization/iaa/rn-banner.md).

# 인앱 광고 - 배너 광고(React Native)

서비스 소개와 콘솔 설정 방법은 인앱 광고 소개 문서를 참고해 주세요.

React Native에서는 `TossAds.attachBanner` 대신 `InlineAd` 컴포넌트를 사용해 배너를 렌더링해요.

### 시작하기

`InlineAd`는 토스 앱 5.241.0 이상에서 사용할 수 있어요.

| 토스 앱 버전        | 지원 여부 | 설명              |
| -------------- | ----- | --------------- |
| **5.241.0 이상** | 지원    | 배너 광고 사용 가능     |
| **5.241.0 미만** | 미지원   | 배너 광고 API 사용 불가 |

{% hint style="info" %}
**5.241.0 미만 버전 예외 처리**

토스앱 5.241.0 미만에서는 빈 화면이 노출될 수 있으니 반드시 예외 처리를 해주세요. [토스앱 버전 가져오기](/documentation/common/network-environment/version.md) 기능을 사용해 예외 처리를 해주세요.
{% endhint %}

개발 단계에서는 테스트용 광고 ID를 사용해요.

| 유형           | 테스트 ID                        |
| ------------ | ----------------------------- |
| 배너 광고 - 리스트형 | `ait-ad-test-banner-id`       |
| 배너 광고 - 피드형  | `ait-ad-test-native-image-id` |

**빠른 시작**

```tsx
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 레퍼런스

**개요**

| 항목     | 값                         |
| ------ | ------------------------- |
| 패키지    | `@apps-in-toss/framework` |
| 주요 API | `InlineAd` 컴포넌트           |
| 전제     | 토스 앱 환경, 5.241.0 이상       |

RN `InlineAd` 문서에서는 WebView 배너 광고의 `initialize`, `attachBanner`, `destroyAll`을 기본 경로로 안내하지 않아요.

**Props**

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

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

| Prop                     | 타입                | 설명                                               |
| ------------------------ | ----------------- | ------------------------------------------------ |
| `adGroupId`              | `string`          | 필수 값이에요. 콘솔에서 발급받은 광고 그룹 ID를 전달해요.               |
| `theme`                  | `InlineAdTheme`   | 기본값은 `auto`예요.                                   |
| `tone`                   | `InlineAdTone`    | 기본값은 `blackAndWhite`예요.                          |
| `variant`                | `InlineAdVariant` | 기본값은 `expanded`예요.                               |
| `impressFallbackOnMount` | `boolean`         | `IOScrollView`를 쓰기 어려울 때 노출 이벤트 fallback 처리를 켜요. |

**콜백 및 페이로드**

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

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

| 콜백                   | 발생 시점                          |
| -------------------- | ------------------------------ |
| `onAdRendered`       | 광고 데이터가 렌더 가능한 상태가 된 직후예요.     |
| `onAdImpression`     | `IMP_1PX` 시점이에요. 수익 이벤트 기준이에요. |
| `onAdViewable`       | 50% 이상 노출 상태가 1초 유지된 시점이에요.    |
| `onAdClicked`        | 사용자가 광고 영역을 클릭한 시점이에요.         |
| `onNoFill`           | 광고 재고가 없을 때 호출돼요.              |
| `onAdFailedToRender` | 렌더 실패, 환경 미지원, 파라미터 오류예요.      |

**이벤트 흐름**

```
InlineAd mount 또는 adGroupId 변경
↓
광고 로드(loadAd)
↓
onAdRendered
↓
onAdImpression (IMP_1PX)
↓
onAdViewable (50% 노출 + 1초 유지)
↓
onAdClicked (사용자 클릭 시)
```

**리프레시 동작**

* 앱/화면 visibility가 `visible`로 돌아왔을 때, 마지막 `IMP_1PX` 이후 10초 이상 지났으면 재로드돼요.

**에러 처리**

* 미지원 환경: `This feature is not supported in the current environment`
* `adGroupId` 누락/잘못된 값: `onAdFailedToRender`로 에러 payload 전달
* 광고 없음: `onNoFill`
* 서버/네트워크/내부 오류: `onAdFailedToRender`

### 노출과 레이아웃

`InlineAd`는 노출 측정을 위해 `IOContext.Provider` 컨텍스트를 사용해요. 아래 둘 중 하나를 반드시 만족해야 해요.

| 조건                     | 권장 설정                                           |
| ---------------------- | ----------------------------------------------- |
| 최상위 스크롤 컨테이너를 제어할 수 있음 | `@granite-js/react-native`의 `IOScrollView`로 감싸기 |
| `IOScrollView` 적용이 어려움 | `InlineAd`에 `impressFallbackOnMount={true}` 설정  |

**권장 패턴: `IOScrollView` 사용**

```tsx
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>
  );
}
```

**대체 패턴: fallback 사용**

{% hint style="info" %}
**prop 사용**

`impressFallbackOnMount` prop은 IOScrollView 컨텍스트가 없어도 InlineAd가 마운트될 때 노출(impression) fallback 로직을 수행해요.
{% endhint %}

```tsx
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>
  );
}
```

**레이아웃 가이드**

* 고정형: 너비 `100%`, 높이 `96` 권장
* 인라인: 너비 `100%`, 높이 미지정(콘텐츠 높이 자동)

```tsx
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>
  );
}
```

### 광고 정책 <a href="#policy" id="policy"></a>

#### 토스 애즈 SSP 정책 <a href="#ssp" id="ssp"></a>

아래 정책을 반드시 지켜주세요. 위반할 경우 광고 노출이 제한될 수 있어요.

**본 정책에 명시되지 않은 경우라도, 광고 노출·클릭·성과를 인위적으로 유도하거나 이용자 오인을 발생시키는 행위는 정책 위반으로 간주될 수 있어요.**

모든 파트너사는 정책 위반으로 서비스가 종료되는 경우, 서비스 종료 정책을 준수해야 해요.

| 유형              | 금지 행위                                                                                  | 구체적 예시                                                                                                                                                                                                                                                                                                                                                                                                                   | 정책 기준                                                                                                                                           |
| --------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| UI/UX 품질 저하     | 광고와 콘텐츠의 구분을 불명확하게 하거나, 사용자 의도와 무관한 광고 소비 또는 클릭을 유도하거나, 정상적인 서비스 이용을 방해하도록 UI를 구성하는 행위 | <p></p><ul><li>"추천 서비스", "금융 팁" 등으로 광고를 위장</li><li>Toss Ads 가이드 외 광고 단위의 색상·글꼴 변경</li><li>광고의 타이틀·라벨·CTA 문구 및 디자인 임의 수정</li><li>사용자 상호작용 요소(버튼, 게임 플레이 영역 등)와 인접하게 광고를 배치하여 의도치 않은 클릭이 발생하도록 하는 구조</li><li>동일 화면에 동일 포맷 광고를 2개 이상 배치하는 경우</li><li>사용자가 정상적으로 화면을 종료하거나 이전 화면으로 이동하기 어렵게 하는 막다른(Dead-end) 구조</li><li>광고와 서비스 CTA의 기능을 사용자가 구분하기 어렵게 구성한 구조</li><li>서비스의 정상적인 이용에 필요한 CTA를 인지하거나 접근하기 어렵게 구성한 구조</li></ul> | <p></p><ul><li>광고는 반드시 "Ad" 표기를 유지해야 함</li><li>모든 광고 UI는 web-base 표준 컴포넌트를 사용해야 함</li><li>광고 성과를 인위적으로 유도하거나 사용자 경험을 저해하는 UI/UX 구성 금지</li></ul> |
| 광고 호출 동작 변조     | SDK 기본 이벤트 흐름이나 광고 호출 방식을 변경하거나 우회하는 행위                                                | <ul><li>SDK Click / Impression 이벤트 변조</li><li>광고 SDK를 거치지 않고 자체 로직으로 광고를 호출하거나 SDK 이벤트를 우회하여 구현하는 경우</li><li>Back 버튼을 차단하거나 비정상적으로 제어하여 사용자의 정상적인 화면 종료 또는 이전 화면 이동을 방해하는 경우</li></ul>                                                                                                                                                                                                                                   | <p></p><ul><li>SDK 기본 이벤트(Click / Impression) 구조 변조 금지</li><li>SDK 외부 API 호출 불가</li></ul>                                                       |
| 비정상 트래픽 및 성과 조작 | 자동화 또는 인위적 방식으로 트래픽 및 광고 성과를 왜곡하는 행위                                                   | <ul><li>광고 영역을 주기적으로 Refresh 처리</li><li>인위적으로 성과(클릭·노출 등)를 발생시키는 활동</li></ul>                                                                                                                                                                                                                                                                                                                                            | <ul><li>트래픽 품질 기반의 비정상 패턴이 확인될 경우 광고 제한, 제재, 정산 보류</li></ul>                                                                                    |
| 보상·참여형 클릭 유도    | 광고 클릭과 동시에 보상 또는 혜택을 제공하는 행위                                                           | <ul><li>"광고 클릭 즉시 리워드 제공"</li><li>"광고 클릭하면 포인트 제공"</li></ul>                                                                                                                                                                                                                                                                                                                                                             | <ul><li>광고 소비를 보상과 직접 연결하는 구조 금지</li><li>클릭 보상성 문구·이벤트 연동 금지</li></ul>                                                                          |
| 광고 은닉 또는 겹침     | 광고를 의도적으로 숨기거나 다른 UI 요소에 가려 사용자가 광고의 존재를 명확히 인지하기 어렵게 만드는 행위                           | <p>• 투명 광고 </p><p>• 다른 카드 UI 뒤에 광고 DOM 삽입</p>                                                                                                                                                                                                                                                                                                                                                                            | • 광고는 노출 상태가 명확히 확인 가능해야 함                                                                                                                      |

***

#### **UX / Product Principle 운영 원칙**

광고도 토스의 UX 원칙을 따라야 해요.

| **Toss Principle**             | **적용 기준**                              | **예시**                       |
| ------------------------------ | -------------------------------------- | ---------------------------- |
| **Simplicity**                 | 광고는 명료해야 하며, 추가 설명 없이 의미를 이해할 수 있어야 해요 | "지금 보기", "광고 보기" 등 명확 CTA 사용 |
| **Clear Action**               | 광고 클릭 후 어떤 행동이 발생할지 사용자가 예측 가능해야 해요    | 리디렉션·새창 이동 시 고지 문구 노출        |
| **No Deception (UX Red Rule)** | 광고가 예상치 못한 순간, 형태, 위치에서 등장하지 않아야 해요    | 서비스 진입 직후 전면 배너 금지           |
| **Value First**                | 광고는 고객의 서비스 목표를 방해하지 않아야 해요            | 결제/계좌 개설 흐름 중 광고 삽입 금지       |

#### 이용 제한 및 제재 조치

앱인토스 광고 지면 또는 서비스가 본 정책을 위반한 경우 제재가 적용될 수 있어요.

***

**제한 절차**

제한 조치는 원칙적으로 위반 행위의 누적 정도에 따라 단계적으로 적용돼요. 다만, 위반의 유형이나 중대성에 따라 단일 위반에도 즉시 30일 이용 제한 또는 영구 이용 제한이 적용될 수 있어요.

※ 동시에 확인된 위반은 위반 슬롯의 개수와 관계없이 1회 위반으로 처리돼요. 이후 별도로 위반이 확인되는 경우 위반 횟수가 누적돼요.

<figure><img src="/files/btdVaHFWy4SdZGarwrAH" alt=""><figcaption></figcaption></figure>

***

**부당 수익 처리**

정책 위반, 무효 트래픽 또는 기타 부정한 방식으로 발생한 수익은 부당 수익으로 간주될 수 있어요.

부당 수익이 확인되면 해당 금액에 대해 지급 보류 또는 지급 거절이 이루어질 수 있으며, 이미 지급된 금액도 동일하게 환수될 수 있어요.

***

**이의제기 절차**

* 이용 제한 통지를 받은 경우 **30일 이내 이의제기를 신청**할 수 있어요.
  * 이의제기 자료는 채널톡을 통해 제출할 수 있어요.
* 제출된 자료는 내부 기준에 따라 검토되며, 필요한 경우 추가 자료를 요청할 수 있어요.
  * 검토에는 영업일 기준 약 1주일이 소요될 수 있어요.
  * 이의제기 신청에 대해서는 **제재가 적절했는지 여부를 중심으로 검토**하며, 위반 사항을 수정했거나 재발 방지 계획을 제출한 사실만으로는 제재가 해제되지 않아요.
  * 제출된 이의제기 자료를 통해 제재의 근거가 된 위반 사실이 인정되지 않거나 제재 판단에 명백한 오류가 있는 것으로 확인되는 경우에는 제재가 해제될 수 있어요.
* 반복적이거나 중대한 위반의 경우 서비스 이용이 영구적으로 제한될 수 있어요.

***

**테스트하기**

개발 단계에서는 반드시 테스트용 광고 ID를 사용해요. 실제 광고 ID로 테스트하면 정책 위반으로 간주해 불이익을 받을 수 있어요. RN 배너 광고 테스트 ID는 [시작하기](#시작하기)에서 확인할 수 있어요.

출시 전에 아래 항목을 꼭 확인해 주세요.

* 광고가 정상적으로 로드되는지 확인해요.
* 클릭 시 의도한 화면으로 이동하는지 확인해요.
* 뒤로 가기 동작이 정상적으로 작동하는지 확인해요.
* 결제나 인증 흐름을 방해하지 않는지 확인해요.

***

### 자주 묻는 질문

<details>

<summary>광고가 보이지 않아요</summary>

1. 토스 앱 환경 및 최소 버전을 확인해 주세요.
2. `adGroupId`가 유효한지 확인해 주세요.
3. `onNoFill()` 또는 `onAdFailedToRender` payload를 확인해 주세요.

</details>

<details>

<summary>콜백 순서가 문서와 달라 보여요</summary>

`onAdImpression`은 1px 노출 시점, `onAdViewable`은 50%+1초 시점으로 정의돼요.

</details>

<details>

<summary>기존 웹 API(TossAds.initialize/attachBanner/destroyAll)를 RN에서 그대로 써도 되나요?</summary>

RN InlineAd 경로에서는 해당 API를 기본 경로로 안내하지 않아요. RN은 `InlineAd` 컴포넌트 중심으로 사용해 주세요.

</details>

<details>

<summary>\"ImpressionArea가 IOContext.Provider 밖에서 사용되었습니다\" 에러가 발생해요</summary>

1. 최상위 스크롤 컴포넌트가 `@granite-js/react-native`의 `IOScrollView`인지 확인
2. `IOScrollView` 적용이 어려우면 `InlineAd`에 `impressFallbackOnMount={true}` 설정
3. 적용 후 `onAdImpression` 이벤트가 정상 수집되는지 확인

</details>

<details>

<summary>샌드박스에서 인앱 광고 기능이 되지 않아요</summary>

샌드박스에서는 인앱 광고 기능을 지원하지 않아요.

불편하시겠지만 콘솔 내 QR 코드로 테스트를 진행해 주세요.

</details>


---

# 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/common/monetization/iaa/rn-banner.md?ask=<question>&goal=<endgoal>
```

`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.