TossAds.initialize

TossAds SDK를 초기화합니다. 배너 광고(attachBanner)를 사용하기 전에 반드시 한 번 호출해야 합니다. 앱 마운트 시점에 한 번만 실행하세요.

시그니처

initialize는 TossAds 네임스페이스 객체의 멤버로 노출됩니다.

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

declare const TossAds: {
  initialize: ((options: InitializeOptions) => void) & {
    isSupported: () => boolean;
  };
};

interface InitializeOptions {
  callbacks?: {
    onInitialized?: () => void;
    onInitializationFailed?: (error: Error) => void;
  };
}

파라미터

이름	타입	필수	설명
options	InitializeOptions	✓	초기화 옵션. 빈 객체({}) 전달도 허용됩니다.
options.callbacks	object	—	초기화 결과 콜백 객체.
options.callbacks.onInitialized	() => void	—	SDK 초기화 성공 시 호출됩니다.
options.callbacks.onInitializationFailed	(error: Error) => void	—	SDK 초기화 실패 시 호출됩니다.

반환값

• void — 반환값 없음.

권한

권한이 필요하지 않습니다 — TossAds.initialize는 별도의 PermissionName에 바인딩되지 않습니다. 권한이 필요한 다른 네임스페이스의 일반적인 처리 흐름은 Guides — 권한 처리 패턴을 참고하세요.

예제

최소 예제

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

TossAds.initialize({});

실전 예제 — 앱 진입 시 초기화 + 콜백

import { TossAds } from '@apps-in-toss/web-framework';
import { useEffect } from 'react';

function App() {
  useEffect(() => {
    if (!TossAds.initialize.isSupported()) {
      return;
    }

    TossAds.initialize({
      callbacks: {
        onInitialized: () => {
          console.log('TossAds 초기화 완료');
        },
        onInitializationFailed: (error) => {
          console.error('TossAds 초기화 실패', error);
        },
      },
    });
  }, []);

  return <main>{/* 앱 콘텐츠 */}</main>;
}

직접 실행해 보기

sdk-example의 Ads 페이지에서 TossAds.initialize 카드를 실행해 결과를 확인할 수 있습니다.

→sdk-example에서 실행해 보기

관련 API

• TossAds.attachBanner — 배너 광고를 DOM에 연결합니다.
• TossAds.destroyAll — 모든 배너 광고 슬롯을 파괴합니다.
• TossAds.destroy — 특정 슬롯 ID의 배너 광고를 파괴합니다.

관련 가이드

• Guides — 광고 통합 패턴 — 라이프사이클·클린업·환경 가드를 한 곳에 정리한 가이드.

외부 참조

• @apps-in-toss/web-framework — 상위 SDK 패키지. 실제 export는 내부적으로 @apps-in-toss/web-bridge에서 가져옵니다.