> 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/api-and-sdk-en/sdk/domains-api/ads/tossads.md). # TossAds This is an inline banner ads SDK. `initialize`After initializing with `attachBanner`attach a banner to the slot with ### TossAds.initialize #### Feature description Initialize the Toss banner ads SDK. Initialization is asynchronous, and the result is delivered via a callback. You must call it once before attaching a banner. If you call it again after it has already been initialized, without duplicate initialization `onInitialized` the callback is invoked immediately (idempotent). Toss app `5.239.0` can be used on versions above. Before calling, `TossAds.initialize.isSupported()`You can check support with #### Type ```ts TossAds.initialize(options: TossAdsInitializeOptions): void; ``` **Params** ```ts interface TossAdsInitializeOptions { callbacks?: { /** Called when initialization succeeds. */ onInitialized?: () => void; /** Called when initialization fails. */ onInitializationFailed?: (error: Error) => void; }; } ``` **Response** None. #### Error If loading the SDK script or initialization fails, `onInitializationFailed` the error is passed through the callback. #### Example code ```js import { Ads } from "@apps-in-toss/web-framework"; function initializeAds() { if (!TossAds.initialize.isSupported()) { console.warn("Banner ads cannot be used in the current environment."); return; } TossAds.initialize({ callbacks: { onInitialized: () => { console.log("Banner ads SDK initialization complete"); }, onInitializationFailed: (error) => { console.error("Banner ads SDK initialization failed:", error); }, }, }); } ``` ### TossAds.attach > **deprecated**: `TossAds.attach`is no longer recommended. `TossAds.attachBanner`and use it. #### Feature description Attach a banner ad to a specific DOM element. `TossAds.initialize`must be called first to initialize the SDK before using it. Toss app `5.239.0` can be used on versions above. Before calling, `TossAds.attach.isSupported()`You can check support with #### Type ```ts TossAds.attach( adGroupId: string, // Ad group ID (issued in the Appintos console) target: string | HTMLElement, // DOM selector or HTMLElement options?: TossAdsAttachOptions, ): void; ``` **Params** ```ts interface TossAdsAttachOptions { /** Theme setting. If omitted, the system default is used. */ theme?: "light" | "dark"; /** CSS padding value (e.g. '20px', '10px 20px'). Applies only to the List Banner type. */ padding?: string; /** Banner event callback. */ callbacks?: TossAdsBannerSlotCallbacks; } ``` **Response** None. #### Error empty `adGroupId`, if attachment fails due to being called before initialization, a non-existent target, etc., `callbacks.onAdFailedToRender` the error is passed through the callback. #### Example code ```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; // used later in TossAds.destroy }, onAdFailedToRender: (payload) => { console.error("Ad rendering failed:", payload.error.message); }, }, }); ``` ### TossAds.attachBanner #### Feature description Attach a banner ad with style presets (background color, rounding, padding) applied to a DOM element. `TossAds.initialize`must be called first to initialize the SDK before using it. to the same element `attachBanner`If you call it repeatedly, it won't attach a new one and will return the existing banner's handle as is. To attach again with different options, the existing handle's `destroy()`must be called first. Toss app `5.239.0` can be used on versions above. Before calling, `TossAds.attachBanner.isSupported()`You can check support with #### Type ```ts TossAds.attachBanner( adGroupId: string, // Ad group ID (issued in the Appintos console) target: string | HTMLElement, // DOM selector or HTMLElement options?: TossAdsAttachBannerOptions, ): TossAdsAttachBannerResult; ``` **Params** ```ts interface TossAdsAttachBannerOptions { /** Theme override. The default is 'auto', which follows the system dark mode. */ theme?: "auto" | "light" | "dark"; /** Background color tone. The default is 'blackAndWhite'. */ tone?: "blackAndWhite" | "grey"; /** Banner variant. 'card' is a card style with rounding and horizontal margins, and 'expanded' is a full-width style. The default is 'expanded'. */ variant?: "card" | "expanded"; /** Banner event callback. */ callbacks?: TossAdsBannerSlotCallbacks; } interface TossAdsBannerSlotCallbacks { /** Called when the ad is rendered. You can receive and store slotId here. */ onAdRendered?: (payload: TossAdsBannerSlotEventPayload) => void; /** Called when the ad is shown on screen. */ onAdViewable?: (payload: TossAdsBannerSlotEventPayload) => void; /** Called when the user clicks the ad. */ onAdClicked?: (payload: TossAdsBannerSlotEventPayload) => void; /** Called when an ad impression is recorded. (The point at which revenue is generated) */ onAdImpression?: (payload: TossAdsBannerSlotEventPayload) => void; /** Called when ad rendering fails. */ onAdFailedToRender?: (payload: TossAdsBannerSlotErrorPayload) => void; /** Called when there is no ad to display. */ onNoFill?: (payload: { slotId: string; adGroupId: string; adMetadata: Record; }) => void; } interface TossAdsBannerSlotEventPayload { slotId: string; // The generated slot ID. You can pass it to TossAds.destroy. adGroupId: string; // Ad group 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 { /** Remove the attached banner and wrapper element together. */ destroy: () => void; } ``` #### Error empty `adGroupId`, if attachment fails due to being called before initialization, a non-existent target, etc., `callbacks.onAdFailedToRender` The error is passed through the callback, and a `destroy`result that does nothing is returned. #### Example code ```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("Ad rendering complete:", payload.slotId); }, onAdImpression: () => { console.log("Ad impression recorded (revenue generated)"); }, onNoFill: () => { console.warn("There is no ad to display."); }, onAdFailedToRender: (payload) => { console.error("Ad rendering failed:", payload.error.message); }, }, }); // Remove the banner when leaving the screen window.addEventListener("pagehide", () => { banner.destroy(); }); ``` ### TossAds.destroy #### Feature description Remove a banner with a specific slot ID. `slotId`can be received from the banner callback's `payload.slotId`If the SDK hasn't been initialized, it does nothing. Toss app `5.239.0` can be used on versions above. Before calling, `TossAds.destroy.isSupported()`You can check support with #### Type ```ts TossAds.destroy(slotId: string): void; ``` **Params** This is the slot ID to remove. **Response** None. #### Example code ```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; }, }, }); // Remove a specific banner function removeBanner() { if (slotId) { TossAds.destroy(slotId); slotId = null; } } ``` ### TossAds.destroyAll #### Feature description Remove all initialized banner slots at once. `attachBanner`The internal state of banners attached with it is also reset, so you can attach again to the same element afterward. If the SDK hasn't been initialized, it does nothing. Toss app `5.239.0` can be used on versions above. Before calling, `TossAds.destroyAll.isSupported()`You can check support with #### Type ```ts TossAds.destroyAll(): void; ``` **Params** None **Response** None. #### Example code ```js import { Ads } from "@apps-in-toss/web-framework"; // Remove all banners when leaving the page 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/api-and-sdk-en/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.