Version: v4

UE5 SDK 开发指南

本文介绍如何在 UE5 项目中接入实名认证和防沉迷服务，覆盖 Android、iOS 和 Tap PC。实名认证规则、防沉迷策略和测试账号等通用说明见功能介绍，本页只说明 UE5 接入差异。

集成前准备

参考开发者中心配置创建应用，配置包名、Bundle ID 与签名证书
参考功能介绍的准备工作开通合规认证服务
参考UE5 集成指南完成 TapSDK 基础接入
参考TapTap 登录 UE5 SDK 开发指南完成登录接入

请等待 FTapTapSDK::Init() 成功后，再调用本页的合规认证 API。

SDK 获取

参考 UE5 集成指南完成 TapCore 基础接入。再从下载页下载相同版本的 TapLogin、TapCompliance，放入项目的 Plugins 目录并启用。

添加模块依赖

在游戏模块的 <GameModule>.Build.cs 中添加：

PublicDependencyModuleNames.AddRange(new string[]
{
    "TapCore",
    "TapLogin",
    "TapCompliance",
});

修改 Build.cs 后重新生成项目文件并编译。

#include "TapCompliance.h"

初始化

合规选项通过 FTapComplianceOptions 在首次初始化 TapSDK 时传入。将以下配置合并到集成指南的初始化流程中，并在调用 Init() 前注册初始化回调：

#include "TapCore.h"
#include "TapComplianceOptions.h"

FTapComplianceOptions ComplianceOptions;
ComplianceOptions.bShowSwitchAccount = true; // 默认 false
ComplianceOptions.bUseAgeRange = false;     // 默认 true

TArray<FTapSdkOption> ModuleOptions;
ModuleOptions.Add(FTapSdkOption::Make<FTapComplianceOptions>(ComplianceOptions));

// TapSdkOptions 为集成指南中配置好的核心参数。
FTapTapSDK::Init(TapSdkOptions, ModuleOptions);

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

切换账号界面

如需同时配置事件或成就模块，把相应 Option 加入同一个 ModuleOptions 数组。不要先用默认参数初始化，再重复调用 Init() 修改合规选项；请等待初始化成功后再调用 Startup()。

注册回调

在调用 Startup() 前注册 ITapComplianceCallback：

#include "TapCompliance.h"
#include "MyComplianceHandler.generated.h"

UCLASS()
class UMyComplianceHandler : public UObject, public ITapComplianceCallback
{
    GENERATED_BODY()

public:
    virtual void OnComplianceResult_Implementation(
        int32 Code,
        const FString& ExtraJson) override
    {
        switch (Code)
        {
        case 500:
            // 认证通过，允许玩家进入游戏
            break;
        case 1000:
        case 1001:
            // 退出认证或切换账号，返回游戏登录页
            break;
        case 1030:
        case 1050:
        case 1100:
            // 当前玩家不可进入游戏
            break;
        case 1200:
            // 检查 Client ID、网络连接，并允许玩家重试
            break;
        case 9002:
            // 玩家关闭实名窗口，可重新发起认证
            break;
        default:
            break;
        }
    }
};

创建对象并注册回调：

UPROPERTY()
UMyComplianceHandler* ComplianceHandler = nullptr;

ComplianceHandler = NewObject<UMyComplianceHandler>(this);

TScriptInterface<ITapComplianceCallback> Callback;
Callback.SetObject(ComplianceHandler);
Callback.SetInterface(Cast<ITapComplianceCallback>(ComplianceHandler));

FTapCompliance::RegisterComplianceCallback(Callback);

warning

TScriptInterface<ITapComplianceCallback> 必须同时设置对象和接口。请使用 UPROPERTY() 或其他 UObject 生命周期管理方式持有回调对象，避免对象在认证流程中被回收。

不再需要接收事件时，传入同一个回调对象注销：

TScriptInterface<ITapComplianceCallback> Callback;
Callback.SetObject(ComplianceHandler);
Callback.SetInterface(Cast<ITapComplianceCallback>(ComplianceHandler));

FTapCompliance::UnregisterComplianceCallback(Callback);

回调码在各技术栈中含义一致：

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

开始认证

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

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

#include "TapCompliance.h"
#include "TapLogin.h"

const TOptional<FTapAccount> Account = FTapTapLogin::GetCurrentTapAccount();
if (Account.IsSet())
{
    FTapCompliance::Startup(Account->OpenID);
}

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

充值额度限制

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

检查充值限制

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

#include "TapCompliance.h"

const int64 Amount = 100;

FTapCompliance::CheckPaymentLimit(
    Amount,
    [](int32 status, const FString& Title, const FString& Description)
    {
        if (status == 1)
        {
            // 继续支付流程
            return;
        }

        // 受限时 SDK 会弹出对应提示窗口，开发者不需要额外处理
        UE_LOG(LogTemp, Warning, TEXT("%s: %s"), *Title, *Description);
    },
    [](const FString& Error)
    {
        // 查询失败，可以继续重试，但建议最多重试三次
        UE_LOG(LogTemp, Error, TEXT("Check payment failed: %s"), *Error);
    });

status 为 1 时继续支付流程，为 0 时表示充值受限；网络、登录态、初始化或解析错误通过独立错误回调返回，不应显示为充值额度受限。

上报充值金额

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

#include "TapCompliance.h"

const int64 Amount = 100;

FTapCompliance::SubmitPayment(
    Amount,
    [](bool bSuccess, const FString& Message)
    {
        if (!bSuccess)
        {
            // 上报失败，可以继续重试，但建议最多重试三次
            UE_LOG(LogTemp, Error, TEXT("上报充值失败：%s"), *Message);
        }
    });

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

退出认证

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

FTapCompliance::Exit();

其他

获取玩家年龄段

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

const int32 AgeRange = FTapCompliance::GetAgeRange();

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

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

-1 表示“未知”，说明该玩家还未实名或未授予年龄段权限，通常有以下原因：

在玩家未完成实名时调用该接口。应在收到玩家是否可以进入游戏的回调后（回调 code 为 500、1030 或 1050）再调用
初始化合规认证模块时将 bUseAgeRange 设置为 false，需设置为 true
游戏无版号且在 TapPlay 中运行
玩家首次进入游戏时，游戏未开启获取年龄段权限；该玩家后续获取年龄段时都会返回 -1

获取剩余时长

开发者可调用以下接口获取玩家当前剩余时长：

const int32 RemainingSeconds = FTapCompliance::GetRemainingTime();

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

设置适龄限制

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

接入验证

场景	预期结果
TapSDK 初始化成功后注册回调并调用 `Startup()`	收到明确的合规回调
未实名测试账号开始认证	显示实名流程，完成后返回认证结果
成年测试账号认证	收到 `500`，允许进入游戏
未成年人在不可玩时段认证	收到限制回调，不能进入游戏
支付前调用 `CheckPaymentLimit()`	可支付时 `status` 为 `1`，受限时为 `0`
支付成功后调用 `SubmitPayment()`	回调 `bSuccess` 为 `true`
玩家退出账号时调用 `Exit()`	收到 `1000`，游戏返回登录页
Android / iOS 打包	原生依赖和合规资源正常参与构建
Windows 打包	合规认证 UI 资源存在，认证流程可正常显示

集成前准备​

SDK 获取​

添加模块依赖​

初始化​

注册回调​

开始认证​

充值额度限制​

检查充值限制​

上报充值金额​

退出认证​

其他​

获取玩家年龄段​

获取剩余时长​

设置适龄限制​

接入验证​