版本：v4

Android SDK 开发指南

本文介绍如何在游戏中加入排行榜系统。

集成前准备

参考开发者中心配置创建应用、配置包名与签名证书
参考 Android 集成指南完成基础接入
排行榜模块依赖于 TapTap 登录模块，开发者接入前应先完成 TapTap 登录的接入

权限说明

该模块需要如下权限：

权限	使用目的	权限申请时机
网络权限	用于访问网络数据	用户首次使用该功能时会申请权限
网络状态权限	用于检查网络连接状态（如 Wi-Fi 或移动数据是否可用）	用户首次使用该功能时会申请权限
写入外部存储权限	用于保存排行榜分享图片到设备存储	用户首次使用分享功能时会申请权限

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

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

SDK 获取

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

dependencies {
  implementation 'com.taptap.sdk:tap-core:4.11.0'
  implementation 'com.taptap.sdk:tap-login:4.11.0'
  implementation 'com.taptap.sdk:tap-leaderboard-androidx:4.11.0'
}

注册排行榜事件回调

排行榜 SDK 提供事件回调接口，用于处理排行榜相关事件，如用户未登录等状态。

Android Java
Android Kotlin

import com.taptap.sdk.leaderboard.androidx.TapTapLeaderboard;
import com.taptap.sdk.leaderboard.callback.TapTapLeaderboardCallback;

// 注册排行榜事件回调
TapTapLeaderboardCallback callback = new TapTapLeaderboardCallback() {
    @Override
    public void onLeaderboardResult(int code, String message) {
        // 处理排行榜事件
        switch (code) {
            case 500102:
                // 用户未登录，需要引导用户登录
                // showLoginDialog();
                break;
            // 处理其他事件
            default:
                Log.d("Leaderboard", "code: " + code + ", message: " + message);
                break;
        }
    }
};
TapTapLeaderboard.registerLeaderboardCallback(callback);
TapTapLeaderboard.unregisterLeaderboardCallback(callback);

import com.taptap.sdk.leaderboard.androidx.TapTapLeaderboard
import com.taptap.sdk.leaderboard.callback.TapTapLeaderboardCallback

// 注册排行榜事件回调
TapTapLeaderboard.registerLeaderboardCallback(
    callback = object : TapTapLeaderboardCallback {
        override fun onLeaderboardResult(code: Int, message: String) {
            // 处理排行榜事件
            when (code) {
                500102 -> {
                    // 用户未登录，需要引导用户登录
                    // showLoginDialog()
                }
                // 处理其他事件
                else -> {
                    Log.d("Leaderboard", "code: $code, message: $message")
                }
            }
        }
    }
)

// 取消注册回调
TapTapLeaderboard.unregisterLeaderboardCallback(callback = callback)

设置分享功能

设置分享回调后，排行榜H5页面会显示分享按钮，用户点击分享按钮后，排行榜截图会保存到本地，并触发分享成功回调。开发者可以根据自己的需要判断是否实现分享失败的回调方法。

Android Java
Android Kotlin

配置 FileProvider

在 Android 平台，为了正确获取分享图片的路径，需要配置 FileProvider。

在 AndroidManifest.xml 中添加 FileProvider 配置：

<provider
    android:name="androidx.core.content.FileProvider"
    android:authorities="${applicationId}.fileprovider"
    android:exported="false"
    android:grantUriPermissions="true">
    <meta-data
        android:name="android.support.FILE_PROVIDER_PATHS"
        android:resource="@xml/file_paths" />
</provider>

在 res/xml 目录下创建 file_paths.xml 文件（如果不存在则创建），内容如下：

<?xml version="1.0" encoding="utf-8"?>
<paths>
    <!-- 允许访问应用私有目录下的 files/shared_images/ -->
    <files-path name="shared_images" path="shared_images/" />
</paths>

设置分享回调

import com.taptap.sdk.leaderboard.androidx.TapTapLeaderboard;
import com.taptap.sdk.leaderboard.callback.TapTapLeaderboardShareCallback;

// 设置分享回调
TapTapLeaderboard.setShareCallback(new TapTapLeaderboardShareCallback() {
    @Override
    public void onShareSuccess(String localPath) {
        // 处理排行榜分享图片保存成功
        // localPath 为本地图片路径，可用于分享到系统
        // shareImageToSystem(localPath);
    }
    
    @Override
    public void onShareFailed(Throwable error) {
        // 处理分享失败（可选实现）
        // 开发者可以根据需要选择是否实现此方法
        Log.e("Leaderboard", "分享失败", error);
    }
});

配置 FileProvider

在 Android 平台，为了正确获取分享图片的路径，需要配置 FileProvider。

在 AndroidManifest.xml 中添加 FileProvider 配置：

<provider
    android:name="androidx.core.content.FileProvider"
    android:authorities="${applicationId}.fileprovider"
    android:exported="false"
    android:grantUriPermissions="true">
    <meta-data
        android:name="android.support.FILE_PROVIDER_PATHS"
        android:resource="@xml/file_paths" />
</provider>

在 res/xml 目录下创建 file_paths.xml 文件（如果不存在则创建），内容如下：

<?xml version="1.0" encoding="utf-8"?>
<paths>
    <!-- 允许访问应用私有目录下的 files/shared_images/ -->
    <files-path name="shared_images" path="shared_images/" />
</paths>

设置分享回调

import com.taptap.sdk.leaderboard.androidx.TapTapLeaderboard

// 设置分享回调
TapTapLeaderboard.setShareCallback(object : TapTapLeaderboardShareCallback {
    override fun onShareSuccess(localPath: String) {
        // 处理排行榜分享图片保存成功
        // localPath 为本地图片路径，可用于分享到系统
        // shareImageToSystem(localPath)
    }
    
    override fun onShareFailed(error: Throwable) {
        // 处理分享失败（可选实现）
        // 开发者可以根据需要选择是否实现此方法
        Log.e("Leaderboard", "分享失败", error)
    }
})

打开排行榜页面

打开排行榜H5页面对话框，支持总榜和好友榜两种类型。

提示

如果排行榜页面显示不完整、按钮被遮挡或布局方向异常，请先确认 TapSDK 初始化时的 screenOrientation 参数是否与游戏实际屏幕方向一致。

Android Java
Android Kotlin

import com.taptap.sdk.leaderboard.androidx.TapTapLeaderboard;

// 打开总榜
String leaderboardId = "your_leaderboard_id";
String collection = "public";
TapTapLeaderboard.openLeaderboard(
    this, // Activity
    leaderboardId,
    collection
);

// 打开好友榜
TapTapLeaderboard.openLeaderboard(
    this, // Activity
    "your_leaderboard_id",
    "friends"
);

import com.taptap.sdk.leaderboard.androidx.TapTapLeaderboard

// 打开总榜
val leaderboardId = "your_leaderboard_id"
val collection = "public"
TapTapLeaderboard.openLeaderboard(
    activity = this, // Activity
    leaderboardId = leaderboardId,
    collection = collection
)

// 打开好友榜
TapTapLeaderboard.openLeaderboard(
    activity = this, // Activity
    leaderboardId = "your_leaderboard_id",
    collection = "friends"
)

打开用户个人资料

展示指定用户的个人资料对话框，传入用户的openId。

Android Java
Android Kotlin

import com.taptap.sdk.leaderboard.androidx.TapTapLeaderboard;

// openId unionId二选一即可
String openId = "user_open_id";
String unionId = "";
TapTapLeaderboard.showTapUserProfile(
    this, // Activity
    openId, 
    unionId
);

import com.taptap.sdk.leaderboard.androidx.TapTapLeaderboard

// openId unionId二选一即可
val openId = "user_open_id"
val unionId = ""
TapTapLeaderboard.showTapUserProfile(
    activity = this, // Activity
    openId = openId, 
    unionId = unionId
)

提交分数

批量提交用户排行榜分数，一次最多提交5个分数。

Android Java
Android Kotlin

import com.taptap.sdk.leaderboard.androidx.TapTapLeaderboard;
import com.taptap.sdk.leaderboard.callback.TapTapLeaderboardResponseCallback;
import com.taptap.sdk.leaderboard.data.request.SubmitScoresRequest;
import com.taptap.sdk.leaderboard.data.response.SubmitScoresResponse;
import java.util.Arrays;
import java.util.List;

List<SubmitScoresRequest.ScoreItem> scores = Arrays.asList(
    new SubmitScoresRequest.ScoreItem("leaderboard_1", 1000L),
    new SubmitScoresRequest.ScoreItem("leaderboard_2", 2000L)
);

TapTapLeaderboard.submitScores(
    scores,
    new TapTapLeaderboardResponseCallback<SubmitScoresResponse>() {
        @Override
        public void onSuccess(SubmitScoresResponse data) {
            // 提交成功
            Log.d("Leaderboard", "提交成功: " + data);
        }

        @Override
        public void onFailure(int code, String message) {
            // 提交失败
            Log.e("Leaderboard", "提交失败: code=" + code + ", message=" + message);
        }
    }
);

import com.taptap.sdk.leaderboard.androidx.TapTapLeaderboard
import com.taptap.sdk.leaderboard.callback.TapTapLeaderboardResponseCallback
import com.taptap.sdk.leaderboard.data.request.SubmitScoresRequest
import com.taptap.sdk.leaderboard.data.response.SubmitScoresResponse

val scores = listOf(
    SubmitScoresRequest.ScoreItem("leaderboard_1", 1000),
    SubmitScoresRequest.ScoreItem("leaderboard_2", 2000)
)

TapTapLeaderboard.submitScores(
    scores = scores,
    callback = object : TapTapLeaderboardResponseCallback<SubmitScoresResponse> {
        override fun onSuccess(data: SubmitScoresResponse) {
            // 提交成功
            Log.d("Leaderboard", "提交成功: $data")
        }

        override fun onFailure(code: Int, message: String) {
            // 提交失败
            Log.e("Leaderboard", "提交失败: code=$code, message=$message")
        }
    }
)

获取排行榜数据

分页获取排行榜数据，支持总榜和好友榜。

Android Java
Android Kotlin

import com.taptap.sdk.leaderboard.androidx.TapTapLeaderboard;
import com.taptap.sdk.leaderboard.data.request.LeaderboardCollection;
import com.taptap.sdk.leaderboard.callback.TapTapLeaderboardResponseCallback;
import com.taptap.sdk.leaderboard.data.response.LeaderboardScoresResponse;

TapTapLeaderboard.loadLeaderboardScores(
    "your_leaderboard_id", // 排行榜ID
    LeaderboardCollection.PUBLIC, // 总榜
    null, // nextPage - 首次请求传null
    null, // periodToken - 时间周期标识
    new TapTapLeaderboardResponseCallback<LeaderboardScoresResponse>() {
        @Override
        public void onSuccess(LeaderboardScoresResponse data) {
            // 获取成功
            List<Score> scores = data.getScores();
            String nextPage = data.getNextPage(); // 用于下一页请求
        }

        @Override
        public void onFailure(int code, String message) {
            // 获取失败
            Log.e("Leaderboard", "获取排行榜数据失败: code=" + code + ", message=" + message);
        }
    }
);

import com.taptap.sdk.leaderboard.androidx.TapTapLeaderboard
import com.taptap.sdk.leaderboard.data.request.LeaderboardCollection
import com.taptap.sdk.leaderboard.callback.TapTapLeaderboardResponseCallback
import com.taptap.sdk.leaderboard.data.response.LeaderboardScoresResponse

TapTapLeaderboard.loadLeaderboardScores(
    leaderboardId = "your_leaderboard_id", // 排行榜ID
    leaderboardCollection = LeaderboardCollection.PUBLIC, // 总榜
    nextPage = null, // 首次请求传null
    callback = object : TapTapLeaderboardResponseCallback<LeaderboardScoresResponse> {
        override fun onSuccess(data: LeaderboardScoresResponse) {
            // 获取成功
            val scores = data.scores
            val nextPage = data.nextPage // 用于下一页请求
        }

        override fun onFailure(code: Int, message: String) {
            // 获取失败
            Log.e("Leaderboard", "获取排行榜数据失败: code=$code, message=$message")
        }
    }
)

获取当前用户分数

获取当前登录用户在指定排行榜的分数和排名。

Android Java
Android Kotlin

import com.taptap.sdk.leaderboard.androidx.TapTapLeaderboard;
import com.taptap.sdk.leaderboard.data.request.LeaderboardCollection;
import com.taptap.sdk.leaderboard.callback.TapTapLeaderboardResponseCallback;
import com.taptap.sdk.leaderboard.data.response.UserScoreResponse;

TapTapLeaderboard.loadCurrentPlayerLeaderboardScore(
    "your_leaderboard_id", // 排行榜ID
    LeaderboardCollection.PUBLIC, // 总榜
    null, // periodToken - 时间周期标识
    new TapTapLeaderboardResponseCallback<UserScoreResponse>() {
        @Override
        public void onSuccess(UserScoreResponse data) {
            // 获取成功
            Score score = data.getCurrentUserScore();
            Log.d("Leaderboard", "用户分数: " + score);
        }

        @Override
        public void onFailure(int code, String message) {
            // 获取失败
            Log.e("Leaderboard", "获取用户分数失败: code=" + code + ", message=" + message);
        }
    }
);

import com.taptap.sdk.leaderboard.androidx.TapTapLeaderboard
import com.taptap.sdk.leaderboard.data.request.LeaderboardCollection
import com.taptap.sdk.leaderboard.callback.TapTapLeaderboardResponseCallback
import com.taptap.sdk.leaderboard.data.response.UserScoreResponse

TapTapLeaderboard.loadCurrentPlayerLeaderboardScore(
    leaderboardId = "your_leaderboard_id", // 排行榜ID
    leaderboardCollection = LeaderboardCollection.PUBLIC, // 总榜
    periodToken = null, // 时间周期标识
    callback = object : TapTapLeaderboardResponseCallback<UserScoreResponse> {
        override fun onSuccess(data: UserScoreResponse) {
            // 获取成功
            val score = data.currentUserScore
            Log.d("Leaderboard", "用户分数: $score")
        }

        override fun onFailure(code: Int, message: String) {
            // 获取失败
            Log.e("Leaderboard", "获取用户分数失败: code=$code, message=$message")
        }
    }
)

获取用户相近分数

查询当前用户相近的其他用户成绩（上下X位）。

Android Java
Android Kotlin

import com.taptap.sdk.leaderboard.androidx.TapTapLeaderboard;
import com.taptap.sdk.leaderboard.data.request.LeaderboardCollection;
import com.taptap.sdk.leaderboard.callback.TapTapLeaderboardResponseCallback;
import com.taptap.sdk.leaderboard.data.response.LeaderboardScoresResponse;

TapTapLeaderboard.loadPlayerCenteredScores(
    "your_leaderboard_id", // 排行榜ID
    LeaderboardCollection.FRIENDS, // 好友榜
    "weekly", // periodToken - 时间周期标识
    10, // maxCount - 最大返回数量
    new TapTapLeaderboardResponseCallback<LeaderboardScoresResponse>() {
        @Override
        public void onSuccess(LeaderboardScoresResponse data) {
            // 获取成功
            List<Score> scores = data.getScores();
            Log.d("Leaderboard", "相近用户数量: " + scores.size());
        }

        @Override
        public void onFailure(int code, String message) {
            // 获取失败
            Log.e("Leaderboard", "获取相近分数失败: code=" + code + ", message=" + message);
        }
    }
);

import com.taptap.sdk.leaderboard.androidx.TapTapLeaderboard
import com.taptap.sdk.leaderboard.data.request.LeaderboardCollection
import com.taptap.sdk.leaderboard.callback.TapTapLeaderboardResponseCallback
import com.taptap.sdk.leaderboard.data.response.LeaderboardScoresResponse

TapTapLeaderboard.loadPlayerCenteredScores(
    leaderBoardId = "your_leaderboard_id", // 排行榜ID
    leaderboardCollection = LeaderboardCollection.FRIENDS, // 好友榜
    periodToken = "weekly", // 时间周期标识
    maxCount = 10, // 最大返回数量
    callback = object : TapTapLeaderboardResponseCallback<LeaderboardScoresResponse> {
        override fun onSuccess(data: LeaderboardScoresResponse) {
            // 获取成功
            val scores = data.scores
            Log.d("Leaderboard", "相近用户数量: ${scores?.size}")
        }

        override fun onFailure(code: Int, message: String) {
            // 获取失败
            Log.e("Leaderboard", "获取相近分数失败: code=$code, message=$message")
        }
    }
)

错误处理

排行榜 SDK 的所有异步操作都通过 TapTapLeaderboardResponseCallback 返回结果，开发者需要在 onFailure 方法中处理错误情况。

错误码说明

错误码	错误类型	描述
500000	排行榜周期已过期	提示用户排行榜周期已结束，引导查看其他周期
500001	排行榜 ID 未找到	检查排行榜ID是否正确，提示用户排行榜不存在
500002	排行榜参数错误	leaderboard_id 与 client_id 不匹配
500101	当前用户未授权获取此产品（服务）	提示用户权限不足，联系管理员
500102	用户未登录	引导用户登录
500199	未知错误	通用错误处理，建议重试或联系技术支持

错误处理示例

Android Java
Android Kotlin

new TapTapLeaderboardResponseCallback<LeaderboardScoresResponse>() {
    @Override
    public void onSuccess(LeaderboardScoresResponse data) {
        // 处理成功结果
    }

    @Override
    public void onFailure(int code, String message) {
        // 根据错误码处理不同的错误情况
        switch (code) {
            case 500000:
                // 排行榜周期已过期
                // showMessage("排行榜周期已结束，请查看其他周期排行榜");
                break;
            case 500001:
                // 排行榜 ID 未找到
                // showMessage("排行榜不存在，请检查排行榜ID");
                break;
            case 500002:
                // 排行榜参数错误
                // showMessage("参数错误，请检查输入参数");
                break;
            case 500101:
                // 用户未授权
                // showMessage("权限不足，请联系管理员");
                break;
            case 500102:
                // 用户未登录
                // showMessage("请先登录");
                // redirectToLogin();
                break;
            case 500199:
                // 未知错误
                // showMessage("未知错误，请稍后重试");
                break;
            default:
                // 其他错误
                // showMessage("操作失败: " + message);
                break;
        }
    }
}

object : TapTapLeaderboardResponseCallback<LeaderboardScoresResponse> {
    override fun onSuccess(data: LeaderboardScoresResponse) {
        // 处理成功结果
    }

    override fun onFailure(code: Int, message: String) {
        // 根据错误码处理不同的错误情况
        when (code) {
            500000 -> {
                // 排行榜周期已过期
                // showMessage("排行榜周期已结束，请查看其他周期排行榜")
            }
            500001 -> {
                // 排行榜 ID 未找到
                // showMessage("排行榜不存在，请检查排行榜ID")
            }
            500002 -> {
                // 排行榜参数错误
                // showMessage("参数错误，请检查输入参数")
            }
            500101 -> {
                // 用户未授权
                // showMessage("权限不足，请联系管理员")
            }
            500102 -> {
                // 用户未登录
                // showMessage("请先登录")
                // redirectToLogin()
            }
            500199 -> {
                // 未知错误
                // showMessage("未知错误，请稍后重试")
            }
            else -> {
                // 其他错误
                // showMessage("操作失败: $message")
            }
        }
    }
}

集成前准备​

权限说明​

SDK 获取​

注册排行榜事件回调​

设置分享功能​

配置 FileProvider​

设置分享回调​

配置 FileProvider​

设置分享回调​

打开排行榜页面​

打开用户个人资料​

提交分数​

获取排行榜数据​

获取当前用户分数​

获取用户相近分数​

错误处理​

错误码说明​

错误处理示例​

集成前准备

权限说明

SDK 获取

注册排行榜事件回调

设置分享功能

配置 FileProvider

设置分享回调

配置 FileProvider

设置分享回调

打开排行榜页面

打开用户个人资料

提交分数

获取排行榜数据

获取当前用户分数

获取用户相近分数

错误处理

错误码说明

错误处理示例