Skip to main content
Version: v4

Android SDK 开发指南

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

集成前准备​

  1. 参考 开发者中心配置 创建应用、配置包名与签名证书
  2. 参考 成就系统功能介绍开通成就系统服务
  3. 参考 Android 集成指南 完成基础接入
  4. 成就模块依赖于 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'
}

初始化额外配置​

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

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

注册监听回调​

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

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

成就常量定义：

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

解锁某个成就​

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

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

分步成就增长步数​

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

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

设置冒泡开关​

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

import com.taptap.sdk.achievement.TapTapAchievement;

TapTapAchievement.setToastEnable(false);

打开成就展示页​

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

import com.taptap.sdk.achievement.TapTapAchievement;

TapTapAchievement.showAchievements();

国际化​

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