API 参考

Adsgram 方法

init

创建用于显示、加载和销毁广告的 AdController。
对于一个 blockId，只需初始化一次。
如果您使用相同的 blockId 多次调用 init 函数，将返回相同的 AdController。

语法

const AdController = window.Adsgram.init({
  blockId: "your-block-id",
  debug: true,
  debugBannerType: "FullscreenMedia"
});

参数

blockId

字符串，例如 "123"。
广告块的唯一标识符，可在流量主账户中获取。
获取 blockId 的详细说明，请参阅获取 blockId 部分。

debug 可选

布尔值，设置为 true 时，服务器将返回测试广告。\

注意：

不要忘记在发布到生产环境时移除或将debug设置为 false。
我们不会将测试广告曝光添加到统计数据中，因此您无法在平台和区块页面上看到其曝光、展示、点击等统计信息。
请求 Reward URL 不会被发送。

debugBannerType 可选

可能的值为 "FullscreenMedia" 或 "RewardedVideo"。
在调试模式下，当 debug 设置为 true 时，使用此值以获取指定类型的测试广告。

返回值

AdController

AdController 方法

show

加载并显示广告。

语法

javascript

AdController.show();

typescript

const showPromise: Promise<ShowPromiseResult> = AdController.show();

返回值

返回 Promise，用户观看广告到结束时解析，否则拒绝。
示例类型如下：

interface ShowPromiseResult {
  done: boolean; // 用户观看到结束时为 true，否则为 false。
  description: string; // 事件描述。
  state: 'load' | 'render' | 'playing' | 'destroy'; // 广告状态。
  error: boolean; // 如果因错误触发事件则为 true，否则为 false。
}

示例

使用 promises API:

javascript

AdController.show().then((result) => {
  // 用户观看到结束
  // 给用户奖励的代码
}).catch((result) => {
  // 用户在播放广告时遇到错误或跳过广告
  // 无需处理或执行其他操作
})

typescript

AdController.show().then((result: ShowPromiseResult) => {
  // 用户观看到结束
  // 给用户奖励的代码
}).catch((result: ShowPromiseResult) => {
  // 用户在播放广告时遇到错误或跳过广告
  // 无需处理或执行其他操作
})

使用 await

javascript

try {
  const showPromiseResult = await AdController.show();
  // 用户观看到结束
  // 给用户奖励的代码
} catch (showPromiseResult) {
  // 用户在播放广告时遇到错误或跳过广告
  // 无需处理或执行其他操作
}

typescript

try {
  const showPromiseResult: ShowPromiseResult = await AdController.show();
  // 用户观看到结束
  // 给用户奖励的代码
} catch (showPromiseResult: ShowPromiseResult) {
  // 用户在播放广告时遇到错误或跳过广告
  // 无需处理或执行其他操作
}

提示

如果您需要在广告播放结束、被跳过或出现错误后添加任何额外操作，请使用 finally 链式处理 Promise。

destroy

停止展示广告并移除加载的广告数据。

语法

AdController.destroy();

返回值

None(undefined)

信息

通常情况下，您无需手动调用它。如果发生错误、跳过广告或广告被完整观看，广告会自动销毁。

addEventListener

订阅 event 并在触发事件时调用 callback 函数；当您对广告展示需要更多控制时，可以使用此方法。

语法

AdController.addEventListener('onReward', () => {
    // 给用户奖励的代码
});

参数事件类型

event

Types of events:

事件	触发时机
onStart	第一个广告帧展示时
onSkip	用户关闭广告时
onReward	用户观看奖励广告到结束时
onComplete	用户观看插页式广告到结束或关闭时
onError	用户在播放广告时遇到错误时
onBannerNotFound	没有可显示广告时
onNonStopShow	当用户尝试连续观看多个广告时
onTooLongSession	当会话时间过长时，用户需要重新启动应用以获取广告

提示

如果您想显示自定义弹窗，可以订阅 onBannerNotFound、onNonStopShow 或 onTooLongSession。
否则，我们将显示默认弹窗。
弹窗会以用户的语言或英语显示

callback

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

返回值

None(undefined)

removeEventListener

基于确定的 callback 取消订阅 event。

语法

AdController.removeEventListener('onReward', rewardFunction);

参数

和 addEventListener 相同

返回值

None(undefined)