跳到主要内容
版本：v4

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

提示

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

权限说明​

集成前准备​

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

SDK 配置​

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

第一步：添加 SDK 所需的外部依赖​

SDK 内部使用了部分第三方库，开发者接入时需先确保 SDK 外部依赖库已正常接入，具体设置如下：

  1. SDK 使用的 JSON 解析库为 Newtonsoft-json，如果当前工程已接入该依赖库，则不需额外处理，否则需在 Packages/manifest.json 添加如下依赖：
"com.unity.nuget.newtonsoft-json":"3.2.1"
  1. SDK 使用 com.google.external-dependency-manager 管理 Android、iOS 依赖，如果当前工程已接入该依赖库，则不需额外处理，否则需在 Packages/manifest.json 添加如下依赖：
{
   "dependencies": {
      "com.google.external-dependency-manager": "1.2.179"
   },
   "scopedRegistries": [
      {
         "name": "package.openupm.com",
         "url": "https://package.openupm.com",
         "scopes": [
            "com.google.external-dependency-manager"
         ]
      }
  ]
}

第二步：添加 SDK 依赖​

SDK 支持 Unity Package Manager 及本地文件导入两种集成方式，开发者根据需求选择其中一种即可，推荐使用远程依赖。

远程依赖​

SDK 支持通过 NPMJS 及 GitHub 两种方式，开发者选择其中一种即可。

1. NPMJS 接入​

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

"dependencies":{
   "com.taptap.sdk.core":"4.8.2",
   "com.taptap.sdk.login":"4.8.2",
   "com.taptap.sdk.compliance":"4.8.2",
}

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

"scopedRegistries":[
  {
    "name": "NPMJS",
    "url": "https://registry.npmjs.org/",
    "scopes": ["com.taptap"]
  }
]
2. GitHub 接入​

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

"dependencies":{
   "com.taptap.sdk.core":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Core#4.8.2",
   "com.taptap.sdk.login":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Login#4.8.2",
   "com.taptap.sdk.compliance":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Compliance#4.8.2",
}

说明：自 4.7.2 起，Unity Packages 仓库已统一为大仓 tapsdk-unity-dist，所有包通过目录区分并使用 ?path= 指定子目录、# 指定版本标签。例如 Core 模块：

"com.taptap.sdk.core": "https://github.com/taptap/tapsdk-unity-dist.git?path=/Core#4.7.2"

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

本地文件导入​

  1. 在 下载页 下载下列模块对应 unitypackage 文件，并在 Unity 项目中依次通过 Assets > Import Packages > Custom Packages 进行导入，包括：
  • TapSDK_Core.unitypackage TapTapSDK 核心模块，必选。
  • TapSDK_Login.unitypackage TapTapSDK 登录模块，必选。
  • TapSDK_Compliance.unitypackage TapTapSDK 合规认证模块，必选。
  1. 如果当前项目已集成 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>

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

初始化​

合规认证模块支持设置是否显示切换账号和使用年龄段信息，开发者可在 TapSDK 初始化 时添加对应的配置，具体如下：

using TapSDK.Core;
using TapSDK.Compliance;
 
// 核心配置
TapTapSdkOptions coreOptions = new TapTapSdkOptions();
// TODO: coreOptions 应用参数配置

// 合规认证配置
TapTapComplianceOption complianceOption = new TapTapComplianceOption
{
    showSwitchAccount = true,  // 是否显示切换账号按钮
    useAgeRange = false  // 游戏是否需要获取真实年龄段信息
};
// 其他模块配置项
TapTapSdkBaseOptions[] otherOptions = new TapTapSdkBaseOptions[]
{
    complianceOption
};
// TapSDK 初始化
TapTapSDK.Init(coreOptions, otherOptions);
参数说明​
  • showSwitchAccount 是否显示切换账号按钮，默认为 false 。如果游戏支持切换账号功能则可以设置为 true，当玩家点击切换账号按钮后，SDK 会触发 1001 回调，游戏可根据该回调 code 做相应处理
  • useAgeRange 游戏是否需要获取真实年龄段信息，默认为 true 。当为 true 时，使用 Tap 实名时会需要用户主动授权，当设置为 false 时，使用 Tap 实名时会进行无 UI 交互的静默授权

切换账号界面

回调设置​

为了处理用户在进行合规认证时触发的不同事件，游戏需通过设置回调进行监听。示例如下：

using TapSDK.Compliance;

private Action<int, string> callback => (code, s) => {
    // do something
};

TapTapCompliance.RegisterComplianceCallback(callback);

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

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

开始认证​

防沉迷开始认证时需传入玩家唯一标识 userIdentifier，建议使用TapTap 用户认证 中的 openId 或 unionId。 玩家唯一标识 userIdentifier 作为账号的唯一字符串，字符串长度不大于 160，只能包含数字、大小写字母、下划线（_）、短横（-）、加号（+）、正斜线（/）、等号（=）、英文句号（.）、英文逗号（,）、英文冒号（:）。

using TapSDK.Compliance;

TapTapAccount account = await TapTapLogin.Instance.GetCurrentTapAccount();
if (account != null) {
    string userIdentifier = account.unionId;
    TapTapCompliance.Startup(userIdentifier);
}

充值额度限制​

不同年龄段的玩家，充值金额有不同的上限，开发者需在玩家充值前检查是否受限，并在玩家成功充值后上报充值金额，具体流程如下：

检查充值限制​

游戏在收到玩家的充值请求后，调用以下接口检查本次充值行为是否受限：

using TapSDK.Compliance;

// 充值金额，单位为分
var amount = 1000;

TapTapCompliance.CheckPaymentLimit(
   amount: amount,
   handleCheckPayLimit: checkResult =>
    {
        // 充值 status 结果: {checkResult.status}
        // status 为 1 时可以继续支付流程，为 0 时 SDK 会弹出对应提示窗口，开发者不需要额外处理
    },
    handleCheckPayLimitException: errorMsg =>
    {
        // 检查充值异常, 处理异常
    }
);

充值金额的单位为分。

上报充值金额​

当玩家充值成功后，开发者需调用如下接口上报玩家充值金额：

using TapSDK.Compliance;

// 充值金额，单位为分
long amount = 100;
TapTapCompliance.SubmitPayment(
    amount: amount,
    handleSubmitPayResult: () =>
    {
        // 成功
    },
    handleSubmitPayResultException: (exception) =>
    {
        // 处理异常
    }
);

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

退出认证​

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

using TapSDK.Compliance;

TapTapCompliance.Exit();

其他​

获取玩家年龄段​

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

using TapSDK.Compliance;

int ageRange = await TapTapCompliance.GetAgeRange();

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

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

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

  1. 开发者在用户未完成实名时调用该接口，应该在收到用户是否可进入游戏的回调时（回调 code 为 500 / 1030 / 1050）时，再进行调用
  2. 在防沉迷初始化时配置的参数 useAgeRange 设置为 false 导致，需设置为 true
  3. 该游戏无版号且在 TapPlay 中运行
  4. 用户首次进入游戏时游戏未开启获取年龄段权限，则该用户后续获取年龄段返回的都是 -1。

获取剩余时长​

获取玩家当前剩余时长：

using TapSDK.Compliance;

int time = await TapTapCompliance.GetRemainingTime(); // 单位:秒

设置适龄限制​

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