跳到主要内容

广告、支付与奖励一致性

适用:微信小游戏变现流程与服务端一致性,示例 TypeScript;客户端接入目标 Cocos Creator 3.8.8。资料核查:2026-11-17。已读取激励广告、服务端验证和虚拟支付技术手册的官方原文,并与官方类型及示例交叉核对。下文区分已核实的接口机制与工程方案;本项目账号准入、后台开通、分成与审核条件仍未确认,未进行真实交易或广告验证。

接口调用与商业资格是两条检查线​

先确认项目主体、游戏类目、目标系统、账号后台能力和当前政策,再决定产品中是否展示某类变现入口。类型文件里有 requestMidasPayment,不等于所有账号或所有设备都可调用。广告组件能创建,也不保证有填充或广告单元已可用。课程可以讲可靠流程,却不能用历史经验替代当前后台事实。

技术集成前写一张核查表:能力名称、当前官方页面、核查日期、账号状态、适用环境、审核要求和负责人。尚未确认就标未知,并保留不可用时的正常游戏路径。不要让 AI 从旧文章补齐门槛数字,也不要把官方示例里的广告单元或支付参数复制成正式配置。

激励广告是有明确终态的会话​

一次展示有准备、加载、可展示、展示中、完成、提前关闭、失败等阶段。show() 返回广告显示操作的 Promise,不能直接等同于完整观看。onClose 的 isEnded 表示是否完整观看后关闭,该字段从基础库 2.1.0 开始支持。业务按已核实的完成信号判断;缺失或无法识别的结果应按未确认处理,不能为了兼容一律发奖。

type AdResult = 'completed' | 'cancelled' | 'failed';
class OneAdAttempt {
private ended = false;
constructor(private finish: (result: AdResult) => void) {}
settle(result: AdResult) {
if (this.ended) return;
this.ended = true;
this.finish(result);
}
}
// onClose 在 show 前绑定;完成、错误、取消等路径都经过 settle。
// 离开页面时清理监听;不要让超时后的迟到回调重启已关闭流程。

示例只控制一次本地展示的结束,不证明广告真实观看,也不直接发放经济资产。监听在展示前建立,结束时解除自己注册的处理器,重复点击共享或拒绝同一进行中尝试。错误后可以按策略重新加载,但不要无上限 load/show 循环。广告不可用与用户提前关闭是不同结果,应给出不同反馈。

展示期间如何暂停战斗、音效和输入也要明确。暂停只属于客户端体验,服务器实时房间未必暂停;本地闯关可冻结适当模拟,返回时恢复到约定阶段。用户切后台、页面被关闭、场景已销毁时,旧广告回调不能再修改失效节点。将广告尝试关联到当前局与界面世代,而不只保留一个全局 isWatching。

奖励资格与到账要由业务流程控制​

复活前可由服务端签发本局一次性资格,完成后提交领取意图,服务端验证局状态、次数与幂等业务键后发放。若只有客户端完成回调,服务端无法仅凭客户端声称就证明真实观看;资格与限流只降低滥用,不应被描述为完整防作弊证明。

微信已提供可选的激励广告服务端验证,要求基础库至少 3.10.3,并在流量主后台开启、配置服务端回调。setServerSideVerificationData 必须在 show() 前调用,透传用户、奖励与自定义数据;这些客户端字段本身不是可信奖励凭据。服务端仍需按官方协议验签、解密、绑定当前业务资格,并对每个奖励事件的 transaction_id 做幂等处理。

服务端回调可能比前端回调晚到,也可能重试。官方允许先按前端结果发放再验证,或重要奖励等待服务端验证;本项目应明确选择其中一种,并说明等待、补发与异常处理。不能把两个回调当作两次奖励,也不能把“有服务端接口”写成当前账号已经开通。

对低价值奖励,团队可接受一定客户端信任与成本取舍,但要明确风险;对可交易或高价值资产,应重新评估验证强度。广告“完成”到奖励“到账”可能跨网络,UI 可显示确认中。响应丢失时查询同一 operationId 的结果,不能生成新意图重复加奖励。广告收益记录、奖励账本和玩家展示也不应混为同一计数。

支付是订单状态机,不是一个回调​

支付流程先由服务端根据商品配置创建订单,固定用户、商品、数量、金额或计价单位与配置版本。客户端只发起购买意图并调用经当前平台确认的支付能力,不能自行决定实际价格。订单创建、拉起支付、平台确认、发货完成是不同状态;取消和失败也不应误显示已购买。

微信虚拟支付技术手册区分两条通路:游戏币充值使用 wx.requestMidasPayment,游戏币由平台发到托管账户,客户端返回后应查询余额;道具直购使用 wx.requestMidasPaymentGameItem,由平台向开发者服务端推送发货通知,开发者负责发道具。不要把两者当成同一套“支付成功后本地加资产”的接口。

服务端按平台当前协议验证可信通知或查询结果,再在事务内记录发货与账本。客户端支付成功回调最多触发主动查询,不能作为唯一发货依据。通知可能重复、乱序或延迟,订单唯一标识、状态转移和幂等发货缺一不可。客户端退出后,订单仍需能在服务端完成,并在下一次登录恢复资产。

道具直购需要开启发货推送,相同 outTradeNo 的重复通知只能发货一次,并返回相同的成功结果。用托管游戏币兑换道具时,应以服务端扣币成功为发货依据;同一扣币意图重试保留同一个 bill_no。平台手册写明该扣币接口的同号幂等窗口为 48 小时,业务仍需保存自己的订单与账本,不能把超过窗口后的请求当成安全重试。这里的 bill_no、支付订单号和广告奖励事件号属于不同协议,不可混用。

created → awaiting_platform → confirmed → fulfilled
↘ cancelled / expired
confirmed 后重复确认:返回原结果
fulfilled 后重复通知:不再次写入资产
状态未知:查询平台与订单记录,不猜测成功或失败

不同支付产品的签名、通知、查询与退款机制不相同,不能用一套伪造字段冒充通用微信支付实现。先选定当前获准的产品,再按其官方服务端协议编码与测试。退款后的资产处理、已消费物品与负余额策略属于产品和财务规则,也要进入状态机,不能只在退款接口成功后删一条订单。

用账本解释争议,用故障注入证明一致​

支付排查保留脱敏订单标识、平台交易关联、状态时间线与发货凭据,避免记录密钥和完整敏感响应。玩家说扣款未到账时,先查可信支付状态,再查发货事务与资产版本;不要让客户端重复购买来试探。广告未得奖励则查展示终态、资格状态和领取结果,分清未完成、未确认与已发但未展示。

测试包括广告加载失败、提前关闭、重复关闭、切场景后迟到、支付取消、通知重复、提交后响应丢失与客户端终止。浏览器替身可以证明业务状态机,不能证明真实广告填充、支付资格或实际到账。涉及真实资金的验证应使用平台当前支持的测试方式与明确项目授权。

交给 AI 的任务与验收​

可复制任务:“设计激励复活与商品购买两条状态机。广告完成信号仅作为客户端观察,奖励领取由服务端资格和幂等约束控制;订单发货必须依可信支付确认。实现替身覆盖取消、重复回调、未知结果和响应丢失,不填广告支付准入数字,不编造平台签名字段。”

验收提前关闭不发奖;重复回调只结算一次;切场景后不访问旧节点;客户端伪造支付成功不发货;可信通知重复只产生一笔资产变更;客户端重启可查原订单。商业能力是否开通与真实交易结果另外留证。

官方来源与核查边界​