跳到主要内容
版本：v4

iOS SDK 开发指南

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

集成前准备​

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

权限说明​

该模块需要如下权限：

权限使用目的权限申请时机
相册权限保存图片到相册用户首次使用该功能时会申请权限

开发者需在工程的 Info.plist 中添加如下权限说明，并替换授权文案：

<key>NSPhotoLibraryUsageDescription</key>
<string>需要访问相册以保存图片</string>

SDK 获取​

远程依赖​

  1. 在工程 Podfile 文件中对应模块下添加依赖：
pod 'TapTapSDK/Leaderboard', '~> 4.11.0'
  1. 执行 Pod install 下载对应依赖文件

本地文件依赖​

排行榜依赖于初始化和 TapTap 登录模块，使用本地文件方式添加依赖时，需先参考集成指南 和 TapTap 登录添加对应本地文件依赖项。

  1. 在下载页下载如下文件：
  • TapTapLeaderboardSDK.xcframework 排行榜模块
  • TapTapProfileSDK.xcframework 用户名片依赖库
  • TapTapKingfisher.xcframework 基础库
  • TapTapProfileResource.bundle 用户名片资源文件
  • TapTapLeaderboardResource.bundle 排行榜资源文件
  1. 在工程中添加 framework 静态库，注意添加时选择 Embed 方式为 Do Not Embed

注册排行榜事件回调​

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

import TapTapLeaderboardSDK

// 定义排行榜回调类
class LeaderboardCallbackHandler: NSObject, TapTapLeaderboardCallback {
    func onLeaderboardResult(code: Int, message: String) {
        // 处理排行榜事件
        switch code {
        case 500102:
            // 用户未登录，需要引导用户登录
            print("用户未登录，需要引导用户登录")
            // showLoginDialog()
        default:
            print("Leaderboard callback: code=\(code), message=\(message)")
        }
    }
}

// 注册排行榜事件回调
let callbackHandler = LeaderboardCallbackHandler()
TapTapLeaderboard.registerLeaderboardCallback(callback: callbackHandler)

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

设置分享功能​

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

import TapTapLeaderboardSDK

// 定义分享回调类
class ShareCallbackHandler: NSObject, TapTapLeaderboardShareCallback {
    func onShareSuccess(localPath: String) {
        // 处理排行榜分享图片保存成功
        // localPath 为本地图片路径，可用于分享到系统
        print("Share success: \(localPath)")
        
        // 可以在这里调用系统分享功能
        shareImageToSystem(imagePath: localPath)
    }
    
    func onShareFailed(error: Error) {
        // 处理分享失败（可选实现）
        // 开发者可以根据需要选择是否实现此方法
        print("Share failed: \(error.localizedDescription)")
    }
    
    // 分享图片到系统的示例方法
    private func shareImageToSystem(imagePath: String) {
        guard let image = UIImage(contentsOfFile: imagePath) else {
            print("Failed to load image from path: \(imagePath)")
            return
        }
        
        DispatchQueue.main.async {
            let activityViewController = UIActivityViewController(
                activityItems: [image],
                applicationActivities: nil
            )
            
            // 获取当前视图控制器并展示分享界面
            if let topController = UIApplication.shared.keyWindow?.rootViewController {
                var presentedController = topController
                while let controller = presentedController.presentedViewController {
                    presentedController = controller
                }
                presentedController.present(activityViewController, animated: true)
            }
        }
    }
}

// 设置分享回调
let shareHandler = ShareCallbackHandler()
TapTapLeaderboard.setShareCallback(callback: shareHandler)

打开排行榜页面​

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

提示

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

import TapTapLeaderboardSDK

// 打开总榜
let leaderboardId = "your_leaderboard_id"
TapTapLeaderboard.openLeaderboard(
    leaderboardId: leaderboardId,
    collection: TapTapLeaderboardCollection.public
)

// 打开好友榜
TapTapLeaderboard.openLeaderboard(
    leaderboardId: "your_leaderboard_id",
    collection: TapTapLeaderboardCollection.friends
)

// 根据条件动态打开不同类型的排行榜
func openLeaderboardByType(leaderboardId: String, isFriendsBoard: Bool) {
    let collection = isFriendsBoard ? TapTapLeaderboardCollection.friends : TapTapLeaderboardCollection.public
    TapTapLeaderboard.openLeaderboard(
        leaderboardId: leaderboardId,
        collection: collection
    )
}

打开用户个人资料​

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

import TapTapLeaderboardSDK

// 使用OpenID打开用户个人资料
let openId = "user_open_id"
TapTapLeaderboard.openUserProfile(openId: openId, unionId: "")

// 使用UnionID打开用户个人资料
let unionId = "user_union_id"
TapTapLeaderboard.openUserProfile(openId: "", unionId: unionId)

提交分数​

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

import TapTapLeaderboardSDK

// 定义响应回调类
class SubmitScoresCallback: NSObject, TapTapLeaderboardResponseCallback {
    func onSuccess(data: Any) {
        // 提交成功，data 为 TapTapSubmitScoresResponse 类型
        if let response = data as? TapTapSubmitScoresResponse {
            print("提交成功: \(response.items.count) 个分数")
            for item in response.items {
                print("排行榜 \(item.leaderboardId): \(item.scoreResult?.rawScore ?? 0)")
            }
        }
    }
    
    func onFailure(code: Int, message: String) {
        // 提交失败
        print("提交失败: code=\(code), message=\(message)")
    }
}

// 提交分数
func submitPlayerScores() {
    // 创建分数项
    let scores = [
        TapTapLeaderboardScoreItem(leaderboardId: "leaderboard_1", score: 1000),
        TapTapLeaderboardScoreItem(leaderboardId: "leaderboard_2", score: 2000)
    ]
    
    // 创建回调
    let callback = SubmitScoresCallback()
    
    // 提交分数（最多5个分数）
    TapTapLeaderboard.submitScores(scores: scores, callback: callback)
}

// 提交单个分数的便捷方法
func submitSingleScore(leaderboardId: String, score: Int64) {
    let scoreItem = TapTapLeaderboardScoreItem(leaderboardId: leaderboardId, score: score)
    let callback = SubmitScoresCallback()
    
    TapTapLeaderboard.submitScores(scores: [scoreItem], callback: callback)
}

获取排行榜数据​

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

import TapTapLeaderboardSDK

// 定义加载排行榜数据回调类
class LoadLeaderboardCallback: NSObject, TapTapLeaderboardResponseCallback {
    func onSuccess(data: Any) {
        // 获取成功，data 为 TapTapLeaderboardDataResponse 类型
        if let response = data as? TapTapLeaderboardDataResponse {
            print("加载成功: \(response.scores?.count ?? 0) 个分数")
            
            // 处理分数数据
            if let scores = response.scores {
                for score in scores {
                    let userName = score.user?.name ?? "Unknown"
                    let userScore = score.score ?? 0
                    let rank = score.rank ?? 0
                    print("排名 \(rank): \(userName) - 分数: \(userScore)")
                }
            }
            
            // 保存下一页标识用于分页加载
            let nextPage = response.nextPage
            if !nextPage.isEmpty {
                print("还有更多数据，nextPage: \(nextPage)")
            }
        }
    }
    
    func onFailure(code: Int, message: String) {
        // 获取失败
        print("获取排行榜数据失败: code=\(code), message=\(message)")
        
        // 根据错误码进行特殊处理
        if code == 500102 {
            print("用户未登录，需要引导用户登录")
        }
    }
}

// 获取排行榜数据
func loadLeaderboardData() {
    let leaderboardId = "your_leaderboard_id"
    let collection = TapTapLeaderboardCollection.public // 总榜
    let nextPage: String? = nil // 首次请求传nil，分页时传上次的nextPage
    let periodToken: String? = nil // 时间周期标识，传nil使用当前周期
    
    let callback = LoadLeaderboardCallback()
    
    TapTapLeaderboard.loadLeaderboardScores(
        leaderboardId: leaderboardId,
        collection: collection,
        nextPage: nextPage,
        periodToken: periodToken,
        callback: callback
    )
}

// 分页加载更多数据
func loadMoreLeaderboardData(nextPage: String) {
    let leaderboardId = "your_leaderboard_id"
    let collection = TapTapLeaderboardCollection.public
    let callback = LoadLeaderboardCallback()
    
    TapTapLeaderboard.loadLeaderboardScores(
        leaderboardId: leaderboardId,
        collection: collection,
        nextPage: nextPage,
        periodToken: nil,
        callback: callback
    )
}

获取当前用户分数​

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

import TapTapLeaderboardSDK

// 定义获取当前用户分数回调类
class LoadCurrentPlayerScoreCallback: NSObject, TapTapLeaderboardResponseCallback {
    func onSuccess(data: Any) {
        // 获取成功，data 为 TapTapUserScoreResponse 类型
        if let response = data as? TapTapUserScoreResponse {
            if let currentUserScore = response.currentUserScore {
                let score = currentUserScore.score ?? 0
                let rank = currentUserScore.rank ?? 0
                let rankDisplay = currentUserScore.rankDisplay ?? ""
                print("当前用户分数: \(score), 排名: \(rank), 排名显示: \(rankDisplay)")
            } else {
                print("用户在此排行榜上暂无分数")
            }
            
            // 获取排行榜信息
            if let leaderboardInfo = response.leaderboard {
                print("排行榜名称: \(leaderboardInfo.name)")
            }
        }
    }
    
    func onFailure(code: Int, message: String) {
        // 获取失败
        print("获取当前用户分数失败: code=\(code), message=\(message)")
    }
}

// 获取当前用户分数
func loadCurrentPlayerScore() {
    let leaderboardId = "your_leaderboard_id"
    let collection = TapTapLeaderboardCollection.public // 总榜
    let periodToken: String? = nil // 时间周期标识，传nil使用当前周期
    
    let callback = LoadCurrentPlayerScoreCallback()
    
    TapTapLeaderboard.loadCurrentPlayerLeaderboardScore(
        leaderboardId: leaderboardId,
        collection: collection,
        periodToken: periodToken,
        callback: callback
    )
}

// 获取好友榜当前用户分数
func loadCurrentPlayerScoreInFriends() {
    let leaderboardId = "your_leaderboard_id"
    let collection = TapTapLeaderboardCollection.friends // 好友榜
    let callback = LoadCurrentPlayerScoreCallback()
    
    TapTapLeaderboard.loadCurrentPlayerLeaderboardScore(
        leaderboardId: leaderboardId,
        collection: collection,
        periodToken: nil,
        callback: callback
    )
}

获取用户相近分数​

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

import TapTapLeaderboardSDK

// 定义获取相近用户分数回调类
class LoadPlayerCenteredScoresCallback: NSObject, TapTapLeaderboardResponseCallback {
    func onSuccess(data: Any) {
        // 获取成功，data 为 TapTapLeaderboardDataResponse 类型
        if let response = data as? TapTapLeaderboardDataResponse {
            if let scores = response.scores {
                print("获取到 \(scores.count) 个相近用户分数")
                
                // 处理相近用户分数数据
                for score in scores {
                    let userName = score.user?.name ?? "Unknown"
                    let userScore = score.score ?? 0
                    let rank = score.rank ?? 0
                    print("排名 \(rank): \(userName) - 分数: \(userScore)")
                }
            } else {
                print("暂无相近用户分数")
            }
        }
    }
    
    func onFailure(code: Int, message: String) {
        // 获取失败
        print("获取相近分数失败: code=\(code), message=\(message)")
    }
}

// 获取用户相近分数
func loadPlayerCenteredScores() {
    let leaderboardId = "your_leaderboard_id"
    let collection = TapTapLeaderboardCollection.friends // 好友榜
    let periodToken = "weekly" // 时间周期标识
    let maxCount = 10 // 最大返回数量
    
    let callback = LoadPlayerCenteredScoresCallback()
    
    TapTapLeaderboard.loadPlayerCenteredScores(
        leaderboardId: leaderboardId,
        collection: collection,
        periodToken: periodToken,
        maxCount: maxCount,
        callback: callback
    )
}

// 获取总榜相近分数（使用默认参数）
func loadPlayerCenteredScoresDefault() {
    let leaderboardId = "your_leaderboard_id"
    let collection = TapTapLeaderboardCollection.public
    let callback = LoadPlayerCenteredScoresCallback()
    
    // 使用默认参数：periodToken = nil, maxCount = nil
    TapTapLeaderboard.loadPlayerCenteredScores(
        leaderboardId: leaderboardId,
        collection: collection,
        periodToken: nil,
        maxCount: nil,
        callback: callback
    )
}

错误处理​

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

错误码说明​

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

错误处理示例​

import TapTapLeaderboardSDK

// 定义通用错误处理回调类
class LeaderboardErrorHandlingCallback: NSObject, TapTapLeaderboardResponseCallback {
    func onSuccess(data: Any) {
        // 处理成功结果
        print("排行榜操作成功")
    }
    
    func onFailure(code: Int, message: String) {
        // 根据错误码处理不同的错误情况
        switch code {
        case 500000:
            // 排行榜周期已过期
            showMessage("排行榜周期已结束，请查看其他周期排行榜")
        case 500001:
            // 排行榜 ID 未找到
            showMessage("排行榜不存在，请检查排行榜ID")
        case 500002:
            // 排行榜参数错误
            showMessage("参数错误，请检查输入参数")
        case 500101:
            // 用户未授权
            showMessage("权限不足，请联系管理员")
        case 500102:
            // 用户未登录
            showMessage("请先登录")
            redirectToLogin()
        case 500199:
            // 未知错误
            showMessage("未知错误，请稍后重试")
        default:
            // 其他错误
            showMessage("操作失败: \(message)")
        }
    }
    
    // 显示错误消息的辅助方法
    private func showMessage(_ message: String) {
        print("错误提示: \(message)")
        
        // 在主线程显示警告框
        DispatchQueue.main.async {
            let alert = UIAlertController(
                title: "提示",
                message: message,
                preferredStyle: .alert
            )
            alert.addAction(UIAlertAction(title: "确定", style: .default))
            
            // 获取当前视图控制器并显示警告框
            if let topController = UIApplication.shared.keyWindow?.rootViewController {
                var presentedController = topController
                while let controller = presentedController.presentedViewController {
                    presentedController = controller
                }
                presentedController.present(alert, animated: true)
            }
        }
    }
    
    // 重定向到登录的辅助方法
    private func redirectToLogin() {
        print("重定向到登录页面")
        // 这里可以实现具体的登录逻辑
        // 例如：调用 TapTap 登录 SDK
        // TapTapLogin.startTapTapLogin(...)
    }
}

// 使用错误处理回调的示例
func loadLeaderboardWithErrorHandling() {
    let leaderboardId = "your_leaderboard_id"
    let collection = TapTapLeaderboardCollection.public
    let callback = LeaderboardErrorHandlingCallback()
    
    TapTapLeaderboard.loadLeaderboardScores(
        leaderboardId: leaderboardId,
        collection: collection,
        nextPage: nil,
        periodToken: nil,
        callback: callback
    )
}

// 错误转换工具方法
func handleLeaderboardError(_ error: Error) -> TapLeaderboardError {
    // 使用 TapTapLeaderboard 提供的错误转换方法
    return TapTapLeaderboard.convertError(error)
}