인앱 광고 2.0 ver2 (배너 광고 - React Native)

지원환경: React NativeReact Native SDKv1.11.0

실행환경: Toss App최소버전v5.241

React Native에서는 TossAds.attachBanner 대신 InlineAd 컴포넌트를 사용해 배너를 렌더링해요.
이 문서는 RN 전용 사용 방식만 다루며, 공통 정책/운영 항목은 기존 문서를 단일 기준(SoT)으로 참조해요.

공통 기준 문서: 배너 초안

공통 항목 딥링크

• 테스트 광고 ID: 기존 문서의 콘솔 가이드 섹션을 참고해주세요.
• 지원 버전: 기존 문서의 지원 버전 섹션을 참고해주세요.
• 광고 정책: 기존 문서의 광고 정책 섹션을 참고해주세요.
• theme/tone/variant 설명: 기존 문서의 적용 가이드 > 스타일 옵션 섹션을 참고해주세요.
• 컨테이너 96/인라인 가이드: 기존 문서의 컨테이너 사이즈 가이드 섹션을 참고해주세요.

개요

• 패키지: @apps-in-toss/framework
• 주요 API: InlineAd 컴포넌트
• 전제: 토스 앱 환경 + 최소 버전 충족 시 정상 동작
• 참고: RN InlineAd 문서는 initialize/attach/destroyAll을 기본 경로로 사용하지 않아요.

빠른 시작

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)}
    />
  );
}

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;
}

• adGroupId (필수): 광고 그룹 ID
• theme (기본값 auto)
• tone (기본값 blackAndWhite)
• variant (기본값 expanded)
• impressFallbackOnMount (선택): 최상위 스크롤이 IOScrollView가 아닐 때, 노출 이벤트 fallback 처리를 위해 설정해주세요.

콜백 및 페이로드

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

레이아웃 가이드

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

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

노출 측정

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

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

권장 패턴 1: IOScrollView 사용

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

대체 패턴 2: fallback 사용

prop 사용

impressFallbackOnMount prop 은 IOScrollView 컨텍스트가 없어도 InlineAd가 마운트될 때 노출(impression) fallback 로직을 수행합니다.

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

---

자주 묻는 질문

1. 토스 앱 환경 및 최소 버전을 확인해주세요.

2. adGroupId가 유효한지 확인해주세요.

3. onNoFill() 또는 onAdFailedToRender payload를 확인해주세요.

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

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

1. 최상위 스크롤 컴포넌트가 @granite-js/react-native의 IOScrollView인지 확인

2. IOScrollView 적용이 어려우면 InlineAd에 impressFallbackOnMount={true} 설정

3. 적용 후 onAdImpression 이벤트가 정상 수집되는지 확인