> 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/guang-gao/tossads.md).

# TossAds

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

### TossAds.initialize

#### 功能说明

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

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

#### 类型

```ts
TossAds.initialize(options: TossAdsInitializeOptions): void;
```

**参数**

```ts
interface TossAdsInitializeOptions {
  callbacks?: {
    /** 初始化成功时调用。 */
    onInitialized?: () => void;
    /** 初始化失败时调用。 */
    onInitializationFailed?: (error: Error) => void;
  };
}
```

**响应**

无。

#### 错误

如果 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 后再使用。

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

#### 类型

```ts
TossAds.attach(
  adGroupId: string,           // 广告组 ID（在 Appintos 控制台中发放）
  target: string | HTMLElement, // DOM 选择器或 HTMLElement
  options?: TossAdsAttachOptions,
): void;
```

**参数**

```ts
interface TossAdsAttachOptions {
  /** 主题设置。省略时遵循系统默认值。 */
  theme?: "light" | "dark";
  /** CSS padding 值（例如：'20px'、'10px 20px'）。仅适用于 List Banner 类型。 */
  padding?: string;
  /** 横幅事件回调。 */
  callbacks?: TossAdsBannerSlotCallbacks;
}
```

**响应**

无。

#### 错误

空 `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应用 `5.239.0` 可在以上版本中使用。调用前 `TossAds.attachBanner.isSupported()`可通过它确认是否支持。

#### 类型

```ts
TossAds.attachBanner(
  adGroupId: string,           // 广告组 ID（在 Appintos 控制台中发放）
  target: string | HTMLElement, // DOM 选择器或 HTMLElement
  options?: TossAdsAttachBannerOptions,
): TossAdsAttachBannerResult;
```

**参数**

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

**响应**

```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应用 `5.239.0` 可在以上版本中使用。调用前 `TossAds.destroy.isSupported()`可通过它确认是否支持。

#### 类型

```ts
TossAds.destroy(slotId: string): void;
```

**参数**

要移除的槽位 ID。

**响应**

无。

#### 示例代码

```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应用 `5.239.0` 可在以上版本中使用。调用前 `TossAds.destroyAll.isSupported()`可通过它确认是否支持。

#### 类型

```ts
TossAds.destroyAll(): void;
```

**参数**

无

**响应**

无。

#### 示例代码

```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/guang-gao/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.