分享、开放数据、权限与平台能力
适用:微信小游戏能力集成方法,客户端目标 Cocos Creator 3.8.8 + TypeScript。资料核查:2026-11-17。已核对 getPrivacySetting 接口原文及官方类型与示例;账号能力、权限及适用隐私义务仍须结合当前项目后台核验。
用能力矩阵替代接口清单
平台 API 很多,但游戏需要的是明确的玩家路径。把“接入分享”改写为“结算页提供分享入口,失败或取消不影响返回大厅”;把“接入排行榜”改写为“显示允许范围内的好友成绩,数据不可用时仍能看个人结果”。先描述触发点、输入、成功含义、失败行为、数据来源和所有者,再选择 API。否则容易实现了调用,却没有可用的完整流程。
能力矩阵至少按目标运行环境、最低支持条件、账号开通状态、授权条件和降级方式记录。函数在类型文件中出现,只证明某份接口资料包含它;账号具备能力、当前基础库支持和用户允许,是不同条件。不要把从其他项目复制的 AppID 或广告单元当作可复用配置,也不要把官方示例账号的能力当成自己的能力。
| 游戏目标 | 必须明确的问题 | 可观察结果 |
|---|---|---|
| 分享战绩 | 分享什么、从哪里进入、带何种参数 | 可进入合法落点,取消不发奖 |
| 好友排行 | 数据由谁写、在哪个上下文读取 | 空列表与失败均可返回 |
| 震动反馈 | 是否非关键、用户能否关闭 | 不支持时玩法仍成立 |
| 授权信息 | 功能是否确需、拒绝后如何继续 | 不反复强制弹窗 |
分享是入口设计,也是外部输入
分享消息携带的 query、邀请标识或关卡信息应作为不可信输入处理。落地时验证格式、长度、活动有效期和服务端资格,再决定路由。不要把客户端传来的邀请人标识直接当作奖励凭据;需要奖励时由服务端建立一次有效邀请关系,并按既定规则结算。分享打开、用户点击、实际完成目标是不同事件,不能用一个本地回调替代全部事实。
分享流程还涉及冷启动与前台恢复。冷启动时先完成最小初始化和登录,再处理待路由意图;已有战斗时收到邀请,要先决定是否允许离开当前局,而不是直接切场景。把入口意图存成待处理对象,并带去重标识,可以防止同一入口参数在多个恢复回调中重复执行。
type EntryIntent =
| { kind: 'home' }
| { kind: 'invite'; inviteId: string };
function parseEntry(query: Record<string, unknown>): EntryIntent {
const id = query.invite;
if (typeof id === 'string' && /^[A-Za-z0-9_-]{8,80}$/.test(id))
return { kind: 'invite', inviteId: id };
return { kind: 'home' };
}
// 格式通过后仍需由服务端校验邀请资格与有效期。
解析失败回首页是安全的体验回退,但要记录可分析的错误类别。不能在日志里保存所有原始 query,因为其中可能含渠道、用户或临时凭据。活动链接应关联版本和时效,旧链接进入时显示活动结束或可替代内容,不应加载不存在的场景后黑屏。
开放数据域的边界要显式保留
好友关系相关数据有平台定义的访问与展示边界。开放数据域可理解为受平台约束的独立上下文,主域通过允许的通信方式请求展示,由它处理被允许读取的数据。不要把它当作普通子模块,试图绕过边界导出全部好友资料。具体可读字段、写入条件和通信方式需要当前官方指南逐项核验。
工程上把排行做成一个拥有初始化、刷新、显示与销毁过程的独立界面。主域传递布局与展示意图,避免每帧发送大量消息;刷新需有频率和超时策略。展示区域的坐标、分辨率与触摸映射必须一致,否则排行榜看起来正确却点不中。空数据、未授权、网络失败和能力不可用应分别有合理界面。
自己的全服榜与好友榜不要共用含混的数据层。全服成绩可由业务服务验证和排序,好友榜遵守平台数据边界,二者的身份、实时性和权限不同。若要在同一页面切换,界面可以统一,但数据契约仍应清楚地说明成绩来源和刷新时点。
权限是持续状态,不是一次弹窗
用户可能首次拒绝、之后到设置修改,也可能在系统层关闭权限。每次使用敏感能力都应处理当下结果,不能只在首次启动记录 allowed=true 后永久信任。授权请求放在能解释用途的操作附近;不相关的关卡入口不应为了方便一次申请所有信息。拒绝后保留功能回退与重新尝试路径,避免循环弹出同一请求。
隐私告知与接口授权也不是同一个动作。实际采集字段、用途、传输对象、留存和删除机制要与声明一致。哪些接口需要何种处理属于动态政策,本节不根据类型名称猜测法律结论。上线时拿具体字段清单和用户路径,核对当前平台规范以及项目负责人的要求,不能只让 AI 生成一份泛用声明。
统一结果而不抹掉差异
平台适配器可以返回 success、cancelled、unsupported 与 failed 等业务结果,但仍应在诊断数据中保留原始错误码和阶段。取消是玩家选择,不一定应计为接口故障;不支持应触发降级;真正失败需要重试或提示。不要把所有异常转换成 false 后让上层猜测,也不要把完整平台对象泄漏到每个组件。
能力的初始化与销毁要有单一所有者。平台按钮、监听、开放数据展示对象可能不随 Cocos Node 销毁自动清理。连续进出排行或分享页面,观察监听数量、内存和点击回调次数。如果离开后还能响应,先检查资源所有权与解绑函数,而不是增加更多布尔开关。
能力接入完成要有退出证据
接入通常只展示成功截图,但平台对象最容易在退出时遗留。为每项能力写出离开页面、切后台、切账号和重复进入的行为:按钮是否消失、回调是否解绑、进行中结果是否仍应处理、旧身份数据是否清空。若一次能力请求跨过账号切换,即使返回成功,也不应把结果落到新账号的界面或资产。
这种退出契约可以直接复用到适配器测试。让替身在离开后返回成功,断言业务无新效果;再重新进入并返回当前结果,确保清理没有误伤正常流程。成功与退出都能解释,才算拥有完整的平台能力生命周期。
交给 AI 的任务与验收
可复制任务:“为结算分享与好友榜写能力矩阵,区分账号条件、运行时检测、用户授权和失败降级。实现入口参数解析、待处理意图及去重,主域业务不读取受限好友数据。输出冷启动、运行中邀请、拒绝授权、空榜与失败的界面流程,未知政策列待核查。”
验收畸形 query 只能进入合法路径;同一邀请不重复处理;取消分享不改变经济资产;排行失败仍可返回;退出界面不遗留平台按钮或监听。接口签名可以静态检查,真实授权与开放数据展示必须留真机证据。
官方来源与限制
- 微信官方能力示例:分享、登录与开放数据域等示例入口,不代表当前项目已获准使用。
- 微信官方 API 类型仓库:接口与回调结构,核查提交 42c427aa8c3961b7a4f8ea5bd6112c2bcf058177。
- 微信隐私设置接口入口:本次不可抓取,权限政策须人工核对;本文流程为工程设计建议。