Skip to main content
Version: v4

最佳实践

本文介绍 TapTap 排行榜的最佳实践。共用说明适用于各技术栈，代码示例可按 Unity、Android、iOS 和 UE5 切换。接入前请先完成对应的开发指南。

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. 完整使用示例​

以下示例展示了如何正确使用排行榜功能：

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