---
title: "AdsGram SDK API 参考"
description: "AdsGram JavaScript SDK 完整参考：init 方法、AdController 方法（show、destroy、addEventListener）、参数与事件类型。"
outline: [2,3]
---
# API 参考

## Adsgram 方法

### init
创建用于显示、加载和销毁广告的 `AdController`。\
对于一个 `blockId`，只需初始化一次。\
如果您使用相同的 `blockId` 多次调用 `init` 函数，将返回相同的 `AdController`。
#### 语法
```js
const AdController = window.Adsgram.init({
  blockId: "your-block-id",
  debug: true,
  debugBannerType: "FullscreenMedia"
});
```

#### 参数
`blockId`
> 字符串，例如 `"123"`。\
> 广告块的唯一标识符，可在[流量主账户](https://partner.adsgram.ai/)中获取。\
> 获取 `blockId` 的详细说明，请参阅[获取 blockId 部分](./get-block-id)。

`debug` <Badge type="info" text="可选" />
> 布尔值，设置为 `true` 时，服务器将返回测试广告。\
> ::: danger 注意：
> 不要忘记在发布到生产环境时移除或将debug设置为 `false`。\
> 我们不会将测试广告曝光添加到统计数据中，因此您无法在平台和区块页面上看到其曝光、展示、点击等统计信息。\
> 请求 Reward URL 不会被发送。
> :::

`debugBannerType` <Badge type="info" text="可选" />
> 
> 可能的值为 `"FullscreenMedia"` 或 `"RewardedVideo"`。\
> 在调试模式下，当 debug 设置为 `true` 时，使用此值以获取指定类型的测试广告。

#### 返回值
`AdController`

## AdController 方法
### show
加载并显示广告。
#### 语法
::: code-group
```js [javascript]
AdController.show();
```
```ts [typescript]
const showPromise: Promise<ShowPromiseResult> = AdController.show();
```
:::
#### 返回值
> 返回 `Promise`，用户观看广告到结束或在插屏格式中关闭广告时解析，否则拒绝。\
> 示例类型如下：
> ```ts
> interface ShowPromiseResult {
>   done: boolean; // 用户观看到结束或在插屏格式中关闭广告时为 true，否则为 false。
>   description: string; // 事件描述。
>   state: 'load' | 'render' | 'playing' | 'destroy'; // 广告状态。
>   error: boolean; // 如果因错误触发事件则为 true，否则为 false。
> }
> ```

#### 示例
使用 [promises API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/then):
::: code-group
```js [javascript]
AdController.show().then((result) => {
  // 用户观看完整广告或在插屏模式下关闭广告
  // 给用户奖励的代码
}).catch((result) => {
  // 用户在播放广告时遇到错误或跳过广告
  // 无需处理或执行其他操作
})
```
```ts [typescript]
AdController.show().then((result: ShowPromiseResult) => {
  // 用户观看完整广告或在插屏模式下关闭广告
  // 给用户奖励的代码
}).catch((result: ShowPromiseResult) => {
  // 用户在播放广告时遇到错误或跳过广告
  // 无需处理或执行其他操作
})
```
:::
使用 [await](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await)
::: code-group
```js [javascript]
try {
  const showPromiseResult = await AdController.show();
  // 用户观看完整广告或在插屏模式下关闭广告
  // 给用户奖励的代码
} catch (showPromiseResult) {
  // 用户在播放广告时遇到错误或跳过广告
  // 无需处理或执行其他操作
}
```
```ts [typescript]
try {
  const showPromiseResult: ShowPromiseResult = await AdController.show();
  // 用户观看完整广告或在插屏模式下关闭广告
  // 给用户奖励的代码
} catch (error) {
  const showPromiseResult = error as ShowPromiseResult;
  // 用户在播放广告时遇到错误或跳过广告
  // 无需处理或执行其他操作
}
```
:::
::: tip 提示
如果您需要在广告播放结束、被跳过或出现错误后添加任何额外操作，请使用 `finally` 链式处理 Promise。
:::

### destroy
停止展示广告并移除加载的广告数据。
#### 语法
```js
AdController.destroy();
```
#### 返回值
> None(`undefined`)
::: info 信息
通常情况下，您无需手动调用它。如果发生错误、跳过广告或广告被完整观看，广告会自动销毁。
:::
### addEventListener
订阅 `event` 并在触发事件时调用 `callback` 函数；当您对广告展示需要更多控制时，可以使用此方法。

#### 语法
```js
AdController.addEventListener('onReward', () => {
    // 给用户奖励的代码
});
```
#### 参数 {#add-event-listener-parameters}
`event`
> ##### 事件类型：
> | 事件                | 触发时机                                                            |
> |--------------------|--------------------------------------------------------------------|
> | `onStart`          | 第一个广告帧展示时                                                    |
> | `onSkip`           | 用户关闭广告时                                                       |
> | `onReward`         | 用户观看奖励广告到结束时                                               |
> | `onComplete`       | 用户观看插页式广告到结束或关闭时                                        |
> | `onError`          | 用户在播放广告时遇到错误时                                             |
> | `onBannerNotFound` | 没有可显示广告时                                                      |
> | `onNonStopShow`    | 当用户尝试连续观看多个广告时                                            |
> | `onTooLongSession` | 当会话时间过长时，用户需要重新启动应用以获取广告                           |
>
> ::: tip 提示
> 如果您想显示自定义弹窗，可以订阅 `onBannerNotFound`、`onNonStopShow` 或 `onTooLongSession`。\
> 否则，我们将显示默认弹窗。\
> 弹窗会以用户的语言或英语显示
> <img src="../../publisher/images/default_alert_banner.webp" alt="alert" width="300" />
> :::

`callback`
> 当指定类型的事件发生时将被调用的函数。

#### 返回值
> None(`undefined`)
### removeEventListener
基于确定的 `callback` 取消订阅 `event`。
#### 语法
```ts
AdController.removeEventListener('onReward', rewardFunction);
```
#### 参数
和 [addEventListener](#add-event-listener-parameters) 相同

#### 返回值
> None(`undefined`)
