登录、支付、社交与广告 SDK

Category

industry / platforms 子树。节点定位：四类 SDK 性质不同——失败代价、出错位置、架构要求各异；隔离层是第一原则。

Definition

平台 SDK 通常被当成一类东西来管理，实际上登录、支付、社交、广告四类 SDK 的性质差别很大：登录关乎身份与合规，支付关乎资金与对账，社交关乎传播与关系链，广告关乎变现与风控。它们的失败代价不同、出问题的位置不同、对架构的要求也不同。把它们混在一起按“接几个 SDK”来排期，往往低估了支付链路的严谨性要求和高估了社交链路的技术难度。

Problem

按「接几个 SDK」排期会低估支付链路的严谨性要求、高估社交链路的技术难度：登录关乎身份合规、支付关乎资金对账、社交关乎传播、广告关乎变现风控。没有隔离层，任何一家的升级或弃用都是全项目事件。

四类 SDK 的失败代价不一样

先分清每类 SDK 出错时的代价，集成策略才有依据。

• 登录失败的代价是进不了游戏，通常可以重试或降级为游客，业务损失有限但发生频率最高。
• 支付失败的代价是真金白银，掉单、重复发货、金额错误每一样都是资损与客诉，但发生频率相对低。
• 社交分享失败的代价是传播效果打折，玩家几乎没有感知，值得优化但不值得牺牲主流程稳定性。
• 广告失败的代价是变现收入损失，激励视频拉取失败还伴随玩家“看了广告没拿到奖励”的强客诉风险。

代价与频率的组合决定了投入分布：支付链路要按最严谨的标准建设，登录链路要按最高频的标准做降级，社交与广告则要处理好“失败但不伤主流程”的体验。很多项目的集成混乱，根源就是用同一套松散标准对待了这四类完全不同的东西。

隔离层为什么是第一原则

SDK 集成最常见的结构问题是调用散落：界面代码里直接调用平台登录、业务逻辑里直接拼接支付参数、到处都是对特定 SDK 全局对象的引用。短期看省事，长期看每次 SDK 升级、每个渠道差异、每个平台特有问题都会穿透到核心代码。

常见做法是在项目内部定义一套稳定的平台能力接口，登录、支付、分享、广告各一套，SDK 的具体调用全部收口到适配实现里。核心逻辑只依赖自己定义的接口，平台差异、SDK 版本差异、渠道差异都被压进适配层。这样做的额外收益也很实在：

• 适配层可以提供空实现或模拟实现，让客户端在无 SDK 环境下开发和测试。
• 每次调用经过收口层，可以统一记录成功率、耗时与错误码，SDK 的健康状况从此可观测。
• 平台 A 的特有坑被隔离在 A 的适配器里，不会污染其他平台。

隔离层的接口设计以自己项目的语义为准，而不是照抄某个 SDK 的接口形状，否则只是把依赖换了个位置。

登录 SDK：身份锚点与会话边界

登录集成的核心不是调用哪个接口，而是想清楚身份模型。平台身份是入口，游戏内账号与资产归属才是自己的权威记录，两者之间需要一张明确的绑定关系，而不是默认一对一。多端发行时这个设计尤其关键：同一个玩家在不同平台拿到的身份标识互不相通，跨端锚点要在立项时确认可用性，事后靠手机号之类的方式补绑，代价是整整一个运营周期的账号割裂。

会话设计上常见的要点有几条：

• 游戏自己的会话与平台会话是两条生命周期，过期、续期、踢人各自独立处理。
• 游客身份要支持后续升级绑定，绑定时的账号合并冲突要有预案，让玩家选择通常比后台自动合并更不容易产生客诉。
• 登录链路里依赖平台服务端的换取步骤是外部调用，要有超时、重试与明确的失败提示。
• 登录接口按幂等设计，重复点击与断线重连的并发请求不应产生重复账号。

支付 SDK：订单状态机与对账

支付是四类 SDK 里对严谨性要求最高的一类。可靠的支付集成通常围绕一张订单状态机展开：下单、支付中、已支付待发货、已发货、已关闭，每个状态迁移有明确的触发方与凭证。客户端的支付成功回执只用于优化体验，发货依据永远是服务端收到的平台通知或主动查单结果。

几个反复被验证的实践：

• 平台通知按幂等处理，重复通知、乱序通知不产生重复发货与状态回退。
• 主动查单兜底：通知可能丢失，未闭环的订单要有定时任务去平台核对状态。
• 定期对账：用自己的订单表和平台的账单核对，差异订单进入人工或自动补偿流程。
• 金额与商品信息在下单时由服务端确定，不信任客户端上报的价格与数量。

掉单是必然会发生的事，方案的意义是让掉单可发现、可定位、可补偿。玩家投诉“付了钱没到账”时，客服要能顺着订单号看到它停在哪一步、缺哪个凭证，而不是在日志里大海捞针。

社交 SDK：借来的关系链

社交类 SDK 提供分享、邀请、好友关系等能力，工程上最容易犯的错是把主流程绑定在不可靠的回调上。分享是否成功、玩家是否真的完成了邀请，这些信号的可信度远比表面上低：回调可能丢失，可能被伪造，平台口径也可能变化。

稳妥的设计原则是把社交能力当传播通道，而不是当结算依据：

• 分享奖励的发放以服务端可验证的事件为准，配频控与风控，而不是无条件相信客户端回调。
• 邀请归因绑定在服务端，防止刷邀请奖励的脚本批量套利。
• 好友关系区分来源，平台好友关系是借来的，规则由平台定；游戏内社交关系要自建，是资产与玩法的基础。
• 分享内容与落地页属于平台审核范围，改文案也可能需要重新过审，排期上要留这个余量。

广告 SDK：变现链路与发奖可信

激励视频是小游戏与休闲产品的重要收入来源，它的链路比看上去长：拉取、展示、关闭、结算，任何一环都可能失败。玩家视角只有一件事——看完广告该拿奖励。所以广告集成的核心矛盾是变现体验与发奖可信的平衡。

常见做法是发奖以广告平台的服务端回调为准，客户端回调只用于推进界面流程；服务端回调要验签，防止伪造回调刷奖励。拉取失败要有体验兜底：提示稍后再试、提供替代奖励或调整玩法入口，避免玩家卡在一个永远转圈广告位上。广告 SDK 本身的体积与初始化时机也值得管理，粗暴的同步初始化会拖慢启动，而启动速度直接影响买量转化。广告填充率、拉取耗时、回调到达率这些指标应该进监控，变现收入异常波动时才有据可查。

降级路径与失败体验

SDK 都会失败，区别只在于失败时玩家看到什么。降级设计的目标是让失败局部化：一个 SDK 的故障不应该拖住整个游戏。

• 登录失败降级到重试或游客模式，同时保住升级绑定的入口。
• 支付失败时订单要留存，界面给出明确状态与后续处理路径，而不是让玩家不知道钱去了哪里。
• 广告失败走替代奖励或延迟入口，主玩法不依赖广告成功。
• 分享失败静默降级，不打断操作流程。

降级的另一个层面是启动隔离。SDK 初始化失败曾经是整包启动失败的高发原因，把各 SDK 的初始化做成异步且互相独立，单个 SDK 异常不再阻断进入游戏。SDK 的崩溃率与错误率按版本监控，某个版本 SDK 质量异常时能及时发现并回退。

SDK 版本升级与弃用周期

平台 SDK 处在持续演进中：接口会弃用，版本会强制最低要求，行为会悄悄变化。长期项目几乎一定会经历几次被迫升级，升级窗口往往又和审核周期绑在一起，排期被动。

值得提前做的准备有三件。其一，把 SDK 版本与适配层版本记录在案，知道每个平台每个版本用的什么、改过什么。其二，升级前在隔离分支上做完整回归，SDK 升级引入的行为变化经常不在更新公告里。其三，关注平台的弃用公告，给老接口的替换留出至少一个版本周期的余量，而不是等到强制下线那天。SDK 治理没有多难，难的是它永远不紧急，直到突然变得非常紧急。

SDK 的合规与隐私申报

集成第三方 SDK 还有一层容易被忽略的义务：SDK 会收集什么数据、用于什么目的，需要在隐私政策里披露，部分平台还要求提交第三方 SDK 清单。广告与归因类 SDK 通常是收集敏感度最高的，漏申报的合规风险比技术风险更大。

常见做法是维护一份 SDK 台账：每个 SDK 的提供方、版本、用途、收集的数据类别、初始化时机。接新 SDK 时先过台账评估，下线 SDK 时确认数据收集同步停止。这件事与技术治理共享同一份基础设施，投入增量很小。

常见误区

• 用同一套松散标准对待四类 SDK，支付链路不够严谨，社交链路过度设计。
• SDK 调用散落在业务代码里，升级一次 SDK 变成全工程回归。
• 把客户端支付回执当发货依据，缺少服务端通知、幂等与对账，掉单变资损。
• 把奖励结算绑定在分享或广告的客户端回调上，被伪造回调批量套利。
• 单个 SDK 初始化失败拖垮整包启动，故障面远大于故障点。
• 只在出事时才关心 SDK 版本，弃用公告没人看，被迫升级时排期全面被动。

SDK 集成的成熟度，看的不是接了多少家，而是失败时的表现：登录失败有没有出口，支付失败有没有订单可查，广告失败有没有替代路径。把这些失败路径设计好，SDK 才真正从风险变成能力。

Used By

SDK 接入评审（分类分级）；隔离层设计；SDK 升级与合规管理。

Related

关系链：四类分性 → 隔离层 → 各类要点 → 降级路径 → 升级合规。上游：platforms/01。下游：models/06（平台型问题模型）。

Reference

本页为工程经验归纳。