版本：v4

Android SDK 开发指南

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

集成前准备

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

权限说明

该模块需要如下权限：

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

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

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

SDK 获取

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

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

初始化额外配置

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

Android Java
Android Kotlin

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;

TapTapSdkOptions tapSdkOptions = new TapTapSdkOptions(
        "clientId", // 游戏 Client ID
        "clientToken", // 游戏 Client Token
        TapTapRegion.CN // 游戏可玩区域: [TapTapRegion.CN]=国内 [TapTapRegion.GLOBAL]=海外
);
// 可选配置 成就模块
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.TapTapRegion

TapTapSdk.init(
    context = context,
    sdkOptions = TapTapSdkOptions(
        clientId = "clientId", // 游戏 Client ID
        clientToken = "clientToken", // 游戏 Client Token
        region = TapTapRegion.CN // 游戏可玩区域: [TapTapRegion.CN]=国内 [TapTapRegion.GLOBAL]=海外
    ),
    options = arrayOf(
        TapTapAchievementOptions(
            // 成就达成时 SDK 是否需要展示一个气泡弹窗提示
            enableToast = true
        )
    )
)

注册监听回调

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

Android Java
Android Kotlin

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) {
        // 成就状态更新成功
        // code TapAchievementResultCode.UNLOCK_ACHIEVEMENT_SUCCESS 70001 解锁成就成功
        // code TapAchievementResultCode.INCREMENT_ACHIEVEMENT_SUCCESS 70002 增加步长成功
        // result 成就数据详情
    }

    @Override
    public void onAchievementFailure(@NonNull String achievementId, int errorCode, @NonNull String errorMessage) {
        // 成就状态更新失败或其他错误
        // achievementId 触发失败的成就 ID，如果调用的是 showAchievements 接口，则为 "" 空字符串
        // errorCode 错误码
        // 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?) {
        // 成就状态更新成功
        // code TapAchievementResultCode.UNLOCK_ACHIEVEMENT_SUCCESS 70001 解锁成就成功
        // code TapAchievementResultCode.INCREMENT_ACHIEVEMENT_SUCCESS 70002 增加步长成功
        // result 成就数据详情
    }

    override fun onAchievementFailure(achievementId: String, errorCode: Int, errorMessage: String) {
        // 成就状态更新失败或其他错误
        // achievementId 触发失败的成就 ID，如果调用的是 showAchievements 接口，则为 "" 空字符串
        // errorCode 错误码
        // errorMessage 错误描述
    }
}

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

成就常量定义：

object TapAchievementResultCode {
    // 解锁成就成功，包括步长达到阈值解锁和直接解锁
    const val UNLOCK_ACHIEVEMENT_SUCCESS = 70001

    // 增加步长成功
    const val INCREMENT_ACHIEVEMENT_SUCCESS = 70002

    // 上报失败，未初始化
    const val NOT_INITIALIZED = 80000

    // 区域不支持
    const val REGION_NOT_SUPPORTED = 80001

    // 上报失败，未登录
    const val LOGIN_REQUIRED = 80002

    // 认证信息无效
    const val ACCESS_DENIED = 80010

    // 服务端错误
    const val SERVER_ERROR = 80020

    // 网络异常
    const val NETWORK_ERROR = 80030

    // 未知异常
    const val UNKNOWN_ERROR = 80100
}

成功数据详情

TapAchievementResult

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

错误码详情

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

解锁某个成就

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

Android Java
Android Kotlin

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

import com.taptap.sdk.achievement.TapTapAchievement

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

分步成就增长步数

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

Android Java
Android Kotlin

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)

设置冒泡开关

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

Android Java
Android Kotlin

import com.taptap.sdk.achievement.TapTapAchievement;

TapTapAchievement.setToastEnable(false);

import com.taptap.sdk.achievement.TapTapAchievement

TapTapAchievement.setToastEnable(enable = false)

打开成就展示页

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

Android Java
Android Kotlin

import com.taptap.sdk.achievement.TapTapAchievement;

TapTapAchievement.showAchievements();

import com.taptap.sdk.achievement.TapTapAchievement

TapTapAchievement.showAchievements()

国际化

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

集成前准备​

权限说明​

SDK 获取​

初始化额外配置​

注册监听回调​

成功数据详情​

错误码详情​

解锁某个成就​

分步成就增长步数​

设置冒泡开关​

打开成就展示页​

国际化​