跳到主要内容
版本：v4

UE5 SDK 开发指南

本文介绍如何在游戏中加入成就系统。

集成前准备​

  1. 参考 开发者中心配置 创建应用、配置包名与签名证书
  2. 参考 成就系统功能介绍开通成就系统服务
  3. 参考 UE5 集成指南完成基础接入
  4. 成就模块依赖于 TapTap 登录模块，开发者接入前应先完成 TapTap 登录的接入

成就服务目前仅支持中国大陆，核心初始化参数 Region 使用 ETapRegion::CN。等待初始化和登录成功后再调用成就接口。

权限说明​

Android 权限说明​

该模块在 Android 平台需要如下权限：

权限使用目的权限申请时机
网络权限用于访问网络数据用户首次使用该功能时会申请权限
网络状态权限用于检查网络连接状态（如 Wi-Fi 或移动数据是否可用）用户首次使用该功能时会申请权限

该模块将在 Android 应用中添加如下权限：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

SDK 获取​

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

添加模块依赖​

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

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

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

初始化额外配置​

在调用业务接口前，开发者需先调用初始化接口完成应用信息的配置，示例如下：

成就模块可通过 FTapAchievementOptions.bEnableToast 设置初始解锁提示，默认值为 true。如需默认关闭提示，将以下 Option 合并到集成指南的初始化流程中：

#include "TapCore.h"
#include "TapAchievementOptions.h"

FTapAchievementOptions AchievementOptions;
AchievementOptions.bEnableToast = false;

TArray<FTapSdkOption> ModuleOptions;
ModuleOptions.Add(FTapSdkOption::Make<FTapAchievementOptions>(AchievementOptions));

// TapSdkOptions 为配置好的核心参数；调用前先注册初始化回调。
FTapTapSDK::Init(TapSdkOptions, ModuleOptions);

注册监听回调​

成就 SDK 中包含多个监听回调，分别会在初始化数据成功、初始化数据失败以及成就进度更新时被调用。

#include "TapAchievement.h"

UCLASS()
class UGameAchievementHandler : public UObject, public ITapAchievementCallback
{
    GENERATED_BODY()
public:
    virtual void OnAchievementSuccess_Implementation(
        int32 Code, const FTapAchievementResult& Result) override
    {
        // 成就状态更新成功
        // Code ETapAchievementError::UnlockSuccess 70001 解锁成就成功
        // Code ETapAchievementError::IncrementSuccess 70002 增加步长成功
        // Result 成就数据详情
    }

    virtual void OnAchievementFailure_Implementation(
        const FString& AchievementId, int32 ErrorCode, const FString& ErrorMessage) override
    {
        // 成就状态更新失败或其他错误
        // AchievementId 触发失败的成就 ID，如果调用的是 ShowAchievements 接口，则为 "" 空字符串
        // ErrorCode 错误码
        // ErrorMessage 错误描述
    }
};

// 在持有者类中声明并持有回调对象
UPROPERTY()
TObjectPtr<UGameAchievementHandler> AchievementHandler;

AchievementHandler = NewObject<UGameAchievementHandler>(this);
TScriptInterface<ITapAchievementCallback> Callback;
Callback.SetObject(AchievementHandler.Get());
Callback.SetInterface(Cast<ITapAchievementCallback>(AchievementHandler.Get()));
UTapAchievement::RegisterCallback(Callback);

// 不需要接收回调时，使用同一个对象注销
UTapAchievement::UnregisterCallback(Callback);

成就常量定义：

namespace ETapAchievementError
{
    // 解锁成就成功，包括步长达到阈值解锁和直接解锁
    constexpr int32 UnlockSuccess = 70001;

    // 增加步长成功
    constexpr int32 IncrementSuccess = 70002;

    // 上报失败，未初始化
    constexpr int32 NotInitialized = 80000;

    // 区域不支持
    constexpr int32 RegionNotSupported = 80001;

    // 上报失败，未登录
    constexpr int32 NotLogged = 80002;

    // 认证信息无效
    constexpr int32 AccessDenied = 80010;

    // 无效请求
    constexpr int32 InvalidRequest = 80020;

    // 网络异常
    constexpr int32 NetworkError = 80030;

    // 未知异常
    constexpr int32 UnknownError = 80100;
}

成功数据详情​

FTapAchievementResult

字段含义
AchievementId成就id
AchievementName成就名称
AchievementType成就类型，分为普通成就（ETapAchievementType::Normal）、白金成就（ETapAchievementType::Platinum）
CurrentSteps当前成就进度，如果不是分步式成就该值为 0

错误码详情​

errorCode错误类型错误原因
80000NotInitialized未初始化，在调用API之前请先初始化
80001RegionNotSupported区域不支持，成就目前只支持区域 CN , 请确认初始化参数 Region
80002NotLogged当前未登录，请在登录之后再使用报错API
80010AccessDenied当前登录失效，需要重新登录
80020InvalidRequest无效参数，请检查传入的参数是否正确
80030NetworkError网络异常, 请确认当前网络连接是否正常
80100UnknownError请确认当前网络连接是否正常 ，或者联系技术支持

解锁某个成就​

当玩家达成某一成就时，可以使用以下方式解锁成就，解锁成功后会触发 callback 的 OnAchievementSuccess 回调。 解锁失败会触发 callback 的 OnAchievementFailure 回调。具体错误码请参考 错误码详情

#include "TapAchievement.h"

// AchievementId 是在开发者中心中添加成就时自行设定的 成就 Id
UTapAchievement::Unlock(TEXT("achievementId"));

分步成就增长步数​

如果成就是增量类型（即，需要几个步骤才能解锁它）请使用以下API。SDK 会自动计算当前全量步数。 解锁成功后会触发 callback 的 OnAchievementSuccess 回调。 解锁失败会触发 callback 的 OnAchievementFailure 回调。具体错误码请参考 错误码详情

#include "TapAchievement.h"

// AchievementId 是在开发者中心中添加成就时自行设定的 成就 Id
FString AchievementId = TEXT("achievementId");
// Step 是增长的步数
int32 Step = 1;
UTapAchievement::Increment(AchievementId, Step);

设置冒泡开关​

默认情况下，成就达成时 SDK 会自行展示一个冒泡浮窗提示玩家已达成相应成就。需要关闭请调用如下接口或者在初始化的时候设置 FTapAchievementOptions.bEnableToast 为 false。详见 成就初始化配置

UTapAchievement::SetToastEnable(false);

打开成就展示页​

SDK 自带一个展示所有成就和已达成成就情况的页面。 当玩家设备上有安装TapTap客户端时，会跳转到TapTap客户端的成就页面，否则会在游戏内展示成就页面。

请注意：在PC平台上，调用此接口会打开外部浏览器展示成就页面。

UTapAchievement::ShowAchievements();

国际化​

TapTapAchievement 支持设置语言：目前只支持简体中文