UE5 SDK 集成（多平台）

本文介绍如何在 UE5 项目中快速接入 TapSDK。

环境要求

• UE5.7 或更高版本

编译工具链

Android 项目按对应 UE5 引擎版本的 Android 开发环境要求安装工具链，并使用 UE5 生成的 Gradle 和 Android Gradle Plugin（AGP）配置。

iOS 项目通过 Xcode 构建。请按对应 UE5 引擎版本的 iOS 开发环境要求选择匹配的 Xcode。

SDK 获取

info

游戏 适用地区 在开启应用配置时选定。

• TapTap 开发者中心适用地区为中国大陆。

• 出海游戏请前往 TapTap.io 开发者中心 开启游戏服务，适用地区为其他国家或地区。

从下载页下载 TapCore，解压到项目的 Plugins 目录，并在 Edit > Plugins 中启用。登录、合规认证等业务模块按对应开发指南添加，不需要的业务模块无需复制到项目中。

打开游戏模块的 <GameModule>.Build.cs，添加 TapCore 依赖：

PublicDependencyModuleNames.AddRange(
    new string[]
    {
        "Core",
        "CoreUObject",
        "Engine",
        "TapCore"
    }
);

修改 Build.cs 后，右键 .uproject 文件并选择 Generate Visual Studio project files，然后重新编译项目。

初始化

新版 SDK 采用统一初始化机制。核心参数使用 FTapTapSdkOptions 配置；业务模块不再分别调用初始化方法，需要自定义模块参数时，通过 TArray<FTapSdkOption> 随核心参数一起传入。

按“配置核心和模块参数 → 注册初始化回调 → 调用一次 Init()”的顺序接入。以下为完整示例，在游戏启动流程（如 GameInstance 初始化）中，从游戏线程调用一次 InitializeTapSdk()：

#include "TapCore.h"
#include "TapTapSdkOptions.h"

class FGameInitCallback : public ITapInitCallback
{
public:
    virtual void OnInitSuccess() override
    {
        FTapTapSDK::RemoveInitCallback(this);
        // 初始化成功，可以继续登录、成就等业务流程。
    }

    virtual void OnInitFail(int32 ErrorCode, const FString& ErrorMessage) override
    {
        FTapTapSDK::RemoveInitCallback(this);
        UE_LOG(LogTemp, Error, TEXT("TapSDK 初始化失败 [%d]: %s"),
            ErrorCode, *ErrorMessage);
        // 暂停后续业务流程，按下文错误码说明处理。
    }
};

// 静态对象持续存活，避免异步回调引用已销毁的局部变量。
static FGameInitCallback InitCallback;

void InitializeTapSdk()
{
    FTapTapSdkOptions TapSdkOptions;
    // 客户端 ID 和令牌，开发者后台获取。
    TapSdkOptions.ClientID = TEXT("<CLIENT_ID>");
    TapSdkOptions.ClientToken = TEXT("<CLIENT_TOKEN>");
    // 地区，CN 为国内，Global 为海外。
    TapSdkOptions.Region = ETapRegion::CN;
    // 语言，默认自动获取系统语言。
    TapSdkOptions.PreferredLanguage = ETapLanguage::Auto;
    // 应用版本号；留空时读取应用的版本号。
    TapSdkOptions.GameVersion = TEXT("<GAME_VERSION>");
    // 是否开启日志，Release 版本请设置为 false。
    TapSdkOptions.bEnableLog = true;
    // 屏幕方向：0-竖屏 1-横屏，仅移动端生效。
    TapSdkOptions.ScreenOrientation = 1;
    // 仅接入 TapTap PC 客户端时填写，其他场景保持为空。
    // TapSdkOptions.ClientPublicKey = TEXT("<CLIENT_PUBLIC_KEY>");

    TArray<FTapSdkOption> ModuleOptions;
    // 可选：自定义 TapTap Event 参数。不需要时可省略下面四行。
    FTapTapEventOptions TapTapEventOptions;
    TapTapEventOptions.bEnableTapTapEvent = true;
    TapTapEventOptions.Channel = TEXT("<CHANNEL>");
    ModuleOptions.Add(FTapSdkOption::Make<FTapTapEventOptions>(TapTapEventOptions));

    // 如需配置合规、成就等模块，在此处加入同一个 ModuleOptions 数组。
    FTapTapSDK::AddInitCallback(&InitCallback);
    FTapTapSDK::Init(TapSdkOptions, ModuleOptions);
}

Init() 是异步过程，返回不代表初始化成功。请等待 OnInitSuccess() 后再调用业务 API。

初始化具体参数如下：

参数名	是否必填	说明
ClientID	是	客户端 ID，开发者后台获取
ClientToken	是	客户端令牌，开发者后台获取
ClientPublicKey	否	Windows 平台的 TapTap PC 客户端公钥，开发者后台获取，仅接入 TapTap PC 客户端需要
Region	否	地区，默认国内；ETapRegion::CN 为国内，ETapRegion::Global 为海外
PreferredLanguage	否	语言，默认自动获取系统语言
GameVersion	否	应用版本号，默认读取应用的版本号
bEnableLog	否	是否开启日志，默认关闭，建议开发阶段开启，上线前关闭
ScreenOrientation	否	屏幕方向：0-竖屏 1-横屏，仅移动端生效，默认为横屏

获取初始化结果

上面的完整示例已在 Init() 前通过 AddInitCallback() 注册监听，并在成功或失败回调中注销监听。如果需要在初始化结束前停止监听，也必须先调用 FTapTapSDK::RemoveInitCallback(&InitCallback)，再销毁回调对象。

ErrorCode 取值如下：

ErrorCode	说明
1000	初始化参数非法（如 ClientID/ClientToken 为空）
1001	应用信息与开发者中心配置不一致（包名/BundleID 与 ClientID/ClientToken），需检查配置后重新发布，无法通过重试恢复
1003	SDK 内部异常

info

Init() 需在游戏线程调用，并确保回调对象在取消注册前持续有效。

移动端工程配置

Android

生成 APK 文件前，需确保工程中已配置正确的 package name 和签名文件，并与 TapTap 开发者中心的应用配置保持一致。

TapCore 插件会通过 UPL 自动添加 Android SDK 依赖和网络权限。首次构建需要网络连接以下载 Maven 依赖。

iOS

导出 Xcode 工程前需配置 icon 和 BundleID，并确保 BundleID 与 TapTap 开发者中心的应用配置保持一致。

常见问题

编译报错 mergeJavaResource task

如果 Android Build Output 中的 :app:mergeDebugJavaResource 任务报告 More than one file was found with OS independent path 'nativeCommonMain/default/linkdata/module'，请检查项目是否重复引入了包含该文件的 AAR 依赖。

如果修改过 Gradle 或 AGP 配置，请检查是否覆盖了 UE5 生成的配置，并按当前引擎版本的 Android 开发环境要求调整。

运行时报错签名不匹配或 signature not match

检查 TapTap 开发者后台配置的应用包名和签名信息是否和当前工程设置一致。

Manifest 中出现 requestLegacyExternalStorage

该属性不是由 TapCore 添加的。UE5.7 在非 Distribution 构建、Android SDK Level 不低于 29 且项目未显式配置该属性时，可能向最终 Manifest 添加 android:requestLegacyExternalStorage="true"。该行为用于旧版存储兼容；应用运行于 Android 11 或更高版本且 targetSdkVersion 不低于 30 时，系统会忽略该属性。请根据引擎版本和项目自身的存储需求处理，无需为 TapCore 单独添加或移除。

Android 构建时无法下载 SDK 依赖

确认网络可用，并检查 Gradle 日志中是否成功解析 TapSDK 依赖。如果项目有自定义 Gradle 配置，确认没有覆盖插件 UPL 添加的依赖、仓库、权限或混淆规则。

iOS 导出 Xcode 后运行报 Swift 符号错误

请先确认 Xcode 版本与所用 UE5 版本匹配。UE5.7 对应 Xcode 16；调整工具链后重新导出并构建，同时检查项目和插件链接的 iOS xcframework。

编译时找不到 TapCore

确认 <YourProject>/Plugins/TapCore 已放入工程并在 Edit > Plugins 中启用，游戏模块的 Build.cs 已添加 TapCore。修改插件或模块依赖后，重新生成项目文件并编译。