> 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/sdk/domains-api/ads/tossads.md). # TossAds 인라인 배너 광고 SDK예요. `initialize`로 초기화한 뒤 `attachBanner`로 슬롯에 배너를 붙여요. ### TossAds.initialize #### 기능 설명 토스 배너 광고 SDK를 초기화해요. 초기화는 비동기로 진행되며 결과는 콜백으로 전달돼요. 배너를 부착하기 전에 반드시 한 번 호출해야 해요. 이미 초기화된 상태에서 다시 호출하면 중복 초기화 없이 `onInitialized` 콜백이 바로 호출돼요(멱등). 토스앱 `5.239.0` 이상에서 사용할 수 있어요. 호출 전에 `TossAds.initialize.isSupported()`로 지원 여부를 확인할 수 있어요. #### 타입 ```ts TossAds.initialize(options: TossAdsInitializeOptions): void; ``` **Params** ```ts interface TossAdsInitializeOptions { callbacks?: { /** 초기화 성공 시 호출돼요. */ onInitialized?: () => void; /** 초기화 실패 시 호출돼요. */ onInitializationFailed?: (error: Error) => void; }; } ``` **Response** 없음. #### 에러 SDK 스크립트 로드나 초기화에 실패하면 `onInitializationFailed` 콜백으로 에러가 전달돼요. #### 예시 코드 ```js import { Ads } from "@apps-in-toss/web-framework"; function initializeAds() { if (!TossAds.initialize.isSupported()) { console.warn("현재 환경에서는 배너 광고를 사용할 수 없어요."); return; } TossAds.initialize({ callbacks: { onInitialized: () => { console.log("배너 광고 SDK 초기화 완료"); }, onInitializationFailed: (error) => { console.error("배너 광고 SDK 초기화 실패:", error); }, }, }); } ``` ### TossAds.attach > **deprecated**: `TossAds.attach`는 더 이상 권장되지 않아요. `TossAds.attachBanner`를 사용하세요. #### 기능 설명 특정 DOM 요소에 배너 광고를 부착해요. `TossAds.initialize`를 먼저 호출해서 SDK를 초기화한 후에 사용해야 해요. 토스앱 `5.239.0` 이상에서 사용할 수 있어요. 호출 전에 `TossAds.attach.isSupported()`로 지원 여부를 확인할 수 있어요. #### 타입 ```ts TossAds.attach( adGroupId: string, // 광고 그룹 ID (앱인토스 콘솔에서 발급) target: string | HTMLElement, // DOM 셀렉터 또는 HTMLElement options?: TossAdsAttachOptions, ): void; ``` **Params** ```ts interface TossAdsAttachOptions { /** 테마 설정이에요. 생략하면 시스템 기본값을 따라요. */ theme?: "light" | "dark"; /** CSS padding 값이에요 (예: '20px', '10px 20px'). List Banner 타입에만 적용돼요. */ padding?: string; /** 배너 이벤트 콜백이에요. */ callbacks?: TossAdsBannerSlotCallbacks; } ``` **Response** 없음. #### 에러 빈 `adGroupId`, 초기화 전 호출, 존재하지 않는 target 등 부착에 실패하면 `callbacks.onAdFailedToRender` 콜백으로 에러가 전달돼요. #### 예시 코드 ```js import { Ads } from "@apps-in-toss/web-framework"; let slotId = null; TossAds.attach("AD_GROUP_ID", "#banner-container", { padding: "20px", callbacks: { onAdRendered: (payload) => { slotId = payload.slotId; // 나중에 TossAds.destroy에 사용 }, onAdFailedToRender: (payload) => { console.error("광고 렌더링 실패:", payload.error.message); }, }, }); ``` ### TossAds.attachBanner #### 기능 설명 스타일 프리셋(배경색, 라운딩, 패딩)이 적용된 배너 광고를 DOM 요소에 부착해요. `TossAds.initialize`를 먼저 호출해서 SDK를 초기화한 후에 사용해야 해요. 같은 요소에 `attachBanner`를 중복 호출하면 새로 부착하지 않고 기존 배너의 핸들을 그대로 반환해요. 다른 옵션으로 다시 부착하려면 기존 핸들의 `destroy()`를 먼저 호출해야 해요. 토스앱 `5.239.0` 이상에서 사용할 수 있어요. 호출 전에 `TossAds.attachBanner.isSupported()`로 지원 여부를 확인할 수 있어요. #### 타입 ```ts TossAds.attachBanner( adGroupId: string, // 광고 그룹 ID (앱인토스 콘솔에서 발급) target: string | HTMLElement, // DOM 셀렉터 또는 HTMLElement options?: TossAdsAttachBannerOptions, ): TossAdsAttachBannerResult; ``` **Params** ```ts interface TossAdsAttachBannerOptions { /** 테마 오버라이드예요. 기본값은 'auto'로, 시스템 다크 모드를 따라요. */ theme?: "auto" | "light" | "dark"; /** 배경 색상 톤이에요. 기본값은 'blackAndWhite'예요. */ tone?: "blackAndWhite" | "grey"; /** 배너 형태예요. 'card'는 라운딩과 좌우 여백이 있는 카드형, 'expanded'는 가로로 꽉 찬 형태예요. 기본값은 'expanded'예요. */ variant?: "card" | "expanded"; /** 배너 이벤트 콜백이에요. */ callbacks?: TossAdsBannerSlotCallbacks; } interface TossAdsBannerSlotCallbacks { /** 광고가 렌더링됐을 때 호출돼요. slotId를 여기서 받아 저장할 수 있어요. */ 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: Record; }) => void; } interface TossAdsBannerSlotEventPayload { slotId: string; // 생성된 슬롯 ID. TossAds.destroy에 전달할 수 있어요. adGroupId: string; // 광고 그룹 ID adMetadata: { creativeId: string; requestId: string; }; } interface TossAdsBannerSlotErrorPayload { slotId: string; adGroupId: string; adMetadata: Record; error: { code: number; message: string; domain?: string }; } ``` **Response** ```ts interface TossAdsAttachBannerResult { /** 부착한 배너와 래퍼 요소를 함께 제거해요. */ destroy: () => void; } ``` #### 에러 빈 `adGroupId`, 초기화 전 호출, 존재하지 않는 target 등 부착에 실패하면 `callbacks.onAdFailedToRender` 콜백으로 에러가 전달되고, 아무 동작도 하지 않는 `destroy`를 가진 결과가 반환돼요. #### 예시 코드 ```js import { Ads } from "@apps-in-toss/web-framework"; const container = document.querySelector("#banner-container"); const banner = TossAds.attachBanner("AD_GROUP_ID", container, { variant: "card", tone: "grey", callbacks: { onAdRendered: (payload) => { console.log("광고 렌더링 완료:", payload.slotId); }, onAdImpression: () => { console.log("광고 노출 기록됨 (수익 발생)"); }, onNoFill: () => { console.warn("표시할 광고가 없어요."); }, onAdFailedToRender: (payload) => { console.error("광고 렌더링 실패:", payload.error.message); }, }, }); // 화면을 떠날 때 배너 제거 window.addEventListener("pagehide", () => { banner.destroy(); }); ``` ### TossAds.destroy #### 기능 설명 특정 슬롯 ID의 배너를 제거해요. `slotId`는 배너 콜백의 `payload.slotId`로 받을 수 있어요. SDK가 초기화되지 않았으면 아무 동작도 하지 않아요. 토스앱 `5.239.0` 이상에서 사용할 수 있어요. 호출 전에 `TossAds.destroy.isSupported()`로 지원 여부를 확인할 수 있어요. #### 타입 ```ts TossAds.destroy(slotId: string): void; ``` **Params** 제거할 슬롯 ID예요. **Response** 없음. #### 예시 코드 ```js import { Ads } from "@apps-in-toss/web-framework"; let slotId = null; TossAds.attachBanner("AD_GROUP_ID", "#banner-container", { callbacks: { onAdRendered: (payload) => { slotId = payload.slotId; }, }, }); // 특정 배너 제거 function removeBanner() { if (slotId) { TossAds.destroy(slotId); slotId = null; } } ``` ### TossAds.destroyAll #### 기능 설명 초기화된 모든 배너 슬롯을 한 번에 제거해요. `attachBanner`로 부착한 배너의 내부 상태도 함께 초기화되므로, 이후 같은 요소에 다시 부착할 수 있어요. SDK가 초기화되지 않았으면 아무 동작도 하지 않아요. 토스앱 `5.239.0` 이상에서 사용할 수 있어요. 호출 전에 `TossAds.destroyAll.isSupported()`로 지원 여부를 확인할 수 있어요. #### 타입 ```ts TossAds.destroyAll(): void; ``` **Params** 없음 **Response** 없음. #### 예시 코드 ```js import { Ads } from "@apps-in-toss/web-framework"; // 페이지를 떠날 때 모든 배너 제거 window.addEventListener("pagehide", () => { TossAds.destroyAll(); }); ``` --- # 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/sdk/domains-api/ads/tossads.md?ask=&goal= ``` `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.