跨平台防沉迷SDK接入实战：Android、iOS与Unity桥接全解析

简介：面向安卓毕设与移动游戏开发者的手机游戏防沉迷系统SDK，同时支持iOS、安卓及Unity平台，提供快速接入方案。该SDK适用于需要实现实名认证、时长限制、宵禁等合规功能的游戏项目，尤其适合作为毕业设计、课程设计或工程实训的完整参考，同时也可用于普通游戏项目的合规功能开发。资源包共331个文件，包含Swift、Java、Objective-C等平台源码，以及Unity集成配置、安卓工程文件、iOS属性列表与故事板等，还覆盖了元数据、构建脚本和多种工程配置，整体压缩包仅10.8兆字节，结构清晰，便于理解和二次开发。目前已有48人学习浏览，源码经过严格测试可运行，并附有防沉迷业务逻辑说明与接入示例，可直接修改复刻到自有项目中，也可作为学习游戏合规开发的入门到进阶素材。注意：资源仅限开源学习与技术交流，不可商用。

1. 防沉迷 SDK 到底在防什么：不是"限时"两个字那么简单

很多做游戏方向毕设的同学，拿到"防沉迷系统 SDK"这个题目，脑子里只有两个字：限时。等真接进去才发现，限时只是最表层的那一层。真正让人熬夜的，是实名认证怎么拉起、游客身份怎么识别、设备时间被改了怎么办、Android 的回调在 Unity 里为什么收不到、iOS 桥接里的 DllImport 为什么一进真机就崩。这篇按我实际接过的跨平台 SDK 方案，把这个 ZIP 包背后的架构、Android 端接入步骤、Unity 桥接写法、iOS 侧接口和几个必踩的坑完整拆一遍。适合两类人：一类是拿它做毕设、需要快速跑通并且能讲清楚原理的学生；另一类是游戏小团队想低成本接入防沉迷能力，又不想从零写实名和时长服务的开发者。

2. 先看架构再做毕设：客户端采集、服务端判定、双端同步的三角关系

2.1 三条红线：实名、宵禁、时长，SDK 把哪一层逻辑放在端上

防沉迷系统在业务上通常拆成三条线：实名认证、时段限制、累计时长限制。实名认证解决"你是谁"，时段限制解决"什么时间不能玩"，时长限制解决"能玩多久"。这三条线不是平行并列的，而是有先后依赖的：先实名，再判断时段，最后在运行过程中持续累计时长。很多毕设文档把这三件事写成一堆状态码，但从不提每一层到底跑在端上还是服务端，结果答辩被问一句就卡住。

常见做法是，SDK 落地时把这套能力切成两个平面。端上（Android/iOS/Unity）负责四件事：拉起实名界面、采集用户标识和设备信息、把心跳和查询结果缓存下来、把服务端下发的策略翻译成游戏 UI 看得懂的文案。服务端负责三件事：身份核验、在统一时间轴里累计在线时长、把"是否受限/剩余时长"算好再下发给端上。也就是说，SDK 客户端本身不做裁决，只做采集、展示和上报。

这个切分在接口设计上会非常明显。我一般会把 SDK 暴露给游戏方的主接口控在五个以内，而不是开放一堆细粒度方法让人随便调：

这五个接口在 Android、iOS、Unity 三端同名同参数，只是底层实现不一样。把接口收敛到五个，游戏方接入时学习成本低，你写毕设文档也容易把"接入流程"讲成一条直线，而不是一堆散点。

提示：有些 SDK 会把 queryPlayState 和 realNameAuth 合并成一个"进入游戏前的统一检查"，减少一次异步往返。毕设里拆开写更清楚，方便拿接口时序图去讲。

2.2 为什么必须服务端判定：本地时钟和存档都是不可信的

第一版毕设最容易犯的错，是把这个系统做成"纯本地判定"：读一下系统时间，算一算今天玩了多久，超了就锁。这个方案在演示视频里跑得很顺，但有一个致命前提——设备时间和本地存储都是玩家可控的。改系统时间、清掉应用数据、卸载重装，任何一项都能让计时归零。手机游戏面向的是真实玩家，不是教学演示环境，所以真正能立住的防沉迷 SDK，时长账本必须记在服务端。

服务端判定带来一个衔接问题：端上怎么让服务端知道"这个用户在线"？主流做法是心跳上报。游戏客户端在运行期间每 30 到 60 秒向服务端发一次心跳，服务端按用户 ID 累计在线时长，游戏进程被切到后台或崩溃时心跳中断，计时自然停住。这个机制比"退出时上报时长"可靠得多，因为玩家进程被杀掉的那一下，往往没有机会执行任何清理代码。

那么端上还剩什么可做的？主要是容灾和体验。常见做法是：查询请求失败时，端上先用本地缓存的策略放行或拦截，同时标记"数据待同步"；心跳连续失败三次，端上弹一个弱网提示，而不是直接踢人。这样既保证了服务端是权威裁决者，又不会因为一次网络抖动就把玩家挡在门外。这一层在毕设答辩里非常值钱，因为它体现的是工程思维，不是背概念。

2.3 SDK 的跨平台封装思路：Android/iOS 各自实现，Unity 走 C# 桥接

标题里写了"iOS+Android+Unity"，这是这类毕设项目最典型的跨平台结构。它并不是用一个跨端框架写三份 UI，而是三个端各自独立实现核心逻辑，再在同一套接口约定下对齐行为。Android 端以 AAR/JAR 形式提供，iOS 端以静态库加 Objective-C 头文件提供，Unity 端通过 C# 的 AndroidJavaObject 和 DllImport 分别桥接到前两者。

为什么 Unity 不直接用 C++ 写一套核心到处编译？因为防沉迷 SDK 要用的实名认证能力，在 Android 和 iOS 上都是以系统级 SDK 和服务的形式开放的，C++ 层拿不到完整的生命周期和系统 UI 能力。与其在 C++ 里再造一层，不如让各端原生实现，Unity 只在边界做薄薄的桥接。

桥接层要解决三个具体问题：一是方法调用从 C# 到原生的参数传递；二是原生回调到 C# 的事件投递，Android 用 UnityPlayer 的当前 Activity，iOS 用 UnitySendMessage；三是生命周期同步，Unity 的 OnApplicationPause 要能触发 SDK 的心跳暂停和恢复。这三个问题解决了，三端的接入体验才能做到"同一套代码，三种端"。

3. Android 端接入实操：从解压 ZIP 到跑通实名认证回调

3.1 工程引入与初始化：把 SDK 包放进项目的正确姿势

拿到 ZIP 解压后，先确认里面有哪几样东西：Android 的 AAR 或 JAR、iOS 的 framework 或静态库、Unity 的 .unitypackage 或桥接脚本、以及一个 Demo 工程。最容易踩的坑是直接把 AAR 拖进 Android Studio 就算完事，等构建报错才回头来配依赖。正确姿势是把 AAR 放进 app/libs 目录，然后在模块的 build.gradle 里显式加一句依赖并同步。

dependencies { implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar']) implementation 'androidx.appcompat:appcompat:1.6.1' }

这段配置做了两件事：fileTree 把 libs 下所有 jar 和 aar 都纳入编译，appcompat 是 SDK 里实名界面通常要用的 AndroidX 基础库。注意 implementation 与 api 的区别，如果你的工程里还有别的模块要调 SDK 的类型，这里应该用 api，否则只能在当前模块里用。初始化的时机建议放在 Application 的 onCreate 里，要传的配置包括 AppId、渠道号和一个是否开启调试日志的开关。

AntiConfig config = new AntiConfig.Builder() .setAppId("10086") .setChannelId("myself") .setDebug(BuildConfig.DEBUG) .build(); AntiAddictionSDK.init(this, config); AntiAddictionSDK.setGlobalCallback(new AntiCallback() { @Override public void onAuthResult(int resultCode, String userId) { // resultCode 为 0 表示认证通过，非 0 是失败或取消 } });

这段代码里的 Builder 模式把配置项集中管理，setDebug 决定 SDK 内部日志是否输出到 Logcat，排查问题的时候必须打开。init 传入的 this 是 Application 上下文，不是 Activity，这一点重要——因为 SDK 内部要用这个上下文启动实名界面，传 Activity 会导致界面栈错乱，比如从后台恢复时直接顶到最上层。setGlobalCallback 注册的是全局回调，游戏登录前后都能收。

3.2 实名认证与防沉迷查询：四个核心 API 的调用顺序

接入时最被高估的是实名认证本身，最被低估的是调用顺序。总结一句话：先查状态，再决定要不要实名，实名完必须再查一次，最后进入心跳循环。顺序错了，就会出现"实名通过了但时长还是按游客算"的翻车现场。

// 1. 进入游戏前查询 AntiAddictionSDK.queryPlayState(userId, new PlayStateCallback() { @Override public void onResult(PlayState state) { if (state.isRestricted()) { // 弹受限提示，限制进入 } else { // 放行，开始心跳 } } }); // 2. 需要在界面上实人认证时 AntiAddictionSDK.realNameAuth(activity, new AuthCallback() { @Override public void onResult(int code, String userId) { // 认证成功后，必须重新查一次状态 } }); // 3. 放行后，每 30 秒心跳一次 Timer timer = new Timer(); timer.schedule(new TimerTask() { @Override public void run() { AntiAddictionSDK.heartbeat(); } }, 0, 30_000L);

这里 queryPlayState 拿到的 PlayState 里至少有三个字段：restricted 是否受限、remainSeconds 剩余可玩秒数、curfew 是否处于宵禁时段。核心逻辑是：restricted 为 true 时禁止进入，curfew 为 true 时提示"当前时段无法游戏"，remainSeconds 用于界面上倒计时。realNameAuth 的 activity 参数必须是当前位于栈顶的 Activity，否则实名界面拉不起来。认证成功后重新 query 一次的原因，是让服务端重新计算这个用户新的策略，而不是沿用游客时期的限制。

注意：心跳间隔不要小于 10 秒，否则服务端会认为请求频率异常，直接限流；也不要大于 90 秒，否则玩家退出到桌面后计时不会及时停止，时长会多算。30 秒是大多数接入方都在用的折中值。

3.3 用 Demo 验证接入：构建前必须检查的三处配置

ZIP 里通常会带一个 Demo 工程，别急着当黑匣子跑，先检查三处配置，改完再构建，能省掉后面所有求救时间。

第一处是 AndroidManifest.xml。SDK 的实名界面 Activity 必须在清单里注册，如果是通过 manifest 占位符自动合并的，也要确认 application 节点下有对应 activity 声明。第二处是混淆规则，release 构建要加上 keep 规则，否则 SDK 内部通过反射回调的方法被混淆后，回调会静默失败，界面正常、逻辑不跑，非常难排查。第三处是 minSdkVersion，这类 SDK 用到的新 API 一般要求 API 21 以上，把 minSdk 设到 21 或更保守的版本，能避免一堆兼容性问题。

-keep class com.example.antisdk.** { *; } -keepclassmembers class com.example.antisdk.** { public *; }

这段混淆规则表示 SDK 包名下所有类都不参与混淆，特别是反射调用到的回调方法。release 包用 APK Analyzer 检查一下，如果发现 AntiAddictionSDK 类路径变了，说明规则没生效，回到配置文件里看是不是包名写错。

三处配置检查完，用 Demo 自己的签名跑一遍登录，记住一个验证方法：打开 Logcat，过滤 SDK 文档里指定的 Tag，能看到完整的认证链路日志。这条日志链是后面所有排查的地基，跑通以前不要动任何业务代码。

4. Unity 桥接与 iOS 接入：同一套业务逻辑，三种端各自怎么写

4.1 Unity 侧调 Android 的两种方式：JNI 直调与 AAR 封装

Unity 工程接入 Android SDK，常见做法有两种。第一种是 C# 里直接用 AndroidJavaClass / AndroidJavaObject 反射 Java 层，适合快速验证；第二种是把 Android 的 AAR 封装成 Unity 插件，专门暴露 C# 接口，适合正式打包。毕设里我建议先用第一种跑通，再用第二种把接口收敛成静态方法，答辩论证的时候可以说"我们用统一桥接层隔离了平台差异"。

using UnityEngine; public class AntiAddictionBridge { private const string SDK_CLASS = "com.example.antisdk.AntiAddictionSDK"; public static void Init(string appId, string channelId) { #if UNITY_ANDROID && !UNITY_EDITOR using (var sdk = new AndroidJavaClass(SDK_CLASS)) { using (var config = new AndroidJavaObject( "com.example.antisdk.AntiConfig", appId, channelId)) using (var activity = GetUnityActivity()) { sdk.CallStatic("init", activity, config); } } #endif } private static AndroidJavaObject GetUnityActivity() { using (var unityPlayer = new AndroidJavaClass("com.unity3d.player.UnityPlayer")) { return unityPlayer.GetStatic<AndroidJavaObject>("currentActivity"); } } }

这段代码里最关键的是 GetUnityActivity。Unity 的 Activity 对象不是自己 new 出来的，必须从 UnityPlayer.currentActivity 拿，否则实名界面无法依附正确的窗口。CallStatic 对应 SDK 里的静态方法 init，参数顺序要和 Java 层完全一致。每一层 using 负责释放 AndroidJavaObject 的引用，Unity 里不释放这些对象会在长时间运行后积累 JNI 全局引用，触发引用上限的崩溃，别小看这个细节。

4.2 iOS 侧接口：从 Unity 工程挂 Objective-C 桥接到原生回调

iOS 侧没有 Android 的 JNI 反射机制，Unity 调原生走的是 DllImport 加 extern "C" 符号导出。具体做法是：在 Unity 工程的 Assets/Plugins/iOS 目录下放一个 .mm 文件，里面写好 C 接口，再用 [DllImport("__Internal")] 在 C# 里声明同签名的外部方法。

#import "AntiAddictionSDK.h" extern "C" { void AntiSDK_Init(const char* appId, const char* channelId, const char* gameObjectName) { NSString* nsAppId = [NSString stringWithUTF8String:appId]; NSString* nsGameObject = [NSString stringWithUTF8String:gameObjectName]; [[AntiAddictionSDK sharedInstance] initSDKWithAppId:nsAppId channelId:channelId ? [NSString stringWithUTF8String:channelId] : @"" callback:^(NSInteger code, NSString* userId) { NSString* param = [NSString stringWithFormat:@"%ld|%@", (long)code, userId]; UnitySendMessage([nsGameObject UTF8String], "OnAuthResult", [param UTF8String]); }]; } }

这段代码里有三个关键点。第一，extern "C" 保证函数名不被 C++ 编译器修饰，C# 侧才能按 AntiSDK_Init 找到符号。第二，char* 转 NSString 的写法是所有字符串参数的通用模板，nil 检查不能省。第三，UnitySendMessage 是原生侧向 Unity 回传数据的通道，三个参数分别是 GameObject 名字、方法名和参数字符串，C# 侧要先建一个常驻 GameObject，挂一个接收方法，名字拼错或方法名拼错都会静默丢消息。另外要记住，UnitySendMessage 必须从主线程调用，在后台队列里调用会导致真机闪退，这也是 iOS 桥接最常见的崩溃原因之一。

4.3 时间校准与心跳上报：三端差异集中在哪几个文件

三端接入之后，最容易出现"iOS 正常、Android 正常、Unity 打包出来不正常"的地方，是时间基准和心跳生命周期。原因非常朴素：Unity 的 OnApplicationPause 和 Android/iOS 原生的生命周期不是一一对应的，切后台、来电、锁屏在同一种设备上有时候只能触发其中一个回调。

统一时间基准的办法是：SDK 内部一律使用服务端下发的 UTC 时间戳作为"当前时间"，本地系统时间只用来做界面展示和心跳间隔计算。这样做的原因是防沉迷的时段和时长判定，和玩家设备时区没有关系——你人在东八区也好、在东二区也好，服务端拿的是同一个 UTC 时间轴。毕设里做这个设计，能顺便把"时区导致跨天重算"的坑从源头上堵死。

心跳的启停建议放在 Unity 的生命周期脚本里统一管理。OnApplicationPause(true) 时停掉心跳并主动上报一次"暂停"，OnApplicationFocus 恢复时重新开始心跳。Android 和 iOS 各自的 SDK 内部也要有同样的处理，否则 Unity 打包后切后台，时长会一直累计到服务端超时踢人。三端差异最后收敛到三个文件：Android 的 Bridge.java、iOS 的 Bridge.mm、Unity 的 AntiAddictionBridge.cs，其余游戏逻辑代码不做任何平台判断。

5. 避坑指南：防沉迷 SDK 接入的 5 个高频坑点，从时钟篡改到回调丢失

5.1 现象：改系统时间就能无限玩？本地判定为什么挡不住

这是我在演示给朋友看的时候真实遇到过的。当时做的是本地版本，逻辑是"记录上次退出时间戳，下次进入时用当前系统时间减一下"，一旦把系统时间往后调，差值瞬间变正，限制被当成"新的一天"全部释放。

原因很简单：系统时间属于用户可控输入，任何依赖它的判定都可以被终端的系统设置改写。不只是时钟，本地存档也一样，清应用数据等于把账本撕了。

解决的办法就是前面讲的服务端 UTC 时间轴加心跳记账。本地记录的不是"今天玩了多久"，而是"最近一次和服务端对齐的时间戳"，每次判定都以服务端返回的 remainSeconds 为准，本地值只用来做离线容灾。这个坑的值钱之处在于：它是"它能跑"和"它真的能防"之间的分界线，答辩时主动讲出来，比被评委问到再承认高明得多。

5.2 现象：游客模式绕过实名，产品取舍与合规的冲突

另一个高频坑是游客模式。很多游戏为了降低上手门槛，允许不实名先玩一会儿。防沉迷 SDK 接入后发现，游客模式下 queryPlayState 返回的是"可玩"，时长限额比实名用户短不少，但限额用完之后，如果清数据换个设备指纹，又能继续玩。这在毕设演示里看起来像是系统有漏洞。

原因在于：游客模式天然缺一个稳定身份标识。设备号、广告 ID、IP 都可能被重置，只要身份不稳定，服务端的时长账本就无法可靠记账。这不是 SDK 本身的问题，而是接入方产品策略的问题。

解决按产品定位分两种。要做严格合规，游客模式只允许玩到触发实名门槛，一到阈值强制弹实名，不实名直接禁止进入。要是只做毕设演示，干脆把游客模式做成"仅供试玩，时长上限 15 分钟"，到点弹实名窗，代码里写清楚"游客时长是独立计数，与服务端实名用户的时长不互通"。这个问题适合写进毕设论文的"产品与合规的冲突"小节，属于有深度的素材，不要用一句话带过。

5.3 现象：回调不触发、重复弹实名窗，集成里的高频翻车

回调不触发，是我见过最多的报错。一般日志里什么都没有，界面也没跳，玩家点完"确定"就没反应了。第一个原因是回调对象的生命周期问题：如果发起实名的 Activity 或 Fragment 在回调回来之前被销毁，回调持有的引用就无效了。第二个原因是主线程问题：Android 的上层回调必须在主线程执行，如果在子线程里直接调 SDK 的查询方法，回调可能被 SDK 内部丢弃，或者被 ANR 弹窗盖住。

解决的办法是标准做法：进游戏先做一个"防重入"标志位。用一个 boolean isAuthing，弹实名窗之前先检查，如果已经在弹就只把窗口提到前台，不重复发起；Activity 销毁时反注册回调，改用 Application 级回调，避免生命周期错配；确认所有对外回调都投递到主线程 Looper，再分发到游戏 UI 线程。

另外有一个 Unity 专属的静默失败：C# 侧的方法名或 GameObject 名拼错时，UnitySendMessage 不会报错，日志也看不到异常，表现就是"原生弹窗还在，游戏里什么都不发生"。排查手段是在原生侧给 UnitySendMessage 的调用点加 NSLog 或 Android Log，把每次回传的参数打全。日志说了谎，但日志本身不看，就只能靠玄学猜了。

5.4 现象：release 包不弹实名窗，混淆规则把回调"咽"了

debug 包跑得好好的，一打 release 包，实名窗点了没反应，Logcat 里连一条错误都没有。这种问题十有八九是 ProGuard/R8 把 SDK 的反射接口剪掉了。前面混淆规则里特别强调过 keep 包路径，这里再补一个细节：只 keep 类不够，回调接口和枚举类型的成员也要 keep。

原因：SDK 内部拿到实名结果后，要先反序列化成回调接口的实例，再通过接口方法抛给游戏层。如果接口名被混淆，反序列化时 ClassNotFoundException 或 NoSuchMethodException 会被 SDK 内部的 catch 吞掉，表现就是"一切正常，就是不回调"。

解决：除了 keep 类，再加一条 keepclassmembers 保留 SDK 所有 public 方法，并且要确认签名是 public 的。检查方法是打一个 release 包，用 APK Analyzer 打开，搜 SDK 的类路径，如果路径已经变成 a.b.c，说明 keep 没生效；如果类在但方法没了，改 keepclassmembers。这两条一起加，才算把混淆这关真正过掉。

6. 从毕设到可演示工程：Mock 服务端、时间加速与答辩演示三件套

演示环节最怕两件事：一是现场网络不好，服务端校验超时，实名窗一直转圈；二是三十分钟的时长限制真的让演示等到限制触发。两个问题都能用"可替代的服务端"和"时间加速"解决。

Mock 服务端不复杂，用 Python 写一个几百行的 HTTP 服务就能顶替真实后台：接收心跳、计算累计时长、返回状态码。我把策略集中在 config 里，比如"每 10 秒心跳记 1 秒时长"，这样人在台上等两分钟就能看到完整的"可玩到受限"过程，而不是等半小时。时间轴这里要注意，Mock 服务端的时间戳用真实时间没问题，演示时把计时倍率放大写清楚，答辩时明说"这是演示倍率，实际策略是服务端配置下发的"，就不会被认为是数据造假。

第二个加分细节是日志埋点。Android 端 Logcat 里留好"AuthSuccess / Heartbeat / Restricted"三个关键日志，iOS 侧用 Xcode 控制台，Unity 里用 Debug.Log 同步一套。演示时把日志窗口放到副屏，让评委能看到限制触发那一刻的实时日志输出，这个观感比干讲 PPT 强很多。

最后一个技巧是状态机的 UI 反馈。受限提示不要只弹一个 Toast，做一个覆盖层：显示剩余时间和下次可玩时段，时间到了按钮自动从"置灰"变成"可进入"。这个小交互在答辩里非常抓眼，它能证明你理解的是"完整的防沉迷体验闭环"，而不是只把一个限制接口接完就收工。

我第一次做这类项目时，把大量时间花在界面美化上，真正的判定逻辑全是本地写死，后来被朋友一句话点醒："你这不是防沉迷，是闹钟。"从那天起我才开始重新搭服务端账本和跨端桥接，里面的不少坑都是反复翻车后填平的。希望这篇笔记能帮到你，少走那段弯路，把时间花在真正值钱的架构和边界问题上。

本文还有配套的精品资源，点击获取