版本：v4

成就系统开发指南

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

权限说明

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

该模块需要如下权限：

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

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

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

该模块需要如下权限：

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

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

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

集成前准备

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

SDK 获取

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

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

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

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

SDK 使用的 JSON 解析库为 Newtonsoft-json，如果当前工程已接入该依赖库，则不需额外处理，否则需在 Packages/manifest.json 添加如下依赖：

"com.unity.nuget.newtonsoft-json":"3.2.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.5.7",
    "com.taptap.sdk.achievement":"4.5.7",
    "com.taptap.sdk.login":"4.5.7",
}

但需要注意的是，需在 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/TapSDKCore-Unity.git#4.5.7",
   "com.taptap.sdk.login":"https://github.com/taptap/TapSDKLogin-Unity.git#4.5.7",
   "com.taptap.sdk.achievement":"https://github.com/taptap/TapSDKAchievement-Unity.git#4.5.7", 
}

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

本地文件导入

在下载页下载下列模块对应 unitypackage 文件，并在 Unity 项目中依次通过 Assets > Import Packages > Custom Packages 进行导入，包括：

TapSDK_Core.unitypackage TapTapSDK 核心模块，必选。
TapSDK_Login.unitypackage TapTapSDK 登录模块，必选。
TapSDK_Achievement.unitypackage TapTapSDK 成就模块，必选。

如果当前项目已集成 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>

项目根目录的 build.gradle 添加仓库地址：

allprojects { 
    repositories {
        google()
        mavenCentral()
    }
}

app module 的 build.gradle 添加对应依赖：

dependencies {
  implementation 'com.taptap.sdk:tap-core:4.5.7'
  implementation 'com.taptap.sdk:tap-achievement:4.5.7'
  // 成就模块依赖登录
  implementation 'com.taptap.sdk:tap-login:4.5.7'
}

项目根目录的 build.gradle 添加仓库地址：

allprojects { 
    repositories {
        google()
        mavenCentral()
    }
}

app module 的 build.gradle 添加对应依赖：

dependencies {
  implementation 'com.taptap.sdk:tap-core:4.5.7'
  implementation 'com.taptap.sdk:tap-achievement:4.5.7'
}

iOS 提供通过添加 cocoaPods 远程依赖和使用本地文件导入两种集成方式，推荐使用远程依赖方式。

远程依赖

在工程 Podfile 文件中对应模块下添加依赖：

 pod 'TapTapAchievementSDK', '~> 4.5.5'

执行 Pod install 下载对应依赖文件
将工程 Pods 目录下 TapTapAchievementSDK/Frameworks/TapTapAchievementResource.bundle 和 TapTapLoginSDK/Frameworks/TapTapLoginResource.bundle 等资源文件导入工程中

本地文件依赖

成就模块依赖于 Tap 登录模块，使用本地文件方式添加依赖时，需先参考入门指南和 TapTap 登录添加对应本地文件依赖项。

在下载页下载如下文件：

TapTapAchievementSDK 成就依赖库
TapTapAchievementResource.bundle 成就资源文件

在工程中添加 framework 静态库，注意添加时选择 Embed 方式为 Do Not Embed，导入 bundle 资源文件

iOS 提供通过添加 cocoaPods 远程依赖和使用本地文件导入两种集成方式，推荐使用远程依赖方式。

远程依赖

在工程 Podfile 文件中对应模块下添加依赖：

 pod 'TapTapAchievementSDK', '~> 4.5.5'

执行 Pod install 下载对应依赖文件
将工程 Pods 目录下 TapTapAchievementSDK/Frameworks/TapTapAchievementResource.bundle 和 TapTapLoginSDK/Frameworks/TapTapLoginResource.bundle 等资源文件导入工程中

本地文件依赖

成就模块依赖于 Tap 登录模块，使用本地文件方式添加依赖时，需先参考入门指南和 TapTap 登录添加对应本地文件依赖项。

在下载页下载如下文件：

TapTapAchievementSDK 成就依赖库
TapTapAchievementResource.bundle 成就资源文件

在工程中添加 framework 静态库，注意添加时选择 Embed 方式为 Do Not Embed，导入 bundle 资源文件

SDK 初始化

详见 TapTapSDK 初始化文档。

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

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);

import com.taptap.sdk.achievement.options.TapTapAchievementOptions;
import com.taptap.sdk.core.TapTapRegion;
import com.taptap.sdk.core.TapTapSdk;
import com.taptap.sdk.core.TapTapSdkOptions;

/* 必选配置 */
// 开发者中心对应 Client ID
String clientId = "";
// 开发者中心对应 Client Token
String clientToken = "";
// 是否开启 log，建议 Debug 开启，Release 关闭，默认关闭 log
boolean enableLog = BuildConfig.DEBUG;

TapTapSdkOptions tapSdkOptions = new TapTapSdkOptions(
        clientId, // 游戏 Client ID
        clientToken, // 游戏 Client Token
        TapTapRegion.CN // 游戏可玩区域: [TapTapRegion.CN]=国内 [TapTapRegion.GLOBAL]=海外
);
tapSdkOptions.setEnableLog(enableLog);
// 可选配置 成就模块
TapTapAchievementOptions tapAchievementOptions = new TapTapAchievementOptions(
       true // 解锁成就弹出 Toast 提示，默认 true
);
// 初始化 TapSDK
TapTapSdk.init(context, tapSdkOptions, tapAchievementOptions);

import com.taptap.sdk.core.TapTapSdk
import com.taptap.sdk.core.TapTapSdkOptions
import com.taptap.sdk.achievement.options.TapTapAchievementOptions
import com.taptap.sdk.core.TapTapLanguage
import com.taptap.sdk.core.TapTapRegion

TapTapSdk.init(
    context = context,
    sdkOptions = TapTapSdkOptions(
        clientId = clientId,
        clientToken = clientToken,
        region = TapTapRegion.CN,
        preferredLanguage = TapTapLanguage.ZH_HANS,
        enableLog = false
    ),
    options = arrayOf(
        TapTapAchievementOptions(
            // 成就达成时 SDK 是否需要展示一个气泡弹窗提示
            enableToast = true
        )
    )
)

import TapTapAchievementSDK
import TapTapCoreSDK

// 核心配置
let coreOptions = TapTapSdkOptions()
// TODO: coreOptions 配置

// 成就配置
let achievementOptions = TapTapAchievementOptions()
// 成就达成时 SDK 是否需要展示一个气泡弹窗提示
achievementOptions.enableToast = true

// 其他模块配置项
let otherOptions = [achievementOptions]

// TapSDK 初始化
TapTapSDK.initWith(coreOptions, otherOptions: otherOptions)

#import "TapTapCoreSDK/TapTapSDK.h"
#import "TapTapAchievementSDK/TapTapAchievementSDK-Swift.h"

// 核心配置项
TapTapSdkOptions *options = [[TapTapSdkOptions alloc] init];
// TODO: 应用信息配置

// 成就配置
TapTapAchievementOptions *achievementOptions = [[TapTapAchievementOptions alloc] init];
// 成就达成时 SDK 是否需要展示一个气泡弹窗提示
achievementOptions.enableToast = YES;

// 其他模块配置项
NSArray *otherOptions = @[achievementOptions];

// TapSDK 初始化
[TapTapSDK initWithOptions:options otherOptions:otherOptions];

注册监听回调

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

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

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;
    }
}

import com.taptap.sdk.achievement.TapAchievementCallback;
import com.taptap.sdk.achievement.TapTapAchievement;
import com.taptap.sdk.achievement.TapTapAchievementResult;

TapAchievementCallback callback = new TapAchievementCallback(){

    @Override
    public void onAchievementSuccess(int code, @Nullable TapTapAchievementResult result) {
        // 成就状态更新成功
    }
    
    @Override
    public void onAchievementFailure(@NonNull String achievementId, int errorCode, @NonNull String errorMessage) {
        // 成就状态更新失败
    }

};
TapTapAchievement.registerCallback(callback);
TapTapAchievement.unregisterCallback(callback);

import com.taptap.sdk.achievement.TapTapAchievement
import com.taptap.sdk.achievement.TapAchievementCallback
import com.taptap.sdk.achievement.TapTapAchievementResult

val callback = object : TapAchievementCallback {
    override fun onAchievementSuccess(code: Int, result: TapTapAchievementResult?) {
        // 成就状态更新成功
    }

    override fun onAchievementFailure(achievementId: String, errorCode: Int, errorMessage: String) {
        // 成就状态更新失败
    }
}

TapTapAchievement.registerCallback(callback = callback)
TapTapAchievement.unregisterCallback(callback)

import TapTapAchievementSDK

class CallbackImpl: NSObject, TapTapAcheievementCallback {

		override init() {}
		
		// 成就状态更新成功
		func onAchievementSuccess(code: Int, result: TapTapAchievementResult) {
	        // code 70001 解锁成就成功
	        // code 70002 增加步长成功
	        // result 成就数据详情
        }
		
		// 成就状态更新失败或其他错误    
		func onAchievementFailure(achievementId: String, errorCode: Int, errorMsg: String) {
			 // achievementId 触发失败的成就 ID， 如果调用的是 [ShowAchievements] 接口，则为 "" 空字符串。
        	 // errorCode 错误码
        	 // errorMsg 错误描述
		 }
}
let callback = CallbackImpl()
TapTapAchievement.registerCallback(callback: callback)

// 不需要接收回调时调用接口移除之前设置的回调对象
TapTapAchievement.unregisterCallback(callback: callback)

成就常量定义：

public class TapAchievementCallbackCode: NSObject {
    // 解锁成就成功，包括步长达到阈值解锁和直接解锁
    public static let UNLOCK_SUCCESS = 70001
    
    // 增加步长成功
    public static let INCREMENT_SUCCESS = 70002
    
    // 上报失败，未初始化
    public static let NOT_INITIALIZED = 80000
    
    // 区域不支持
    public static let REGION_NOT_SUPPORTED = 80001
    
    // 上报失败，未登录
    public static let NOT_LOGGED = 80002
    
    // 认证信息无效
    public static let ACCESS_DENIED = 80010
    
    // 无效请求
    public static let INVALID_REQUEST = 80020
    
    // 网络异常
    public static let NETWORK_ERROR = 80030
    
    // 未知异常
    public static let UNKNOWN_ERROR = 80100
}

#import "TapTapAchievementSDK/TapTapAchievementSDK-Swift.h"

@interface GameMainController () <TapTapAcheievementCallback>

@end
@implementation GameMainController

- (void)handleAchievemntCallback {
    //注册回调
    [TapTapAchievement registerCallbackWithCallback:self];
    
    // 不需要接收回调时调用接口移除之前设置的回调对象
    [TapTapAchievement unregisterCallbackWithCallback:self];
}

- (void)onAchievementFailureWithAchievementId:(NSString * _Nonnull)achievementId errorCode:(NSInteger)errorCode errorMsg:(NSString * _Nonnull)errorMsg { 
    // achievementId 触发失败的成就 ID， 如果调用的是 [ShowAchievements] 接口，则为 "" 空字符串。
    // errorCode 错误码
    // errorMsg 错误描述
}

- (void)onAchievementSuccessWithCode:(NSInteger)code result:(TapTapAchievementResult * _Nonnull)result { 
    // code 70001 解锁成就成功
    // code 70002 增加步长成功
    // result 成就数据详情
}

成功数据详情

TapAchievementResult

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

错误码详情

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

解锁某个成就

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

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

using TapSDK.Achievement;

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

import com.taptap.sdk.achievement.TapTapAchievement;
// achievementId 是在开发者中心中添加成就时自行设定的 成就 Id
TapTapAchievement.unlock("achievementId");

import com.taptap.sdk.achievement.TapTapAchievement

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

import TapTapAchievementSDK

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

#import "TapTapAchievementSDK/TapTapAchievementSDK-Swift.h"

// achievementId 是在开发者中心中添加成就时自行设定的成就 Id
[TapTapAchievement unlockWithAchievementId:achievementId];

分步成就增长步数

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

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

using TapSDK.Achievement;

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

import com.taptap.sdk.achievement.TapTapAchievement;
// achievementId 为在开发者中心中添加成就时自行设定的成就 Id
// steps 为增长的步数
int steps = 1;
TapTapAchievement.increment("achievementId", steps);

import com.taptap.sdk.achievement.TapTapAchievement

TapTapAchievement.increment(achievementId = "achievementId", steps = 1)

import TapTapAchievementSDK

// achievementId 为在开发者中心中添加成就时自行设定的成就 Id
let achievementId = "achievementId"
// steps 为增长的步数
let steps = 1
// 更新成就步长数据
TapTapAchievement.increment(achievementId: achievementId, steps: steps)

#import "TapTapAchievementSDK/TapTapAchievementSDK-Swift.h"

// achievementId 为在开发者中心中添加成就时自行设定的成就 Id
NSString *achievementId = @"achievementId";
// steps 为增长的步数
NSInteger steps = 1;
// 更新成就步长数据
[TapTapAchievement incrementWithAchievementId:achievementId steps:steps];

设置冒泡开关

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

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

using TapSDK.Achievement;

TapTapAchievement.SetToastEnable(false);

import com.taptap.sdk.achievement.TapTapAchievement;

TapTapAchievement.setToastEnable(false);

import com.taptap.sdk.achievement.TapTapAchievement

TapTapAchievement.setToastEnable(enable = false)

import TapTapAchievementSDK

TapTapAchievement.setToastEnable(enable: false)

#import "TapTapAchievementSDK/TapTapAchievementSDK-Swift.h"

[TapTapAchievement setToastEnableWithEnable:NO];

打开成就展示页

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

Unity
Android Java
Android Kotlin
iOS Swift
iOS Objective-C

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

using TapSDK.Achievement;

TapTapAchievement.ShowAchievements();

import com.taptap.sdk.achievement.TapTapAchievement;

TapTapAchievement.showAchievements();

import com.taptap.sdk.achievement.TapTapAchievement

TapTapAchievement.showAchievements()

import TapTapAchievementSDK

TapTapAchievement.showAchievements()

#import "TapTapAchievementSDK/TapTapAchievementSDK-Swift.h"

[TapTapAchievement showAchievements];

国际化

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

权限说明​

集成前准备​

SDK 获取​

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

第二步：添加 SDK 依赖​

远程依赖​

1. NPMJS 接入​

2. GitHub 接入​

本地文件导入​

SDK 初始化​

注册监听回调​

成功数据详情​

错误码详情​

解锁某个成就​

分步成就增长步数​

设置冒泡开关​

打开成就展示页​

国际化​