广告模块

本页介绍如何通过 Playol SDK 接入激励视频广告与普通插页广告，实现无痛变现、自动回流、平台代管的广告投放机制。无需接入第三方广告联盟，无需审批，无需账户结算，平台统一处理，开发者专注游戏本身即可。

---

📌 一、使用场景

• 激励广告：看完视频后获得奖励（复活、金币、道具、重试机会等）；
• 插页广告：过关、失败、暂停时展示普通广告，带来平台收益；
• SDK 内部自动判断广告是否填充、是否跳过、是否完成；
• 所有广告行为都会回调 afterAd，即使广告未填充或用户跳过，也保证回调安全触达；
• 所有广告收益归属当前游戏，统一由平台结算；
• 广告频率默认策略为每 30 秒间隔一次投放请求（由 Google 广告系统控制）。

---

🧩 二、方法与调用方式

🎥 打开奖励广告

openRewardAd(callbacks)

打开奖励广告，用户看完后可获得奖励

window.playolSDK.ad.openRewardAd({
  beforeAd: () => console.log('广告即将开始'),
  adViewed: (duration) => console.log('已完整观看广告:', duration, '秒'),
  adDismissed: (duration) => console.log('广告被跳过，观看时长:', duration, '秒'),
  afterAd: (res) => console.log('广告完成状态：', res)
})

📌 回调说明：

回调名	类型	说明
beforeAd	() => void	广告开始播放前触发
adViewed	(duration?: number)	完整观看广告后触发，附带观看时长（秒）
adDismissed	(duration?: number)	用户跳过广告后触发，附带已观看时长（秒）
afterAd	(msg: adMsg)	广告流程结束后始终调用，返回结构体包含状态与时长

📦 adMsg 结构体说明：

字段	类型	含义
status	-1/0/1	-1: 未填充 / 0: 跳过 / 1: 完整观看
msg	string	对应提示消息
duration	number?	观看时长（秒），部分状态下可能不存在

⚠️ 激励广告必须完整观看后再进行奖励发放，平台建议根据 status === 1 判断是否发奖。

---

📺 打开插页广告

openNormalAd(callbacks)

展示普通广告（无奖励），如关卡结束、暂停后

window.playolSDK.ad.openNormalAd({
  beforeAd: () => console.log('插页广告开始'),
  afterAd: (res) => console.log('广告结束状态：', res)
})

📌 说明：

• 普通广告不可跳过，仅记录展示行为，广告结束后统一回调 afterAd；
• 若广告未填充，也会走 afterAd 回调，开发者无需处理异常分支；

---

✅ 通用广告调用方式

openAd(adType, callbacks)

统一入口，传入广告类型：reward 或 normal

window.playolSDK.ad.openAd('reward', callbacks)

📦 adType 枚举说明：

值	含义
'reward'	激励广告
'normal'	普通插页广告

---

🧪 检测广告拦截

hasAdblock()

异步检测当前环境是否存在广告拦截器（如 AdBlock）

const isBlocked = await window.playolSDK.ad.hasAdblock()
if (isBlocked) {
  console.warn('检测到广告拦截器，建议提示用户关闭以支持开发者')
}

📌 **建议：**可限制特定功能（如皮肤、礼包等）鼓励用户关闭广告拦截；确保数据已保存，避免用户刷新时数据丢失。

---

🛠️ 三、推荐实践场景

场景	推荐调用方式
玩家失败后复活	openRewardAd()
关卡通关获得加成奖励	openRewardAd()
暂停后展示广告	openNormalAd()
检测用户屏蔽广告	hasAdblock()

---

📦 四、常见问题解答

Q: 广告播放失败是否会回调？

A: 会。无论广告是否存在或是否被跳过，都会触发 afterAd 回调，返回明确状态码。

Q: 广告播放频率是如何限制的？

A: 平台已在广告脚本中配置默认广告频率策略，如 30s 间隔一次填充请求。开发者无需控制频率，但应合理安排触发点。

Q: 广告收益怎么结算？

A: 所有广告收益由平台统一回流，结算周期与金额展示将在开发者平台提供。

Q: 广告接口是否支持 Promise？

A: 当前版本为回调式设计，后续将支持 Promise/async 调用形式。

---

🔗 相关文档推荐

👉 用户模块 ｜ 游戏模块 ｜ 支付模块 ｜ 邀请模块