Skip to main content
Version: v4

Unity SDK 开发指南

本文介绍如何在 Unity 项目中接入实名认证和防沉迷服务，覆盖 Android、iOS 和 PC。

集成前准备​

  1. 参考开发者中心配置创建应用、配置包名与签名证书
  2. 参考功能介绍的准备工作开通合规认证服务
  3. 参考Unity 集成指南完成 TapSDK 基础接入。接入 PC 时，还需完成启动校验
  4. 参考TapTap 登录 Unity SDK 开发指南完成登录接入

SDK 获取​

远程依赖​

NPMJS 方式：在 Packages/manifest.json 中添加：

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

GitHub 方式：在 Packages/manifest.json 中添加：

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

本地文件导入​

在下载页下载并导入：

  • TapSDK_Core.unitypackage
  • TapSDK_Login.unitypackage
  • TapSDK_Compliance.unitypackage

初始化​

合规认证模块可配置是否显示切换账号按钮，以及是否获取年龄段信息：

using TapSDK.Core;
using TapSDK.Compliance;

var coreOptions = new TapTapSdkOptions
{
    clientId = clientId,
    clientToken = clientToken
};

var complianceOption = new TapTapComplianceOption
{
    showSwitchAccount = true,
    useAgeRange = false
};

TapTapSDK.Init(
    coreOptions,
    new TapTapSdkBaseOptions[] { complianceOption }
);
配置说明
showSwitchAccount是否显示切换账号按钮，默认为 false。如果游戏支持切换账号，可设置为 true；玩家点击按钮后，SDK 会触发 1001 回调，游戏可根据该回调 code 进行处理
useAgeRange游戏是否需要获取真实年龄段信息，默认为 true。设置为 true 时，使用 Tap 实名需要用户主动授权；设置为 false 时，使用 Tap 实名会进行无 UI 交互的静默授权

切换账号界面

注册回调​

在开始认证前注册回调，并处理所有会影响玩家能否进入游戏的结果：

using System;
using TapSDK.Compliance;
using UnityEngine;

private readonly Action<int, string> complianceCallback = (code, extra) =>
{
    switch (code)
    {
        case 500:
            // 认证通过，允许玩家进入游戏
            break;
        case 1000:
        case 1001:
            // 退出认证或切换账号，返回登录页
            break;
        case 1030:
        case 1050:
        case 1100:
            // 当前玩家不可进入游戏
            break;
        case 1200:
            // 检查应用配置和网络，并允许重试
            break;
        case 9002:
            // 玩家关闭实名窗口，可重新发起认证
            break;
        default:
            Debug.Log($"合规认证回调：{code}, {extra}");
            break;
    }
};

TapTapCompliance.RegisterComplianceCallback(complianceCallback);
回调 code回调类型游戏处理
500LOGIN_SUCCESS玩家未受到限制，允许进入游戏
1000EXITED认证退出或凭证失效，返回登录页
1001SWITCH_ACCOUNT玩家选择切换账号，返回登录页
1030PERIOD_RESTRICT当前时段不可玩，阻止进入游戏
1050DURATION_LIMIT无剩余可玩时长，阻止进入游戏
1100AGE_LIMIT触发开发者中心配置的可玩年龄限制
1200INVALID_CLIENT_OR_NETWORK_ERROR应用配置无效或网络异常
9002REAL_NAME_STOP玩家关闭实名窗口，可重新开始认证

开始认证​

防沉迷开始认证时需传入玩家唯一标识 userIdentifier，建议使用 TapTap 登录 Unity SDK 开发指南中获取的 openId。

玩家唯一标识 userIdentifier 是账号的唯一字符串，长度不能超过 160，只能包含数字、大小写字母、下划线（_）、短横（-）、加号（+）、正斜线（/）、等号（=）、英文句号（.）、英文逗号（,）和英文冒号（:）。

using TapSDK.Compliance;
using TapSDK.Login;

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

不要在前一次认证结果返回前重复调用 Startup()。

充值额度限制​

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

检查充值限制​

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

using TapSDK.Compliance;

long amount = 100;

TapTapCompliance.CheckPaymentLimit(
    amount,
    result =>
    {
        if (result.status == 1)
        {
            // 继续支付流程
        }
        // status 为 0 时 SDK 会弹出对应提示窗口，开发者不需要额外处理
    },
    errorMessage =>
    {
        // 查询失败，可以继续重试，但建议最多重试三次
    }
);

上报充值金额​

当玩家充值成功后，开发者需调用以下接口上报玩家充值金额。传入金额的单位同样为分：

using TapSDK.Compliance;

long amount = 100;

TapTapCompliance.SubmitPayment(
    amount,
    () =>
    {
        // 上报成功
    },
    errorMessage =>
    {
        // 上报失败，可以继续重试，但建议最多重试三次
    }
);

不要在支付失败或取消时调用 SubmitPayment()。

退出认证​

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

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 remainingSeconds = await TapTapCompliance.GetRemainingTime();

remainingSeconds 为玩家剩余游戏时间，单位为秒。

设置适龄限制​

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

接入验证​

场景预期结果
初始化成功后注册回调并调用 Startup()收到明确的合规回调
未实名测试账号开始认证显示实名流程，完成后返回认证结果
成年测试账号认证收到 500，允许进入游戏
未成年人在不可玩时段认证收到限制回调，不能进入游戏
支付前调用 CheckPaymentLimit()可支付时 status 为 1，受限时为 0
支付成功后调用 SubmitPayment()收到成功回调
玩家退出账号时调用 Exit()收到 1000，游戏返回登录页