跳到主要内容
版本：v3

实名认证和防沉迷开发指南

提示

使用 TDS 实名认证和防沉迷服务之前，需要在 开发者中心后台 > 游戏服务 > 开发与构建 > 合规认证 处开通服务，可选择「已有版号」或「暂无版号」方案。

环境要求​

  • Unity 2019.4 或更高版本
  • iOS 11 或更高版本，Xcode 版本 14.1 或更高版本
  • Android 5.0（API level 21）或更高版本

权限说明​

集成前准备​

  1. 参考 准备工作 创建应用、开启应用配置。
  2. 参考实名认证和防沉迷功能介绍中准备工作开通防沉迷服务。
  3. 防沉迷模块依赖于 TapTap 登录模块，开发者接入防沉迷前应先接入 TapTap 登录 相关依赖。

SDK 配置​

可以在 下载页 获得 TapSDK，引入防沉迷模块。

SDK 可以通过 Unity Package Manager 导入或手动导入，二者任选其一。请根据项目需要选择。

方法一：使用 Unity Package Manager​

从 3.29.1 版本开始， SDK 修改 JSON 解析库为 Newtonsoft-json，如果当前工程已接入该依赖库，则不需额外处理，否则需在 Packages/manifest.json 添加如下依赖：

"com.unity.nuget.newtonsoft-json":"3.2.1"
NPMJS 安装​

从 3.25.0 版本开始，TapSDK 支持了 NPMJS 安装，优势是只需要配置版本号，并且支持嵌套依赖。

在项目的 Packages/manifest.json 文件中添加以下依赖：

"dependencies":{
    "com.tapsdk.antiaddiction":"3.29.2",
    "com.taptap.tds.common":"3.29.2",
    "com.taptap.tds.login":"3.29.2",
    }

但需要注意的是，要在 Packages/manifest.json 中 dependencies 同级下声明 scopedRegistries：

"scopedRegistries": [
      {
        "name": "NPMJS",
        "url": "https://registry.npmjs.org/",
        "scopes": ["com.tapsdk", "com.taptap"]
      }
    ]
GitHub 安装​

在项目的 Packages/manifest.json 文件中添加以下依赖：

"dependencies":{
    "com.taptap.tds.common":"https://github.com/TapTap/TapCommon-Unity.git#3.29.2",
    "com.tapsdk.antiaddiction":"https://github.com/TapTap/TapAntiAddiction-Unity.git#3.29.2",
    "com.taptap.tds.login":"https://github.com/TapTap/TapLogin-Unity.git#3.29.2", 
    }

在 Unity 顶部菜单中选择 Window > Package Manager 可查看已经安装在项目中的包。

方法二：手动导入​

  1. 在 下载页 找到 TapSDK Unity 下载地址，下载 TapSDK-UnityPackage.zip 。

  2. 在 Unity 项目中依次转到 Assets > Import Packages > Custom Packages，从解压后的 TapSDK-UnityPackage.zip 中，选择希望在游戏中使用的 TapSDK 包导入，其中：

    • TapTap_Common.unitypackage TapSDK 基础库，必选。
    • TapTap_AntiAddiction.unitypackage TapTap 防沉迷库，必选。

  3. 如果当前项目已集成 Newtonsoft.Json 依赖，则忽略该步骤，否则在 NuGet.org Newtonsoft.Json 页面中通过点击右侧 「Download package」 下载库文件，并将下载的文件后缀从.nupkg 修改为 .zip，同时解压该文件并复制内部的 Newtonsoft.Json.dll 文件拷贝到工程 Assets 的 Plugins 目录下，另外为了避免导出 IL2CPP 平台时删除必要数据，需在 Assets 目录下创建 link.xml 文件（如果已有该文件，则添加如下内容），其内容如下：

<linker>
  <assembly fullname="System.Core">
    <type fullname="System.Linq.Expressions.Interpreter.LightLambda" preserve="all" />
  </assembly>
</linker>

iOS 平台配置：

使用 Xcode 13.0 beta 5 编译，检查 Unity 输出的 Xcode 工程：

查看 Unity 输出的 Xcode 工程详情配置
  1. 请确保设置 Xcode - General - Frameworks, Libraries, and Embedded Content 中的 AntiAddictionService.framework 和 AntiAddictionUI.framework 为 Do Not Embed。

  1. 如果编译报错找不到头文件或者模块，请确保 Xcode - Build Settings - Framework Search Paths 中的路径以保证 Xcode 正常编译。

  1. 确保 Xcode 工程的 Build Settings 的 Swift Compile Language / Swift Language Version 为 Swift5。

  1. 添加依赖库 libz.tbd、libc++.tbd。

  1. 开始代码接入。

  2. 将 AntiAddiction-Unity/Assets/Plugins/iOS/Resource/AntiAdictionResources.bundle 拷贝到 Unity 导出的 Xcode 工程目录下（如果 Unity 项目没有正确导入 AntiAddictionResources.bundle）。假设你的 Unity 项目名称为 AntiDemo，则默认导出 Xcode 工程名为 antidemoxcode，需要将 AntiAdictionResources.bundle 拷贝到 antidemoxcode 目录里。拷贝成功后在项目的 Build Phases > Copy Bundle Resources 里添加拷贝的 AntiAdictionResources.bundle。

防沉迷 SDK 需要联网和发送请求数据的权限，请开发者注意在项目中声明相应权限。

初始化与回调设置​

回调设置​

因初始化接口依赖或需结合使用防沉迷回调对象参数，开发者应先自定义防沉迷回调对象来处理不同类型事件。

Action<int, string> callback = (code, extra) => {
      // 防沉迷回调
     UnityEngine.Debug.LogFormat($"code: {code} error Message: {extra}");
};

回调参数中 code 用于标识回调类型， extra 为对应提示信息

回调 code回调类型触发逻辑
500LOGIN_SUCCESS玩家未受到限制，正常进入游戏
1000EXITED退出防沉迷认证及检查，当开发者调用 Exit 接口时或用户认证信息无效时触发，游戏应返回到登录页
1001SWITCH_ACCOUNT用户点击切换账号，游戏应返回到登录页
1030PERIOD_RESTRICT用户当前时间无法进行游戏，此时用户只能退出游戏或切换账号
1050DURATION_LIMIT用户无可玩时长，此时用户只能退出游戏或切换账号
1100AGE_LIMIT当前用户因触发应用设置的年龄限制无法进入游戏
1200INVALID_CLIENT_OR_NETWORK_ERROR数据请求失败，游戏需检查当前设置的应用信息是否正确及判断当前网络连接是否正常
9002REAL_NAME_STOP实名过程中点击了关闭实名窗，游戏可重新开始防沉迷认证

初始化​

从 3.27.0 版本开始，防沉迷初始化有两种方式，使用 TapBootstrap 模块 和 单独调用防沉迷接口初始化，游戏根据需要选择一种即可， 3.27.0 之前的版本只支持单独调用防沉迷接口初始化。

TapBootstrap 初始化（不推荐）​

使用 TapBootstrap 初始化时，需要在 TapConfig 中设置 TapAntiAddicitionConfig 配置, 但不需要再额外调用登录初始化接口，同时防沉迷回调对象需单独设置。示例如下：

var config = new TapConfig.Builder()
        .ClientID(clientId)
        .ClientToken(clientToken)
        .ServerURL(serverUrl)
        .RegionType(regionType)
        // showSwitchAccount bool 类型 是否显示切换账号按钮； useAgeRange bool 类型 是否需要获取真实年龄段信息
        .AntiAddictionConfig(showSwitchAccount, useAgeRange);    
TapBootstrap.Init(config);
// 设置回调， callback 为开发者实现的自定义防沉迷回调对象
AntiAddictionUIKit.SetAntiAddictionCallback(callback);
参数说明​

TapAntiAddictionConfig 为防沉迷模块使用的配置，其参数如下：

  • showSwitchAccount 是否显示切换账号按钮。如果游戏不支持切换账号功能，应设置为 false；如果游戏支持则设置为 true，当玩家点击切换账按钮后，SDK 会触发 1001 回调，游戏可根据这个回调 code 做相应处理。

  • useAgeRange 游戏是否需要获取真实年龄段信息，当设置为 true 时，使用 Tap 实名时会需要用户主动授权，当设置为 false 时，使用 Tap 实名时会进行无 UI 交互的静默授权，未设置时默认为 true

防沉迷接口单独初始化（推荐）​

因防沉迷模块依赖于 TapLogin 模块，所以在防沉迷模块初始化前必须完成 TapLogin 模块初始化。 初始化防沉迷 UI 模块，包括设置启动防沉迷功能的配置、注册防沉迷的消息监听。

using TapTap.AntiAddiction;
using TapTap.AntiAddiction.Model;

AntiAddictionConfig config = new AntiAddictionConfig()
{
    gameId = "your_client_id",      // TapTap 开发者中心对应 Client ID
    showSwitchAccount = false,      // 是否显示切换账号按钮
    useAgeRange = true      // 是否使用年龄段信息
};         
//设置配置及回调，callback 为开发者实现的自定义防沉迷回调对象
AntiAddictionUIKit.Init(config);
AntiAddictionUIKit.SetAntiAddictionCallback(callback);
参数说明​
  • config 是防沉迷功能的配置，包括如下参数：
    • gameId 游戏的 Client ID，可以在控制台查看（开发者中心 > 你的游戏 > 游戏服务 > 应用配置）。
    • showSwitchAccount 是否显示切换账号按钮。如果游戏不支持切换账号功能，应设置为 false；如果支持则设置为 true，当玩家点击切换账按钮(如下图所示）后，SDK 会触发 1001 回调，游戏可根据这个回调 code 做相应处理。
    • useAgeRange 游戏是否需要获取真实年龄段信息，当设置为 true 时，使用 Tap 实名时会需要用户主动授权，当设置为 false 时，在移动端使用 Tap 实名时会进行无 UI 交互的静默授权，未设置时默认为 true
  • callback 开发者实现的自定义防沉迷回调对象

切换账号界面

开始认证​

防沉迷开始认证时需传入玩家唯一标识 userIdentifier，如果接入 TDS 内建账户系统，可以用玩家的 objectId；如果使用单纯 TapTap 用户认证则可以用 openid 或 unionid。

// 注意唯一标识参数值长度不能超过 64 字符
string userIdentifier = "玩家的唯一标识";
AntiAddictionUIKit.StartupWithTapTap(userIdentifier);

检查消费上限​

根据年龄段的不同，未成年玩家的消费金额有不同的上限。开发者需要在未成年玩家消费前检查是否受限，并在成功消费后上报消费金额。

游戏在收到玩家的付费请求后，调用以下接口当前玩家的付费行为是否被限制：

long amount = 100;
AntiAddictionUIKit.CheckPayLimit(amount,
    (result) => {
        // status 为 1 时可以支付
        int status = result.status;
        if (status == 1) {
            // 可以进行支付
        }
    },
    (exception) => {
        // 处理异常
    }
);

消费金额的单位为分。

上报消费金额​

当未成年玩家消费成功后，调用如下接口上报玩家消费金额：

long amount = 100;
AntiAddictionUIKit.SubmitPayResult(amount,
    () => {
        // 成功
    }, (exception) => {
        // 处理异常
    }
);

上报消费金额时，传入的消费金额的单位同样为分。

退出认证​

玩家在游戏内退出账号时调用，重置防沉迷状态。

AntiAddictionUIKit.Exit();

其他​

获取玩家年龄段​

开发者可调用如下接口获取玩家所处年龄段：

int ageRange = AntiAddictionUIKit.AgeRange;

上例中的 ageRange 是一个整数，表示玩家所处年龄段的下限（最低年龄）。

类型数值含义
-1未知
00 到 7 岁
88 到 15 岁
1616 到 17 岁
18成年玩家

-1 表示「未知」，说明该用户还未实名或未授予年龄段权限，通常有以下几个原因：

  1. 开发者在用户未完成实名时调用该接口，应该在收到用户是否可进入游戏的回调时（回调 code 为 500 / 1030 / 1050）时，再进行调用
  2. 在防沉迷初始化时配置的参数 useAgeRange 设置为 false 导致，需设置为 true
  3. 该游戏无版号且在 TapPlay 中运行

获取剩余时长​

获取玩家当前剩余时长：

int remainingTimeInSeconds = AntiAddictionUIKit.RemainingTime;    // 单位：秒

int remainingTimeInMinutes = AntiAddictionUIKit.RemainingTimeInMinutes;    // 单位：分

设置适龄限制​

当除了需要满足防沉迷政策外，应用需要对用户年龄有额外限制时，例如只允许 16 周岁以上使用，开发者可在 开发者中心页面配置对应的年龄限制，SDK 将在用户完成实名后 且 根据时长限制规则显示 UI 前检查用户是否符合游戏要求，满足要求时，SDK 会继续进行后续时长业务及回调处理，否则会直接返回 code 为 1100 的年龄限制回调通知开发者。

测试模式设置​

使用提供的测试账号以邮箱方式登录 TapTap，游戏启动后触发 TapTap 登录，登录成功后会在成功的回调中得到当前测试账号对应的 unionid， unionid 获取方式可以参考获取用户信息的内容。

开启测试模式的接口需要在 SDK 的 init 初始化接口之后，startupwithtaptap 接口之前调用。

测试账号的使用场景分为两种：常规模式 和 测试模式。无论是常规模式还是测试模式，在 startupwithtaptap 传入的 玩家唯一标识 userIdentifier 皆必须为测试账号对应的 TapTap 登录后返回的 unionid。

AntiAddictionUIKit.SetTestEnvironment(enable)

使用该接口需要在控制台开启「切换为测试模式」，可以针对某个账号进行一些设置，正式打包上线的应用应该需要去掉这个接口。

提示

合规认证 3.29.0 之前版本提供的 REST API 已不适用于 3.29.0 及其以上版本，如果游戏早期已接入 REST API 且游戏想要升级至 3.29.0 及其以上版本后继续使用 REST API，请于 TapTap 开发者后台提工单联系我们。