版本：v4

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

提示

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

权限说明

Unity
Android Java
Android Kotlin
iOS

该模块需要如下权限：

权限	使用目的	权限申请时机
网络权限	用于正常网络请求	用户首次使用该功能时会申请权限
获取网络状态权限	用于检测当前网络连接是否有效	用户首次使用该功能时会申请权限

该模块将在应用中添加如下权限：

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

该模块需要如下权限：

权限	使用目的	权限申请时机
网络权限	用于正常网络请求	用户首次使用该功能时会申请权限
获取网络状态权限	用于检测当前网络连接是否有效	用户首次使用该功能时会申请权限

该模块将在应用中添加如下权限：

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

集成前准备

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

SDK 配置

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

Unity
Android Java
Android Kotlin
iOS

接入外部依赖

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

SDK 使用的 JSON 解析库为 Newtonsoft-json，如果当前工程已接入该依赖库，则不需额外处理，否则需在 Packages/manifest.json 添加如下依赖：

"com.unity.nuget.newtonsoft-json":"3.2.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"
         ]
      }
  ]
}

提示

如果需要接入 TapSDK Unity PC 平台，需要在使用 NuGet 集成工具，集成 K4os.Compression.LZ4 , protobuf-net 两个库，具体设置如下：

在 Packages/manifest.json 添加如下依赖：

"com.github-glitchenzo.nugetforunity": "https://github.com/GlitchEnzo/NuGetForUnity.git?path=/src/NuGetForUnity"

添加完后，在 Unity 顶部菜单中如果没有出现 NuGet选项，可以重启 Unity 编辑器，包括 Unity Hub 客户端。
在 Unity 顶部菜单中选择 NuGet > Manage NuGet Packages，在弹出的窗口中搜索 K4os.Compression.LZ4 和 protobuf-net 并安装。
最终会在 Assets文件夹下的 packages.config 文件中自动生成如下依赖：

<?xml version="1.0" encoding="utf-8"?>
<packages>
  <package id="K4os.Compression.LZ4" version="1.3.8" manuallyInstalled="true" />
  <package id="System.Collections.Immutable" version="7.0.0" />
  <package id="System.Runtime.CompilerServices.Unsafe" version="6.0.0" />
  <package id="protobuf-net" version="3.2.30" manuallyInstalled="true" />
  <package id="protobuf-net.Core" version="3.2.30" />
</packages>

添加 SDK 依赖

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

远程依赖

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

1. NPMJS 接入

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

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

但需要注意的是，需在 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/TapSDKCore-Unity.git#4.4.3",
   "com.taptap.sdk.login":"https://github.com/taptap/TapSDKLogin-Unity.git#4.4.3",
   "com.taptap.sdk.compliance":"https://github.com/taptap/TapSDKCompliance-Unity.git#4.4.3", 
 }

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

本地文件导入

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

1. 项目根目录的 build.gradle 添加仓库地址：

allprojects { 
    repositories {
        google()
        mavenCentral()
    }
}

app module 的 build.gradle 添加对应依赖：

dependencies {
    implementation 'com.taptap.sdk:tap-core:4.4.3'
    implementation 'com.taptap.sdk:tap-compliance:4.4.3'
    // 实名认证模块依赖登录
    implementation 'com.taptap.sdk:tap-login:4.4.3'
}

1. 项目根目录的 build.gradle 添加仓库地址：

allprojects { 
    repositories {
        google()
        mavenCentral()
    }
}

app module 的 build.gradle 添加对应依赖：

dependencies {
    implementation 'com.taptap.sdk:tap-core:4.4.3'
    implementation 'com.taptap.sdk:tap-compliance:4.4.3'
}

iOS 提供通过添加 cocoaPods 远程依赖和使用本地文件导入两种集成方式，推荐使用远程依赖方式。

远程依赖

在工程 Podfile 文件中对应模块下添加依赖：

 pod 'TapTapComplianceSDK', '~> 4.4.3'

执行 Pod install 下载对应依赖文件
将工程 Pods 目录下 TapTapCompilanceSDK/Frameworks/TapTapComplianceResource.bundle 和 TapTapLoginSDK/Frameworks/TapTapLoginResource.bundle 等资源文件导入工程中

本地文件依赖

合规认证依赖于初始化和 TapTap 登录模块，使用本地文件方式添加依赖时，需先参考 TapSDK 集成和 TapTap 登录添加对应本地文件依赖项。

在下载页下载如下文件：

TapTapComplianceSDK.xcframework 合规认证依赖库
TapTapComplianceResource.bundle 合规认证资源文件

在工程中添加 framework 静态库，注意添加时选择 Embed 方式为 Do Not Embed，导入 bundle 资源文件

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

初始化

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

Unity
Android Java
Android Kotlin
iOS

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);

import com.taptap.sdk.compilance.option.TapTapComplianceOptions;
import com.taptap.sdk.core.TapTapLanguage;
import com.taptap.sdk.core.TapTapRegion;
import com.taptap.sdk.core.TapTapSdk;
import com.taptap.sdk.core.TapTapSdkOptions;

/* 必选配置 */
// 开发者中心对应 Client ID
String clientId = "";
// 开发者中心对应 Client Token
String clientToken = "";
// 是否开启 log，建议 Debug 开启，Release 关闭，默认关闭 log
boolean enableLog = BuildConfig.DEBUG;

TapTapSdkOptions tapSdkOptions = new TapTapSdkOptions(
        clientId, // 游戏 Client ID
        clientToken, // 游戏 Client Token
        TapTapRegion.CN // 游戏可玩区域: [TapTapRegion.CN]=国内 [TapTapRegion.GLOBAL]=海外
);
tapSdkOptions.setEnableLog(enableLog);

// 可选配置 合规模块
TapTapComplianceOptions tapComplianceOptions = new TapTapComplianceOptions(
        true, // 是否显示切换账号按钮，默认为 false
        true // 游戏是否需要获取真实年龄段信息，默认为 true
);
// 初始化 TapSDK
TapTapSdk.init(context, tapSdkOptions, tapComplianceOptions);

import com.taptap.sdk.core.TapTapSdk
import com.taptap.sdk.core.TapTapSdkOptions
import com.taptap.sdk.compilance.option.TapTapComplianceOptions
import com.taptap.sdk.core.TapTapLanguage
import com.taptap.sdk.core.TapTapRegion

TapTapSdk.init(
    context = context,
    sdkOptions = TapTapSdkOptions(
        clientId = clientId,
        clientToken = clientToken,
        region = TapTapRegion.CN,
        preferredLanguage = TapTapLanguage.ZH_HANS,
        enableLog = false
    ),
    options = arrayOf(
        TapTapComplianceOptions(
            //
            showSwitchAccount = true,
            //
            useAgeRange = false,
        )
    )
)

import TapTapComplianceSDK
import TapTapCoreSDK

// 核心配置
let coreOptions = TapTapSdkOptions()
// TODO: coreOptions 应用参数配置

// 合规认证配置
let complianceOptions = TapTapComplianceOptions()
complianceOptions.useAgeRange = false
complianceOptions.showSwitchAccount = true

// 其他模块配置项
let otherOptions = [complianceOptions]
// TapSDK 初始化
TapTapSDK.initWith(coreOptions, otherOptions: otherOptions)

参数说明

showSwitchAccount 是否显示切换账号按钮，默认为 false 。如果游戏支持切换账号功能则可以设置为 true，当玩家点击切换账号按钮后，SDK 会触发 1001 回调，游戏可根据该回调 code 做相应处理
useAgeRange 游戏是否需要获取真实年龄段信息，默认为 true 。当为 true 时，使用 Tap 实名时会需要用户主动授权，当设置为 false 时，使用 Tap 实名时会进行无 UI 交互的静默授权

切换账号界面

回调设置

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

Unity
Android Java
Android Kotlin
iOS

using TapSDK.Compliance;

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

TapTapCompliance.RegisterComplianceCallback(callback);

import com.taptap.sdk.compilance.TapTapCompliance;
import com.taptap.sdk.compilance.TapTapComplianceCallback;
import com.taptap.sdk.compilance.constants.ComplianceMessage;

TapTapCompliance.registerComplianceCallback(new TapTapComplianceCallback() {
    @Override
    public void onComplianceResult(int code, @Nullable Map<String, ?> extra) {
        // 合规结果
        switch (code) {
            case ComplianceMessage.LOGIN_SUCCESS:
                // do something
                break;
            case ComplianceMessage.EXITED:
                // do something
                break;
            case ComplianceMessage.SWITCH_ACCOUNT:
                // do something
                break;
            case ComplianceMessage.PERIOD_RESTRICT:
                // do something
                break;
            case ComplianceMessage.DURATION_LIMIT:
                // do something
                break;
            case ComplianceMessage.INVALID_CLIENT_OR_NETWORK_ERROR:
                // do something
                break;
            default:
                break;
        }
    }
});

import com.taptap.sdk.compilance.TapTapCompliance
import com.taptap.sdk.compilance.TapTapComplianceCallback

TapTapCompliance.registerComplianceCallback(
    callback = object : TapTapComplianceCallback {

        override fun onComplianceResult(code: Int, extra: Map<String, Any>?) {
            when (code) {
                LOGIN_SUCCESS -> {
                    // 登录成功
                }

                EXITED -> {
                    // 退出登录
                }

                SWITCH_ACCOUNT -> {
                    // 切换账号
                }
            }
        }
    }
)

import TapTapComplianceSDK

// 实现 TapTapComplianceDelegate 协议
extension GameMainController: TapTapComplianceDelegate {
    func complianceCallback(with code: TapComplianceResultHandlerCode, extra: String?) {
        print("TapCompliance result code = \(code.rawValue)")
    }
}
// 注册合规认证回调
TapTapCompliance.register(self)

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

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

开始认证

防沉迷开始认证时需传入玩家唯一标识 userIdentifier，建议使用TapTap 用户认证中的 openid 或 unionid。

Unity
Android Java
Android Kotlin
iOS

using TapSDK.Compliance;

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

import com.taptap.sdk.compilance.TapTapCompliance;
import com.taptap.sdk.login.TapTapAccount;
import com.taptap.sdk.login.TapTapLogin;

TapTapAccount currentTapAccount = TapTapLogin.getCurrentTapAccount();
if(currentTapAccount != null) {
    String unionId = currentTapAccount.getUnionId();
    TapTapCompliance.startup(activity, unionId);
}

import com.taptap.sdk.compilance.TapTapCompliance

TapTapCompliance.startup(activity = this, userId = "userIdentifier")

import TapTapComplianceSDK
import TapTapLoginSDK

let userIdentifier = TapTapLogin.currentAccount?.userInfo?.unionId
TapTapCompliance.startup(userIdentifier)

充值额度限制

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

检查充值限制

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

Unity
Android Java
Android Kotlin
iOS

using TapSDK.Compliance;

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

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

import com.taptap.sdk.compilance.TapTapCompliance;
import com.taptap.sdk.compilance.bean.CheckPaymentResult;
import com.taptap.sdk.kit.internal.callback.TapTapCallback;
import com.taptap.sdk.kit.internal.exception.TapTapException;

// 充值金额，单位为分
int amount = 100;

TapTapCompliance.checkPaymentLimit(activity, amount, new TapTapCallback<CheckPaymentResult>() {

    @Override
    public void onSuccess(CheckPaymentResult checkPaymentResult) {
        if(checkPaymentResult.getStatus()) {
            // 充值没有限制
        } else {
            // 在充值被限制时，SDK 会弹出对应提示窗口，开发者不需要额外处理
        }
    }

    @Override
    public void onFail(@NonNull TapTapException exception) {
        // 查询失败，开发者可以继续重试，但建议最多重试三次
    }

    @Override
    public void onCancel() {
    }
});

import com.taptap.sdk.compilance.TapTapCompliance
import com.taptap.sdk.kit.internal.callback.TapTapCallback

TapTapCompliance.checkPaymentLimit(
    activity = this,
    amount = amount,
    callback = object : TapTapCallback<CheckPaymentResult> {

        override fun onSuccess(result: CheckPaymentResult) {
            if (result.status) {
                // 充值没有限制
            }
            // 在充值被限制时，SDK 会弹出对应提示窗口，开发者不需要额外处理
        }

        override fun onFail(exception: TapTapException) {
            // 查询失败，开发者可以继续重试，但建议最多重试 3次
        }
    }
)

import TapTapComplianceSDK

// 充值金额，单位为分
let amount = 100 
TapTapCompliance.checkPaymentLimit(amount) { status, title, desc in
    // 充值没有限制
    if status {
        // TODO: 完成后续充值流程
    }
    // 在充值被限制时，SDK 会弹出对应提示窗口，开发者不需要额外处理
} failureHandler: { msg in
    // 查询失败，开发者可以继续重试，但建议最多重试三次
}

充值金额的单位为分。

上报充值金额

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

Unity
Android Java
Android Kotlin
iOS

using TapSDK.Compliance;

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

import com.taptap.sdk.compilance.TapTapCompliance;
import com.taptap.sdk.kit.internal.callback.TapTapCallback;
import com.taptap.sdk.kit.internal.exception.TapTapException;

int amount = 100;
TapTapCompliance.submitPayment(amount, new TapTapCallback<JsonElement>() {
    @Override
    public void onSuccess(JsonElement jsonElement) {
        // 上报充值成功
    }

    @Override
    public void onFail(@NonNull TapTapException exception) {
        // 上报充值失败
    }

    @Override
    public void onCancel() {
    }
});

import com.taptap.sdk.compilance.TapTapCompliance
import com.taptap.sdk.kit.internal.callback.TapTapCallback

TapTapCompliance.submitPayment(
    amount = amount,
    callback = object : TapTapCallback<JsonElement> {
        override fun onSuccess(result: JsonElement) {
            // 上报充值成功
        }

        override fun onFail(exception: TapTapException) {
            // 上报充值失败
        }
    }
)

import TapTapComplianceSDK

// 充值金额，单位为分
let amount = 100 
TapTapCompliance.submitPayment(amount) { success in
   // 上报成功
} failureHandler: { msg in
   // 上报失败，开发者可以继续重试，但建议最多重试三次
}

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

退出认证

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

Unity
Android Java
Android Kotlin
iOS

using TapSDK.Compliance;

TapTapCompliance.Exit();

import com.taptap.sdk.compilance.TapTapCompliance;

TapTapCompliance.exit();

import com.taptap.sdk.compilance.TapTapCompliance

TapTapCompliance.exit()

import TapTapComplianceSDK

TapTapCompliance.exit()

其他

获取玩家年龄段

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

Unity
Android Java
Android Kotlin
iOS

using TapSDK.Compliance;

int ageRange = await TapTapCompliance.GetAgeRange();

import com.taptap.sdk.compilance.TapTapCompliance;

int ageRange = TapTapCompliance.getAgeRange();

import com.taptap.sdk.compilance.TapTapCompliance

TapTapCompliance.getAgeRange()

import TapTapComplianceSDK

let ageRange = TapTapCompliance.getAgeRange().rawValue

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

类型数值	含义
-1	未知
0	0 到 7 岁
8	8 到 15 岁
16	16 到 17 岁
18	成年玩家

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

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

获取剩余时长

获取玩家当前剩余时长：

Unity
Android Java
Android Kotlin
iOS

using TapSDK.Compliance;

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

import com.taptap.sdk.compilance.TapTapCompliance;

int remainingTime = TapTapCompliance.getRemainingTime(); // 单位:秒

import com.taptap.sdk.compilance.TapTapCompliance

TapTapCompliance.getRemainingTime()

import TapTapComplianceSDK

let remainingTimeInSeconds = TapTapCompliance.getRemainingTime()    // 单位：秒

设置适龄限制

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

权限说明​

集成前准备​

SDK 配置​

接入外部依赖​

添加 SDK 依赖​

远程依赖​

1. NPMJS 接入​

2. GitHub 接入​

本地文件导入​

远程依赖​

本地文件依赖​

初始化​

参数说明​

回调设置​

开始认证​

充值额度限制​

检查充值限制​

上报充值金额​

退出认证​

其他​

获取玩家年龄段​

获取剩余时长​

设置适龄限制​

权限说明

集成前准备

SDK 配置

接入外部依赖

添加 SDK 依赖

远程依赖

1. NPMJS 接入

2. GitHub 接入

本地文件导入

远程依赖

本地文件依赖

初始化

参数说明

回调设置

开始认证

充值额度限制

检查充值限制

上报充值金额

退出认证

其他

获取玩家年龄段

获取剩余时长

设置适龄限制