Ad API

激励视频、横幅、分享等激励动作自 v0.2.0 起已统一为单一槽位模型。通过查询 API（getRewardedAdSlots / getRewardedAdSlot）获取活跃槽位并渲染，用户点击时只需一次 showRewardedAd({ slotId }) 调用即可执行。如需在不使用槽位的情况下仅展示激励视频广告，仍可照常使用 showRewardedAd({ adUnitId })。

`showRewardedAd(options)` (推荐)

一次调用即可执行激励广告/激励动作。若提供 slotId，则按该槽位的动作（视频/横幅/分享）执行；否则使用 adUnitId 执行激励视频广告。加载、展示、失败重试及提示由平台自动处理。

选项:

参数	类型	必填	说明
`slotId`	`string`	△	激励槽位 ID（从 `getRewardedAdSlots` / `getRewardedAdSlot` 获取）。优先处理。
`adUnitId`	`string`	△	广告单元 ID。未指定 `slotId` 时按激励视频广告执行。
`success`	`function`	-	成功回调
`fail`	`function`	-	失败回调
`complete`	`function`	-	完成回调

slotId 与 adUnitId 均为可选，但至少需提供一个。两者都存在时，slotId 优先。

成功响应:

字段	类型	说明
`isEnded`	`boolean`	激励是否完成（奖励发放对象）
`errMsg`	`string`	结果消息

// 1) 执行激励槽位（推荐）
TudadaSDK.showRewardedAd({
  slotId: slot.slotId,
  success: (res) => {
    if (res.isEnded) {
      giveReward();   // 奖励发放由游戏自行执行
    }
  },
  fail: (err) => console.error('激励动作执行失败:', err.errMsg),
});

// 2) 直接执行激励视频广告
TudadaSDK.showRewardedAd({
  adUnitId: 'your-ad-unit-id',
  success: (res) => {
    if (res.isEnded) giveReward();
  },
});

参考: 加载失败时平台会自动重试，最终失败时会显示提示弹窗。游戏无需单独实现错误处理 UI。isEnded 为 true 时即为奖励发放对象，实际奖励发放由游戏自行执行。

`showRewardedAdAsync(options)`

showRewardedAd() 的 Promise 版本。选项相同，通过 Promise<ShowRewardedAdResult> 返回激励完成状态。

const result = await TudadaSDK.showRewardedAdAsync({ slotId: slot.slotId });
if (result.isEnded) {
  giveReward();
}

统一激励槽位

激励槽位是将激励视频、横幅、分享作为单一模型处理的 v0.2.0 统一 API。游戏获取活跃槽位列表，使用 slotData 自行渲染，用户点击时以 showRewardedAd({ slotId }) 执行。

每个槽位的结构如下。

字段	类型	说明
`slotId`	`string`	槽位标识符（执行时指定）
`action`	`string`	动作类型（`'REWARD_VIDEO'` \| `'BANNER'` \| `'SHARE'`）
`slotData`	`object?`	供游戏渲染的数据（可选）
`slotData.imageUrl`	`string?`	槽位图片 URL（游戏自行渲染）
`slotData.title`	`string?`	槽位标题
`slotData.expiresAt`	`number?`	过期时间（Unix 毫秒）

默认激励视频与分享槽位没有需要渲染的视觉元素，因此可能没有 slotData。横幅槽位通常包含 slotData.imageUrl。

`getRewardedAdSlots(options?)`

获取全部活跃激励槽位列表。

选项:

参数	类型	必填	说明
`success`	`function`	-	成功回调
`fail`	`function`	-	失败回调
`complete`	`function`	-	完成回调

成功响应:

字段	类型	说明
`slots`	`RewardedAdSlot[]`	活跃槽位列表
`errMsg`	`string`	结果消息

TudadaSDK.getRewardedAdSlots({
  success: ({ slots }) => {
    slots.forEach((slot) => {
      if (slot.slotData?.imageUrl) renderSlot(slot);
    });
  },
});

`getRewardedAdSlotsAsync()`

getRewardedAdSlots() 的 Promise 版本。

const { slots } = await TudadaSDK.getRewardedAdSlotsAsync();

`getRewardedAdSlot(options)`

按 slotId 查询单个槽位。如果槽位不存在，将调用 fail 回调。

选项:

参数	类型	必填	说明
`slotId`	`string`	✅	要查询的槽位 ID
`success`	`function`	-	成功回调
`fail`	`function`	-	失败回调（包括槽位不存在）
`complete`	`function`	-	完成回调

成功响应:

字段	类型	说明
`slot`	`RewardedAdSlot`	槽位信息
`errMsg`	`string`	结果消息

TudadaSDK.getRewardedAdSlot({
  slotId: 'main_menu_reward',
  success: ({ slot }) => renderSlot(slot),
  fail: (err) => console.warn('槽位不存在:', err.errMsg),
});

`getRewardedAdSlotAsync(slotId)`

getRewardedAdSlot() 的 Promise 版本。直接以槽位 ID 作为参数传入，槽位不存在时 reject。

try {
  const { slot } = await TudadaSDK.getRewardedAdSlotAsync('main_menu_reward');
  renderSlot(slot);
} catch (e) {
  // 槽位没有可展示的激励 — 不显示 UI
}

完整流程:

// 1) 查询活跃槽位
const { slots } = await TudadaSDK.getRewardedAdSlotsAsync();

// 2) 渲染槽位（由游戏自行完成）
slots.forEach((slot) => {
  if (!slot.slotData?.imageUrl) return;
  const el = renderSlotButton(slot.slotData);

  // 3) 用户点击时执行
  el.onclick = async () => {
    const res = await TudadaSDK.showRewardedAdAsync({ slotId: slot.slotId });
    if (res.isEnded) giveReward();   // 奖励发放由游戏自行执行
  };
});

`createRewardedVideoAd(options)` (旧版)

已弃用 (Deprecated)

createRewardedVideoAd 是旧版 API，将在未来版本中移除。请使用统一 API showRewardedAd() 或 showRewardedAdAsync()。

创建激励视频广告实例。

选项:

参数	类型	必填	说明
`adUnitId`	`string`	✅	广告单元 ID
`multiton`	`boolean`	-	多实例模式

参考: 当前仅支持单个广告，且广告 ID 由平台控制，因此 adUnitId 可输入任意字符串。

实例方法:

成员	类型	说明
`load()`	`Promise<void>`	加载广告
`show()`	`Promise<void>`	展示广告
`destroy()`	`void`	销毁实例
`onLoad(callback)`	`void`	加载完成事件
`onError(callback)`	`void`	错误事件
`onClose(callback)`	`void`	关闭事件
`offLoad(callback?)`	`void`	取消加载事件
`offError(callback?)`	`void`	取消错误事件
`offClose(callback?)`	`void`	取消关闭事件

// 创建广告实例
const rewardedAd = TudadaSDK.createRewardedVideoAd({
  adUnitId: 'your-ad-unit-id',
});

// 注册事件监听器
rewardedAd.onLoad(() => {
  console.log('广告加载完成');
});

rewardedAd.onError((err) => {
  console.error('广告错误:', err.errMsg, err.errCode);
});

rewardedAd.onClose((res) => {
  if (res.isEnded) {
    // 用户已完整观看广告 → 发放奖励
    console.log('发放奖励!');
    giveReward();
  } else {
    // 用户中途关闭
    console.log('广告中途关闭');
  }
});

// 加载并展示广告
rewardedAd.load()
  .then(() => rewardedAd.show())
  .catch((err) => console.error('广告展示失败:', err));

已弃用 (Deprecated)

横幅广告 API（getAvailableBannerIds / getBanner / runBannerAction）已被统一激励槽位取代，仅为兼容而保留。新接入请使用 getRewardedAdSlots() 获取槽位，并以 showRewardedAd({ slotId })（action=BANNER）执行。

横幅广告采用槽位模型：游戏在屏幕上定义槽位（如 "main_menu_top"），由游戏自行渲染广告图片。SDK 仅负责图片 URL 的传递与动作处理，渲染、点击检测与后处理由游戏自由控制。

bannerId 是兼作槽位名称的横幅标识符。
用户点击横幅时，游戏调用 runBannerAction(bannerId) 将动作处理委托给 SDK。
响应只携带 success / fail 信号，奖励等后处理在游戏内部完成。

`getAvailableBannerIds(options)`

获取当前活跃的横幅槽位 ID 列表。由于游戏通常已知自己的槽位名称，此 API 主要用于运营元数据。

选项：

参数	类型	必填	说明
`success`	`function`	-	成功回调
`fail`	`function`	-	失败回调
`complete`	`function`	-	完成回调

成功响应：

字段	类型	说明
`bannerIds`	`string[]`	活跃槽位名称数组
`errMsg`	`string`	结果消息

TudadaSDK.getAvailableBannerIds({
  success: ({ bannerIds }) => {
    console.log('活跃槽位:', bannerIds);
  },
});

`getAvailableBannerIdsAsync()`

getAvailableBannerIds() 的 Promise 版本。

const { bannerIds } = await TudadaSDK.getAvailableBannerIdsAsync();

`getBanner(options)`

按槽位名称获取匹配的横幅数据。如果槽位未匹配到广告，将调用 fail 回调。

选项：

参数	类型	必填	说明
`bannerId`	`string`	✅	兼作槽位名称的横幅 ID
`success`	`function`	-	成功回调
`fail`	`function`	-	失败回调（包括"无匹配"）
`complete`	`function`	-	完成回调

成功响应：

字段	类型	说明
`banner.bannerId`	`string`	兼作槽位名称的横幅 ID
`banner.imageUrl`	`string`	横幅图片 URL（游戏自行渲染）
`banner.expiresAt`	`number?`	过期时间（Unix 毫秒，可选）
`errMsg`	`string`	结果消息

TudadaSDK.getBanner({
  bannerId: 'main_menu_top',
  success: ({ banner }) => {
    const img = document.createElement('img');
    img.src = banner.imageUrl;
    document.body.appendChild(img);
  },
  fail: (err) => {
    console.warn('该槽位无可用广告:', err.errMsg);
  },
});

`getBannerAsync(bannerId)`

getBanner() 的 Promise 版本。无匹配广告时 reject。

try {
  const { banner } = await TudadaSDK.getBannerAsync('main_menu_top');
  renderBanner(banner.imageUrl);
} catch (e) {
  // 槽位无匹配广告 — 跳过渲染
}

`runBannerAction(options)`

用户点击横幅时由游戏调用。SDK 处理动作（深链接/外部链接等）并仅通知 success / fail 信号。

奖励等后处理在游戏内部完成。

选项：

参数	类型	必填	说明
`bannerId`	`string`	✅	兼作槽位名称的横幅 ID
`success`	`function`	-	成功回调 — 游戏发放奖励等后处理
`fail`	`function`	-	失败回调
`complete`	`function`	-	完成回调

img.onclick = () => {
  TudadaSDK.runBannerAction({
    bannerId: 'main_menu_top',
    success: () => {
      grantReward();   // 游戏侧奖励发放
    },
    fail: (err) => {
      showToast(err.errMsg);
    },
  });
};

`runBannerActionAsync(bannerId)`

runBannerAction() 的 Promise 版本。

img.onclick = async () => {
  try {
    await TudadaSDK.runBannerActionAsync('main_menu_top');
    grantReward();
  } catch (e) {
    showToast('处理失败');
  }
};

Ad API​

showRewardedAd(options) (推荐)​

showRewardedAdAsync(options)​

统一激励槽位​

getRewardedAdSlots(options?)​

getRewardedAdSlotsAsync()​

getRewardedAdSlot(options)​

getRewardedAdSlotAsync(slotId)​

createRewardedVideoAd(options) (旧版)​

横幅广告（槽位模型）​

getAvailableBannerIds(options)​

getAvailableBannerIdsAsync()​

getBanner(options)​

getBannerAsync(bannerId)​

runBannerAction(options)​

runBannerActionAsync(bannerId)​

Ad API

`showRewardedAd(options)` (推荐)

`showRewardedAdAsync(options)`

统一激励槽位

`getRewardedAdSlots(options?)`

`getRewardedAdSlotsAsync()`

`getRewardedAdSlot(options)`

`getRewardedAdSlotAsync(slotId)`

`createRewardedVideoAd(options)` (旧版)

横幅广告（槽位模型）

`getAvailableBannerIds(options)`

`getAvailableBannerIdsAsync()`

`getBanner(options)`

`getBannerAsync(bannerId)`

`runBannerAction(options)`

`runBannerActionAsync(bannerId)`