Skip to main content
Version: v4

TapTap排行榜开发指南

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

集成前准备​

  1. 参考 开发者中心配置 创建应用、配置包名与签名证书
  2. 参考集成指南（Unity、Android、iOS）完成对应平台或引擎的基础接入
  3. 排行榜模块依赖于 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 获取​

远程依赖​

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

"dependencies":{
  "com.taptap.sdk.core":"4.9.3",
  "com.taptap.sdk.login":"4.9.3",
  "com.taptap.sdk.leaderboard":"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.leaderboard":"https://github.com/taptap/tapsdk-unity-dist.git?path=/Leaderboard#4.9.3"
}

本地文件导入​

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

  • TapSDK_Core.unitypackage (TapTapSDK 核心模块，必选)
  • TapSDK_Login.unitypackage（TapTapSDK 登录模块，必选）
  • TapSDK_Leaderboard.unitypackage (TapTapSDK 排行榜模块，必选)

iOS 工程配置​

在 iOS 项目或通过 Unity 项目导出 Xcode 工程时，因排行榜业务需要访问相册保存图片，所以需添加对应权限的使用说明，具体如下：

在 Assets/Plugins/iOS/Resource 目录下创建 TDS-Info.plist 文件 (如果已创建，只需添加内容即可），配置相关权限并替换授权文案：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>NSPhotoLibraryUsageDescription</key>
    <string>需要访问相册以保存图片</string>
</dict>
</plist>

注册排行榜事件回调​

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

using TapSDK.Leaderboard

LeaderboardCallback callback = new LeaderboardCallback();
TapTapLeaderboard.RegisterLeaderboardCallback(callback);
TapTapLeaderboard.UnregisterLeaderboardCallback(callback);

class LeaderboardCallback : ITapTapLeaderboardCallback
{

    public LeaderboardCallback(){}

    public void OnLeaderboardResult(int code, string message)
    {
        // 处理排行榜 SDK 的状态码
        // 500102：需要登录
    }

}

设置分享功能​

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

using TapSDK.Leaderboard;
using UnityEngine;

// 设置分享回调（同步方法，建议在初始化时调用）
public void SetupLeaderboardSharing()
{
    var shareCallback = new TapTapLeaderboardShareCallback
    {
        OnShareSuccessAction = (localPath) =>
        {
            // 处理排行榜分享图片保存成功
            // localPath 为本地图片路径，可用于分享到系统
            Debug.Log($"Share image saved to: {localPath}");
            
            // 可以在这里调用系统分享功能
            ShareImageToSystem(localPath);
        },
        OnShareFailedAction = (error) =>
        {
            // 处理分享失败（可选实现）
            // 开发者可以根据需要选择是否实现此方法
            Debug.LogError($"Share failed: {error?.Message}");
        }
    };

    TapTapLeaderboard.SetShareCallback(shareCallback);
    Debug.Log("Leaderboard share callback has been set");
}

// 分享图片到系统的示例方法
private void ShareImageToSystem(string imagePath)
{
    // 这里可以实现具体的系统分享逻辑
    // 例如使用Native Share插件或Unity的分享功能
    Debug.Log($"Sharing image: {imagePath}");
}

打开排行榜页面​

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

using TapSDK.Leaderboard;

// 打开排行榜页面（同步方法，无需async）
public void OpenLeaderboardPanel()
{
    string leaderboardId = "your_leaderboard_id";

    // 打开总榜
    TapTapLeaderboard.OpenLeaderboard(leaderboardId, "public");

    // 打开好友榜
    TapTapLeaderboard.OpenLeaderboard(leaderboardId, "friends");
}

// 根据条件动态打开不同类型的排行榜
public void OpenLeaderboardByType(bool isFriendsBoard)
{
    string leaderboardId = "your_leaderboard_id";
    string collection = isFriendsBoard ? "friends" : "public";
    
    TapTapLeaderboard.OpenLeaderboard(leaderboardId, collection);
}

打开用户个人资料​

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

using TapSDK.Leaderboard;

// 打开用户个人资料（使用OpenID）
string openId = "user_open_id"; // 用户的OpenID
TapTapLeaderboard.ShowTapUserProfile(openId, null);

// 或者使用UnionID
string unionId = "user_union_id"; // 用户的UnionID
TapTapLeaderboard.ShowTapUserProfile(string.Empty, unionId);

提交分数​

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

using System.Collections.Generic;
using TapSDK.Leaderboard;
using UnityEngine;

// 提交分数（异步方法，需要在async方法中调用）
public async void SubmitPlayerScores()
{
    // 单个分数提交
    var singleScore = new List<SubmitScoresRequest.ScoreItem>
    {
        new SubmitScoresRequest.ScoreItem
        {
            LeaderboardId = "your_leaderboard_id",
            Score = 1000
        }
    };

    // 提交分数（使用异步方式）
    try
    {
        var result = await TapTapLeaderboard.SubmitScores(singleScore);
        // 提交成功
        Debug.Log($"Submit scores success: {result}");
    }
    catch (TapException e)
    {
        // 提交失败
        Debug.LogError($"Submit scores failed, code: {e.code}, message: {e.message}");
    }
}

// 或者在需要时批量提交多个分数
public async void SubmitMultipleScores()
{
    var multipleScores = new List<SubmitScoresRequest.ScoreItem>
    {
        new SubmitScoresRequest.ScoreItem
        {
            LeaderboardId = "leaderboard_1",
            Score = 1000
        },
        new SubmitScoresRequest.ScoreItem
        {
            LeaderboardId = "leaderboard_2", 
            Score = 2000
        }
    };

    try
    {
        var result = await TapTapLeaderboard.SubmitScores(multipleScores);
        Debug.Log($"Submit multiple scores success: {result}");
    }
    catch (TapException e)
    {
        Debug.LogError($"Submit multiple scores failed, code: {e.code}, message: {e.message}");
    }
}

获取排行榜数据​

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

using TapSDK.Leaderboard;
using UnityEngine;

// 获取排行榜数据（异步方法，需要在async方法中调用）
public async void LoadLeaderboardData()
{
    string leaderboardId = "your_leaderboard_id";
    string leaderboardCollection = "public"; // 总榜："public"，好友榜："friends"
    string nextPageToken = null; // 首次请求传null，加载更多时传上次请求返回的nextPage
    string periodToken = null; // 时间周期标识，传null使用当前周期

    try
    {
        var scores = await TapTapLeaderboard.LoadLeaderboardScores(
            leaderboardId,
            leaderboardCollection,
            nextPageToken,
            periodToken);
        
        // 获取成功
        if (scores != null)
        {
            // 保存分页标识用于加载更多数据
            nextPageToken = scores.nextPage;
            
            // 处理分数数据
            if (scores.scores != null && scores.scores.Count > 0)
            {
                Debug.Log($"Loaded {scores.scores.Count} scores");
                
                // 遍历排行榜数据
                for (int i = 0; i < scores.scores.Count; i++)
                {
                    var score = scores.scores[i];
                    Debug.Log($"Rank {score.rank}: {score.user?.name} - Score: {score.score}");
                }
            }
            else
            {
                Debug.Log("No scores found for this leaderboard");
            }
        }
    }
    catch (TapException e)
    {
        // 获取失败，根据错误码进行处理
        Debug.LogError($"Load leaderboard scores failed, code: {e.code}, message: {e.message}");
        
        // 可以根据错误码进行特殊处理
        if (e.code == 500102)
        {
            // 用户未登录，引导登录
            Debug.LogWarning("User not logged in, please login first");
        }
    }
}

获取当前用户分数​

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

using TapSDK.Leaderboard;
using UnityEngine;

// 获取当前用户分数（异步方法，需要在async方法中调用）
public async void LoadCurrentPlayerScore()
{
    string leaderboardId = "your_leaderboard_id";
    string leaderboardCollection = "public"; // 总榜，使用"friends"获取好友榜
    string periodToken = null; // 时间周期标识，默认为当前周期

    try
    {
        var result = await TapTapLeaderboard.LoadCurrentPlayerLeaderboardScore(
            leaderboardId,
            leaderboardCollection,
            periodToken);
        
        // 获取成功
        if (result.currentUserScore != null)
        {
            var userScore = result.currentUserScore;
            Debug.Log($"Current player score: {userScore.score}, rank: {userScore.rank}");
            // 处理用户分数和排名
        }
        else
        {
            Debug.Log("User has no score on this leaderboard");
        }
    }
    catch (TapException e)
    {
        // 获取失败
        Debug.LogError($"Load current player score failed, code: {e.code}, message: {e.message}");
    }
}

获取用户相近分数​

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

using TapSDK.Leaderboard;
using UnityEngine;

// 获取用户相近分数（异步方法，需要在async方法中调用）
public async void LoadPlayerCenteredScores()
{
    string leaderboardId = "your_leaderboard_id";
    string leaderboardCollection = "friends"; // 好友榜
    string periodToken = "weekly"; // 时间周期标识
    int maxCount = 10; // 最大返回数量

    try
    {
        var result = await TapTapLeaderboard.LoadPlayerCenteredScores(
            leaderboardId,
            leaderboardCollection,
            periodToken,
            maxCount);
        
        // 获取成功
        if (result.scores != null)
        {
            Debug.Log($"Loaded {result.scores.Count} player centered scores");
            // 处理相近用户分数数据
            foreach (var score in result.scores)
            {
                Debug.Log($"Player: {score.user.name}, Score: {score.score}, Rank: {score.rank}");
            }
        }
    }
    catch (TapException e)
    {
        // 获取失败
        Debug.LogError($"Load player centered scores failed, code: {e.code}, message: {e.message}");
    }
}

错误处理​

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

错误码说明​

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

错误处理示例​

using TapSDK.Leaderboard;
using UnityEngine;

// 示例：获取排行榜数据并处理错误（异步方法，需要在async方法中调用）
public async void LoadLeaderboardWithErrorHandling()
{
    try
    {
        var data = await TapTapLeaderboard.LoadLeaderboardScores(
            "your_leaderboard_id",
            "public",
            null,
            null);
        
        // 处理成功结果
        Debug.Log($"Successfully loaded {data.scores?.Count ?? 0} scores");
    }
    catch (TapException e)
    {
        // 根据错误码处理不同的错误情况
        switch (e.code)
        {
            case 500000:
                // 排行榜周期已过期
                Debug.LogWarning("排行榜周期已结束，请查看其他周期排行榜");
                break;
            case 500001:
                // 排行榜 ID 未找到
                Debug.LogError("排行榜不存在，请检查排行榜ID");
                break;
            case 500002:
                // 排行榜参数错误
                Debug.LogError("参数错误，请检查输入参数");
                break;
            case 500101:
                // 用户未授权
                Debug.LogError("权限不足，请联系管理员");
                break;
            case 500102:
                // 用户未登录
                Debug.LogWarning("用户未登录，需要引导用户登录");
                // ShowLoginDialog();
                break;
            case 500199:
                // 未知错误
                Debug.LogError("未知错误，请稍后重试");
                break;
            default:
                // 其他错误
                Debug.LogError($"操作失败: {e.message}");
                break;
        }
    }
}

最佳实践​

1. 内存管理​

记得在适当的时机取消注册回调，避免内存泄漏：

using TapSDK.Leaderboard;
using UnityEngine;

public class YourGameManager : MonoBehaviour, ITapTapLeaderboardCallback
{
    private void Start()
    {
        // 注册回调
        TapTapLeaderboard.RegisterLeaderboardCallback(this);
    }
    
    private void OnDestroy()
    {
        // 取消注册回调避免内存泄漏
        TapTapLeaderboard.UnregisterLeaderboardCallback(this);
    }

    public void OnLeaderboardResult(int code, string message)
    {
        // 处理排行榜 SDK 的状态码
        // 500102：需要登录
    }
}

2. 用户登录检测​

在使用排行榜功能前，建议先检查用户登录状态：

using TapSDK.Leaderboard;
using UnityEngine;

public class YourGameManager : MonoBehaviour, ITapTapLeaderboardCallback
{
    private void Start()
    {
        // 注册排行榜回调
        TapTapLeaderboard.RegisterLeaderboardCallback(this);
    }

    public void OnLeaderboardResult(int code, string message)
    {
        switch (code)
        {
            case 500102:
                // 引导用户登录
                ShowLoginDialog();
                break;
        }
    }
    
    private void ShowLoginDialog()
    {
        // 引导用户进行登录
    }
}

3. 完整使用示例​

以下是一个完整的排行榜管理器示例，展示了如何在Unity中正确使用排行榜功能：

using System.Collections.Generic;
using TapSDK.Leaderboard;
using UnityEngine;

public class LeaderboardManager : MonoBehaviour, ITapTapLeaderboardCallback
{
    [Header("排行榜配置")]
    public string leaderboardId = "your_leaderboard_id";
    
    private string nextPageToken = null;
    private bool isInitialized = false;

    private void Start()
    {
        InitializeLeaderboard();
    }

    private void OnDestroy()
    {
        // 清理资源
        if (isInitialized)
        {
            TapTapLeaderboard.UnregisterLeaderboardCallback(this);
        }
    }

    /// <summary>
    /// 初始化排行榜
    /// </summary>
    public void InitializeLeaderboard()
    {
        // 注册回调
        TapTapLeaderboard.RegisterLeaderboardCallback(this);
        
        // 设置分享回调
        var shareCallback = new TapTapLeaderboardShareCallback
        {
            OnShareSuccessAction = (localPath) =>
            {
                Debug.Log($"Share success: {localPath}");
            },
            OnShareFailedAction = (error) =>
            {
                Debug.LogError($"Share failed: {error?.Message}");
            }
        };
        TapTapLeaderboard.SetShareCallback(shareCallback);
        
        isInitialized = true;
        Debug.Log("Leaderboard initialized successfully");
    }

    /// <summary>
    /// 提交玩家分数
    /// </summary>
    public async void SubmitScore(long score)
    {
        if (string.IsNullOrEmpty(leaderboardId))
        {
            Debug.LogError("Leaderboard ID is not set");
            return;
        }

        var scoreItems = new List<SubmitScoresRequest.ScoreItem>
        {
            new SubmitScoresRequest.ScoreItem
            {
                LeaderboardId = leaderboardId,
                Score = score
            }
        };

        try
        {
            var result = await TapTapLeaderboard.SubmitScores(scoreItems);
            Debug.Log($"Score submitted successfully: {score}");
        }
        catch (TapException e)
        {
            Debug.LogError($"Submit score failed: {e.code} - {e.message}");
            HandleLeaderboardError(e.code);
        }
    }

    /// <summary>
    /// 打开排行榜界面
    /// </summary>
    public void OpenLeaderboard(bool friendsOnly = false)
    {
        string collection = friendsOnly ? "friends" : "public";
        TapTapLeaderboard.OpenLeaderboard(leaderboardId, collection);
    }

    /// <summary>
    /// 加载排行榜数据
    /// </summary>
    public async void LoadLeaderboardScores(bool friendsOnly = false, bool loadMore = false)
    {
        string collection = friendsOnly ? "friends" : "public";
        string pageToken = loadMore ? nextPageToken : null;

        try
        {
            var scores = await TapTapLeaderboard.LoadLeaderboardScores(
                leaderboardId, collection, pageToken, null);

            if (scores?.scores != null && scores.scores.Count > 0)
            {
                nextPageToken = scores.nextPage;
                Debug.Log($"Loaded {scores.scores.Count} scores");
                
                // 处理数据
                ProcessLeaderboardScores(scores.scores);
            }
            else
            {
                Debug.Log("No scores available");
            }
        }
        catch (TapException e)
        {
            Debug.LogError($"Load leaderboard failed: {e.code} - {e.message}");
            HandleLeaderboardError(e.code);
        }
    }

    /// <summary>
    /// 处理排行榜数据
    /// </summary>
    private void ProcessLeaderboardScores(List<Score> scores)
    {
        foreach (var score in scores)
        {
            Debug.Log($"Rank: {score.rank}, Player: {score.user?.name}, Score: {score.score}");
        }
    }

    /// <summary>
    /// 处理错误码
    /// </summary>
    private void HandleLeaderboardError(int errorCode)
    {
        switch (errorCode)
        {
            case 500102:
                Debug.LogWarning("User not logged in");
                // 这里可以触发登录流程
                break;
            case 500001:
                Debug.LogError("Leaderboard not found");
                break;
            default:
                Debug.LogError($"Leaderboard error: {errorCode}");
                break;
        }
    }

    /// <summary>
    /// 排行榜回调处理
    /// </summary>
    public void OnLeaderboardResult(int code, string message)
    {
        Debug.Log($"Leaderboard callback: {code} - {message}");
        HandleLeaderboardError(code);
    }
}