Skip to main content
Version: v4

成就系统开发指南

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

权限说明​

集成前准备​

  1. 参考 准备工作 创建应用、开启成就服务。

SDK 获取​

由于 TapSDK V4 依赖于 TapTapCore 核心库，所以需要在 TapTapCore 的基础上，另外添加 TapTapAchievement 、 TapTapLogin 模块：

第一步：添加 SDK 所需的外部依赖​

SDK 内部使用了部分第三方库，开发者接入时需先确保 SDK 外部依赖库已正常接入，具体设置如下：

  1. SDK 使用的 JSON 解析库为 Newtonsoft-json，如果当前工程已接入该依赖库，则不需额外处理，否则需在 Packages/manifest.json 添加如下依赖：
"com.unity.nuget.newtonsoft-json":"3.2.1"
  1. SDK 使用 com.google.external-dependency-manager 管理 Android、iOS 依赖，如果当前工程已接入该依赖库，则不需额外处理，否则需在 Packages/manifest.json 添加如下依赖：
{
   "dependencies": {
      "com.google.external-dependency-manager": "1.2.179"
   },
   "scopedRegistries": [
      {
         "name": "package.openupm.com",
         "url": "https://package.openupm.com",
         "scopes": [
            "com.google.external-dependency-manager"
         ]
      }
  ]
}

第二步：添加 SDK 依赖​

SDK 支持 Unity Package Manager 及本地文件导入两种集成方式，开发者根据需求选择其中一种即可，推荐使用远程依赖。

远程依赖​

SDK 支持通过 NPMJS 及 GitHub 两种方式，开发者选择其中一种即可。

1. NPMJS 接入​

在项目的 Packages/manifest.json 文件中添加以下依赖：

"dependencies":{
   "com.taptap.sdk.core":"4.9.1",
   "com.taptap.sdk.achievement":"4.9.1",
   "com.taptap.sdk.login":"4.9.1",
}

但需要注意的是，需在 Packages/manifest.json 中 dependencies 同级下声明 scopedRegistries：

"scopedRegistries":[
  {
    "name": "NPMJS",
    "url": "https://registry.npmjs.org/",
    "scopes": ["com.taptap"]
  }
]
2. GitHub 接入​

在项目的 Packages/manifest.json 文件中添加以下依赖：

"dependencies":{
   "com.taptap.sdk.core":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Core#4.9.1",
   "com.taptap.sdk.login":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Login#4.9.1",
   "com.taptap.sdk.achievement":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Achievement#4.9.1",
}

说明：自 4.7.2 起，Unity Packages 仓库已统一为大仓 tapsdk-unity-dist，所有包通过目录区分并使用 ?path= 指定子目录、# 指定版本标签。例如 Core 模块：

"com.taptap.sdk.core": "https://github.com/taptap/tapsdk-unity-dist.git?path=/Core#4.7.2"

在 Unity 顶部菜单中选择 Window > Package Manager 可查看已经安装在项目中的包。

本地文件导入​

  1. 在 下载页 下载下列模块对应 unitypackage 文件，并在 Unity 项目中依次通过 Assets > Import Packages > Custom Packages 进行导入，包括：
  • TapSDK_Core.unitypackage TapTapSDK 核心模块，必选。
  • TapSDK_Login.unitypackage TapTapSDK 登录模块，必选。
  • TapSDK_Achievement.unitypackage TapTapSDK 成就模块，必选。
  1. 如果当前项目已集成 Newtonsoft.Json 依赖，则忽略该步骤，否则在 NuGet.org Newtonsoft.Json 页面中通过点击右侧 「Download package」 下载库文件，并将下载的文件后缀从.nupkg 修改为 .zip，同时解压该文件并复制内部的 Newtonsoft.Json.dll 文件拷贝到工程 Assets 的 Plugins 目录下，另外为了避免导出 IL2CPP 平台时删除必要数据，需在 Assets 目录下创建 link.xml 文件（如果已有该文件，则添加如下内容），其内容如下：
<linker>
  <assembly fullname="System.Core">
    <type fullname="System.Linq.Expressions.Interpreter.LightLambda" preserve="all" />
  </assembly>
</linker>

SDK 初始化​

详见 TapTapSDK 初始化文档。

TapTapSdkOptions 详细参数见 入门指南#快速开始

using TapSDK.Core;
using TapSDK.Achievement;
 
// 核心配置 详细参数见 [TapTapSDK]
TapTapSdkOptions coreOptions = new TapTapSdkOptions();
// 成就配置
TapTapAchievementOptions achievementOptions = new TapTapAchievementOptions
{
    // 成就达成时 SDK 是否需要展示一个气泡弹窗提示
    enableToast = true
};
// 其他模块配置项
TapTapSdkBaseOptions[] otherOptions = new TapTapSdkBaseOptions[]
{
    achievementOptions
};
// TapSDK 初始化
TapTapSDK.Init(coreOptions, otherOptions);

注册监听回调​

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

using TapSDK.Achievement;

AchievementCallback callback = new AchievementCallback();
TapTapAchievement.RegisterCallBack(callback);
TapTapAchievement.UnRegisterCallBack(callback);

class AchievementCallback : ITapAchievementCallback
{

    public AchievementCallback(){}
  
    public void OnAchievementSuccess(int code, TapAchievementResult result)
    {
        // 成就状态更新成功
        // code 70001 解锁成就成功
        // code 70002 增加步长成功
        // result 成就数据详情
    }
  
    public void OnAchievementFailure(string achievementId, int errorCode, string errorMsg)
    {
        // 成就状态更新失败或其他错误
        // achievementId 触发失败的成就 ID， 如果调用的是 [ShowAchievements] 接口，则为 "" 空字符串。
        // errorCode 错误码
        // errorMsg 错误描述
	}

}

成就常量定义：

namespace TapSDK.Achievement
{
    public class TapTapAchievementConstants
    {
        // 未初始化
        public static readonly int NOT_INITIALIZED = 80000;
        // 区域不支持
        public static readonly int REGION_NOT_SUPPORTED = 80001;
        // 当前未登录，需要登录
        public static readonly int NOT_LOGGED = 80002;
        // 当前登录失效，需要重新登录
        public static readonly int ACCESS_DENIED = 80010;
        // 无效参数
        public static readonly int INVALID_REQUEST = 80020;
        // 网络异常
        public static readonly int NETWORK_ERROR = 80030;
        // 未知错误，如：代理导致网络错误
        public static readonly int UNKNOWN_ERROR = 80100;

        // unlock解锁成就成功
        public static readonly int UNLOCK_SUCCESS = 70001;
        // 增加步长成功
        public static readonly int INCREMENT_SUCCESS = 70002;
    }
}

成功数据详情​

TapAchievementResult

字段含义
achievementId成就id
achievementName成就名称
achievementType成就类型，分为普通成就（TapAchievementType.NORMAL）、白金成就（TapAchievementType.PLATINUM）
currentSteps当前成就进度，如果不是分步式成就该值为 0

错误码详情​

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

解锁某个成就​

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

using TapSDK.Achievement;

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

分步成就增长步数​

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

using TapSDK.Achievement;

// achievementId 是在开发者中心中添加成就时自行设定的 成就 Id
string achievementId = "achievementId";
// step 是增长的步数
int step = 1;
TapTapAchievement.Increment(achievementId : achievementId, step : step);

设置冒泡开关​

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

using TapSDK.Achievement;

TapTapAchievement.SetToastEnable(false);

打开成就展示页​

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

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

using TapSDK.Achievement;

TapTapAchievement.ShowAchievements();

国际化​

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