跳到主要内容
版本：v4

成就系统开发指南

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

集成前准备​

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

权限说明​

该模块需要如下权限：

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

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

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

SDK 获取​

远程依赖​

NPMJS 方式：在 Packages/manifest.json 中添加：

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

GitHub 方式：在 Packages/manifest.json 中添加：

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

本地文件导入​

在 下载页 下载并导入以下 unitypackage 文件：

  • TapSDK_Core.unitypackage (TapTapSDK 核心模块，必选)
  • TapSDK_Login.unitypackage（TapTapSDK 登录模块，必选）
  • TapSDK_Achievement.unitypackage (TapTapSDK 成就模块，必选)

初始化额外配置​

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

using TapSDK.Core;
using TapSDK.Achievement;
 
// 核心配置 详细参数见 [TapTapSDK]
TapTapSdkOptions coreOptions = new new TapTapSdkOptions
{
   // 客户端 ID，开发者后台获取
   clientId = clientId,
   // 客户端令牌，开发者后台获取
   clientToken = clientToken
};
// 成就配置
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 支持设置语言：目前只支持简体中文