Unity SDK 开发指南

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

集成前准备

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

权限说明

Android 权限说明

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

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

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

<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.11.1",
  "com.taptap.sdk.login":"4.11.1",
  "com.taptap.sdk.achievement":"4.11.1"
}

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

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

本地文件导入

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

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

初始化额外配置

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

using TapSDK.Core;
using TapSDK.Achievement;
 
// 核心配置 详细参数见 [TapTapSDK]
TapTapSdkOptions coreOptions = 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	错误类型	错误原因
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 回调。具体错误码请参考 错误码详情

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 支持设置语言：目前只支持简体中文