---
name: ineed-rewarded-ads
description: 为游戏接入按动作结算的激励广告，检查平台开通状态、真实完成凭据、奖励去重和取消恢复。
---
# 激励广告

通用激励广告需要平台为作品启用可信供应商、广告位和结算记录。SDK 中有方法并不表示已经开通。普通展示广告的位置需求与激励奖励分开记录。

## 需要创作者与平台确认

创作者确认 placement、按钮位置、触发时机、奖励内容/数量、适用动作以及失败时是否有其他选择；价格和奖励不得由 AI 擅自决定。平台确认广告位已启用、供应商实际填充、reward 字段结构、环境及可信完成验证。需要冷却或每日限制时列为明确配置需求，不编造 SDK 参数。

## 调用和应用顺序

1. initialize 后检查 supports("ads.rewarded")。未开通禁用或隐藏“看广告领奖”，明确提示暂不可用，不用假进度条模拟广告。
2. 需要账号时先 ensure_logged_in。玩家点击后为本次奖励动作生成并保存 actionId，16–80 位字母/数字/_/-；重试同一动作保持此 ID，另一局或另一奖励用新 ID。
3. `await INeed.show_rewarded(placement, action_id)`。平台暂停事件进入时保存游戏/音频状态，结束恢复原状态。
4. 只有 ok=true 且 value 的 receiptId/actionId/placement 与待处理动作一致才进入奖励处理。reward 按与平台约定的字段解释；不能假定所有广告都返回 coins。
5. 对 receiptId 去重，将“奖励已应用”与游戏对应状态一起保存；相同回执只恢复原结果，不再次加数值。replayed 标记表示平台重复返回同一结算，不是新奖励。

## 奖励的权威边界

平台验证真实完成并持久化一次性回执；这不意味着平台自动修改任意游戏金币。可消费资产和真实经济权益以服务端账本为准；如果需要广告自动发放某个商品，必须由平台确认对应服务端发放实现，不能拿本地存档布尔值代替。

浏览器发出的“播放完毕”、计时器结束、关闭窗口、旧访问解锁 token 都不是通用发奖依据。模拟供应商仅可用于隔离测试。预览不能写入正式奖励。

## 取消和未知结果

CANCELLED、NO_FILL、EXPIRED、PROVIDER_ERROR 或其他失败不发奖。TIMEOUT 表示结果未知，保留 actionId，人工重试恢复同一动作；不要立刻新建动作。奖励应用前账号变更应停止，不能把 A 的回执给 B。广告关闭后恢复原有暂停/音频状态，不自动把原先静音的游戏打开声音。

## 验收与交接

记录入口路径、placement、actionId、receiptId、平台配置的 reward 和环境。测试未开通、无填充、取消、真实完成、重复完成/领取、刷新恢复、账号切换和存档冲突。不能用模拟成功报告真实广告验收通过。参见[接口手册](../../../guides/integration/api.md)与[平台交接单](../../platform-handoff/SKILL.md)。