跳到主要内容
版本：v4

UE5 SDK 集成（多平台）

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

环境要求​

  • UE5.7 或更高版本

编译工具链​

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

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

SDK 获取​

信息

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

从下载页下载 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），需检查配置后重新发布，无法通过重试恢复
1003SDK 内部异常
信息

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。修改插件或模块依赖后，重新生成项目文件并编译。