> 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-zh/sdk/domains-api/ads/tossads.md).

# TossAds

这是内联横幅广告 SDK。 `initialize`以……初始化后 `attachBanner`将横幅附加到槽位上。

### TossAds.initialize

#### 功能说明

初始化 Toss 横幅广告 SDK。初始化是异步进行的，结果会通过回调传递。必须在附加横幅之前调用一次。若在已经初始化的状态下再次调用，则不会重复初始化 `onInitialized` 回调会立即被调用（幂等）。

Toss App `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

> **已弃用**: `TossAds.attach`已不再推荐使用。 `TossAds.attachBanner`使用。

#### 功能说明

将横幅广告附加到特定 DOM 元素。 `TossAds.initialize`请先调用它以初始化 SDK 后再使用。

Toss App `5.239.0` 可在以上版本中使用。调用前 `TossAds.attach.isSupported()`可通过它确认是否支持。

#### 类型

```ts
TossAds.attach(
  adGroupId: string,           // 广告组 ID（从 Apps in Toss 控制台发放）
  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()`需要先调用。

Toss App `5.239.0` 可在以上版本中使用。调用前 `TossAds.attachBanner.isSupported()`可通过它确认是否支持。

#### 类型

```ts
TossAds.attachBanner(
  adGroupId: string,           // 广告组 ID（从 Apps in Toss 控制台发放）
  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<string, never>;
  }) => void;
}

interface TossAdsBannerSlotEventPayload {
  slotId: string; // 生成的槽位 ID。可以传给 TossAds.destroy。
  adGroupId: string; // 广告组 ID
  adMetadata: {
    creativeId: string;
    requestId: string;
  };
}

interface TossAdsBannerSlotErrorPayload {
  slotId: string;
  adGroupId: string;
  adMetadata: Record<string, never>;
  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 尚未初始化，则不会有任何动作。

Toss App `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 尚未初始化，则不会有任何动作。

Toss App `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/api-and-sdk-zh/sdk/domains-api/ads/tossads.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.