Version: v4

UE5 SDK 开发指南

本文介绍如何在 UE5 项目中接入 TapTap 登录，覆盖 Android、iOS 和 Tap PC。

集成前准备

参考开发者中心配置创建应用，配置包名、Bundle ID 与签名证书。接入 TapTap PC 端时，还需配置 Client Public Key
参考 TapTap 登录功能介绍开通 TapTap 登录服务
参考 UE5 集成指南完成 TapSDK 基础接入，并等待初始化成功后再调用登录 API

SDK 获取

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

添加模块依赖

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

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

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

Android 配置

插件会通过 UPL 自动完成 Android 配置：

添加 INTERNET 等网络权限
添加 com.taptap.sdk:tap-login 依赖
注入登录路由和 UE 回调桥接
添加登录模块的混淆保留规则

首次 Android 构建需要网络连接以下载 Maven 依赖。

iOS 配置

TapLogin 插件会链接随插件提供的 TapTapLoginSDK.xcframework 和所需系统框架，并通过 UE 的 OnOpenURL 事件处理登录回调。当前插件不会自动把登录 URL Scheme 和查询白名单写入最终应用的 Info.plist；请在 iOS 工程配置中加入以下内容，并在每次打包后检查最终产物：

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>taptap</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>ttYOUR_CLIENT_ID</string>
        </array>
    </dict>
</array>
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>tapiosdk</string>
    <string>tapsdk</string>
    <string>taptap</string>
</array>

将 YOUR_CLIENT_ID 替换为开发者中心的 Client ID，保留前缀 tt。请使用 macOS / Xcode 构建 iOS 项目。

PC 配置

接入 TapTap PC 端的游戏，与未接入游戏的登录交互不同。请按实际接入方式选择对应流程。

TapTap PC 端登录

tip

接入 TapTap PC 端时，需要先完成启动校验，具体参考 UE5 启动校验示例。等待校验成功后再发起客户端登录。

在 TapTap PC 端登录时，SDK 会静默完成登录，不会弹出 UI。该流程为异步操作，建议在发起登录前显示加载弹窗，并在登录完成后关闭。

普通 PC 登录

tip

SDK 默认支持扫码登录。跳转浏览器登录需要额外配置。

PC 登录

Windows 使用 OAuth 登录面板，支持二维码和浏览器授权。TapTap PC 客户端可用且启动校验通过时，会优先走客户端授权。

Windows 平台

如果要在 Windows 使用跳转网页浏览器登录，需要在注册表添加：

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\open-taptap-{client_id}]
@="{游戏名称}"
"URL Protocol"="{程序.exe 安装路径}"

[HKEY_CLASSES_ROOT\open-taptap-{client_id}]
@="{游戏名称}"

[HKEY_CLASSES_ROOT\open-taptap-{client_id}]

[HKEY_CLASSES_ROOT\open-taptap-{client_id}\Shell\Open]

[HKEY_CLASSES_ROOT\open-taptap-{client_id}\Shell\Open\Command]
@="\"{程序.exe 安装路径}\" --taptap-deeplink=\"%1\""

将 {client_id} 替换为开发者中心的 Client ID。插件会从命令行读取 --taptap-deeplink，并校验 URL Scheme、Client ID 和 authorize 回调路径。

发起登录

在用户点击 TapTap 登录按钮后调用。授权范围必须包含 public_profile 或 basic_info，可按业务组合其他权限。

权限	说明
`public_profile`	获得 openId、unionId、用户昵称、用户头像
`basic_info`	获得 openId 和 unionId
`user_friends`	获得访问 TapTap 好友相关数据的权限

tip

若只请求 basic_info，用户可使用无感登录，无需手动确认授权。

登录结果通过 ITapLoginCallback 返回。实现成功、失败和取消三个分支：

#include "TapLogin.h"

UCLASS()
class UMyLoginCallback : public UObject, public ITapLoginCallback
{
    GENERATED_BODY()

public:
    virtual void OnLoginSuccess(const FTapAccount& Account) override
    {
        UE_LOG(LogTemp, Log, TEXT("登录成功，当前用户 ID：%s"), *Account.UnionID);
        // 建立游戏登录态
    }

    virtual void OnLoginFailed(int32 ErrorCode, const FString& ErrorMessage) override
    {
        UE_LOG(LogTemp, Error, TEXT("登录失败：%s"), *ErrorMessage);
    }

    virtual void OnLoginCancelled() override
    {
        // 用户取消登录，不要提示为系统错误
        UE_LOG(LogTemp, Log, TEXT("用户取消登录"));
    }
};

在发起登录的 UObject 类中使用 UPROPERTY() 持有回调对象，避免异步流程中被回收：

private:
    UPROPERTY()
    UMyLoginCallback* LoginHandler;

等待 TapSDK 初始化成功后，创建回调对象并发起登录：

#include "TapLogin.h"

TArray<ETapLoginScope> Scopes;
Scopes.Add(ETapLoginScope::PublicProfile);

if (!LoginHandler)
{
    LoginHandler = NewObject<UMyLoginCallback>(this);
}

TScriptInterface<ITapLoginCallback> LoginCallback;
LoginCallback.SetObject(LoginHandler);
LoginCallback.SetInterface(Cast<ITapLoginCallback>(LoginHandler));

FTapTapLogin::LoginWithScopes(Scopes, LoginCallback);

参数	类型	必选	说明
`Scopes`	`TArray<ETapLoginScope>`	是	本次登录请求的授权范围，必须包含 `PublicProfile` 或 `BasicInfo`。
`Callback`	`TScriptInterface<ITapLoginCallback>`	是	接收登录成功、用户取消和登录失败结果；对象必须在异步流程结束前保持有效。

不要在同一时间重复发起多个登录请求。登录成功后应建立游戏自己的登录态，不要直接把 Access Token 当作游戏用户 ID。

获取当前用户

游戏启动时先调用该接口。该接口没有参数，返回本地缓存的 TOptional<FTapAccount>；没有可用登录信息时 IsSet() 为 false。如果本地已有有效登录信息，不要再弹出登录按钮。

#include "TapLogin.h"

TOptional<FTapAccount> Account = FTapTapLogin::GetCurrentTapAccount();
if (Account.IsSet())
{
    const FTapAccessToken& AccessToken = Account->AccessToken;
    const FString& OpenId = Account->OpenID;
}
else
{
    // 用户未登录，显示登录按钮
}

字段	说明
`AccessToken`	玩家在 TapTap 平台的用户 token。服务端调用 OpenAPI 时使用，见获取用户信息
`OpenID`	用户在当前游戏内的唯一标识
`UnionID`	用户在同一厂商下所有游戏中的统一标识
`Name`	TapTap 昵称
`Avatar`	TapTap 头像 URL

登出

登出只清除本地缓存的 TapTap 登录信息，不会退出 TapTap 客户端。

#include "TapLogin.h"

FTapTapLogin::Logout();

接入验证

场景	预期结果
初始化成功后点击登录	收到成功、取消或失败回调之一
Android 登录	通过原生登录 SDK 返回账号信息
iOS 授权后返回游戏	最终 `Info.plist` 包含 `tt{ClientID}` Scheme 和查询白名单，URL 回调被插件处理并返回登录结果
Windows TapTap PC 客户端登录	客户端可用时完成客户端授权；不可用时回退到登录面板
Windows 扫码或浏览器登录	授权完成后返回登录结果
登录成功后重启游戏	`GetCurrentTapAccount()` 返回当前账号
调用 `Logout()`	本地登录信息被清除，可重新发起登录
用户取消登录	收到 `OnLoginCancelled()`，不提示系统错误

集成前准备​

SDK 获取​

添加模块依赖​

Android 配置​

iOS 配置​

PC 配置​

TapTap PC 端登录​

普通 PC 登录​

Windows 平台​

发起登录​

获取当前用户​

登出​

接入验证​