Athana SDK

For Games

游戏中心服务

配置游戏中心

Google Play Games

Google Play Console 配置

Apple Game Center

XCode 配置

查阅 XCode配置GameKit 中的以下两个章节

排行榜

提交分数

根据排行榜设置的榜单数值类型，填写的数值也有不同的规则：

  • 整数：设置为整数，输入 1000，最终显示也为 1000
  • 小数：设置为2位小数，12.55 则需要输入 1255
  • 时间：单位：毫秒，12000 表示 12 秒
  • 货币：对实际货币值 x 1000000，实际 $12.25，则需要传入 12250000
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Example
private fun submitScore(
    leaderboardId: String,
    score: Long,
    extra: String? = null // 额外信息，Google Play Games 对应 scoreTag 参数，长度限制64位
) {
    Athana.getInstance().gamingService.submitScore(
        leaderboardId = leaderboardId,
        score = score,
        extra = extra,
        listener = object : GamingRequestListener<Boolean> {
            override fun onResponse(result: Boolean) {
                // 提交成功
            }

            override fun onError(error: Throwable?) {
                // 提交异常
            }
        }
    )
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// Example
private void submitScore(
    String leaderboardId,
    long score,
    @Nullable String extra
) {
    Athana.getInstance().getGamingService().submitScore(
        leaderboardId,
        score,
        extra,
        new GamingRequestListener<Boolean>() {
            @Override
            public void onResponse(Boolean result) {
                // 提交成功
            }

            @Override
            public void onError(@Nullable Throwable error) {
                // 提交异常
            }
        }
    );
}

查询分数

获取当前玩家在指定排行榜中的得分。

LeaderboardPlayerScope 枚举值：

  • ALL - 所有玩家
  • FRIENDS - 好友排行榜（需要先获取好友列表权限）

LeaderboardTimeSpan 枚举值：

  • TODAY - 日榜
  • WEEK - 周榜
  • ALL_TIME - 总榜
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Example
private fun getScore(
    leaderboardId: String,
    scope: LeaderboardPlayerScope,
    timeScope: LeaderboardTimeSpan
) {
    Athana.getInstance().gamingService.getScore(
        leaderboardId = leaderboardId,
        scope = scope,
        timeScope = timeScope,
        listener = object : GamingRequestListener<ScoreData?> {
            override fun onResponse(result: ScoreData?) {
                // 查询成功
            }

            override fun onError(error: Throwable?) {
                // 查询异常
            }
        }
    )
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// Example
private void getScore(
    String leaderboardId,
    LeaderboardPlayerScope scope,
    LeaderboardTimeSpan timeScope
) {
    Athana.getInstance().getGamingService().getScore(
        leaderboardId,
        scope,
        timeScope,
        new GamingRequestListener<ScoreData>() {
            @Override
            public void onResponse(@Nullable ScoreData result) {
                // 查询成功
            }

            @Override
            public void onError(@Nullable Throwable error) {
                // 查询异常
            }
        }
    );
}

跳转至排行榜界面

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
// Example - 打开指定排行榜
private fun openLeaderboardUI(
    leaderboardId: String,
    scope: LeaderboardPlayerScope?,
    timeScope: LeaderboardTimeSpan?
) {
    Athana.getInstance().gamingService.openLeaderboardUI(
        leaderboardId = leaderboardId,
        scope = scope,
        timeScope = timeScope,
        listener = object : GamingRequestListener<Boolean> {
            override fun onResponse(result: Boolean) {
                // 打开成功
            }

            override fun onError(error: Throwable?) {
                // 打开异常
            }
        }
    )
}

// Example - 打开排行榜总入口
private fun openLeaderboardUI() {
    Athana.getInstance().gamingService.openLeaderboardUI(
        listener = object : GamingRequestListener<Boolean> {
            override fun onResponse(result: Boolean) {
                // 打开成功
            }

            override fun onError(error: Throwable?) {
                // 打开异常
            }
        }
    )
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
// Example - 打开指定排行榜
private void openLeaderboardUI(
    String leaderboardId,
    @Nullable LeaderboardPlayerScope scope,
    @Nullable LeaderboardTimeSpan timeScope
) {
    Athana.getInstance().getGamingService().openLeaderboardUI(
        leaderboardId,
        scope,
        timeScope,
        new GamingRequestListener<Boolean>() {
            @Override
            public void onResponse(Boolean result) {
                // 打开成功
            }

            @Override
            public void onError(@Nullable Throwable error) {
                // 打开异常
            }
        }
    );
}

// Example - 打开排行榜总入口
private void openLeaderboardUI() {
    Athana.getInstance().getGamingService().openLeaderboardUI(
        null,
        null,
        null,
        new GamingRequestListener<Boolean>() {
            @Override
            public void onResponse(Boolean result) {
                // 打开成功
            }

            @Override
            public void onError(@Nullable Throwable error) {
                // 打开异常
            }
        }
    );
}

获取排行榜信息

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
// Example - 获取所有排行榜
private fun getAllLeaderboardInfo() {
    Athana.getInstance().gamingService.getLeaderboardInfo(
        leaderboardId = null,
        forceReload = false,
        listener = object : GamingRequestListener<List<LeaderboardInfo>> {
            override fun onResponse(result: List<LeaderboardInfo>) {
                // 查询成功
            }

            override fun onError(error: Throwable?) {
                // 查询异常
            }
        }
    )
}

// Example - 获取指定排行榜
private fun getLeaderboardInfo(leaderboardId: String) {
    Athana.getInstance().gamingService.getLeaderboardInfo(
        leaderboardId = leaderboardId,
        forceReload = false,
        listener = object : GamingRequestListener<List<LeaderboardInfo>> {
            override fun onResponse(result: List<LeaderboardInfo>) {
                // 查询成功
            }

            override fun onError(error: Throwable?) {
                // 查询异常
            }
        }
    )
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// Example - 获取所有排行榜
private void getAllLeaderboardInfo() {
    Athana.getInstance().getGamingService().getLeaderboardInfo(
        null,
        false,
        new GamingRequestListener<List<LeaderboardInfo>>() {
            @Override
            public void onResponse(List<LeaderboardInfo> result) {
                // 查询成功
            }

            @Override
            public void onError(@Nullable Throwable error) {
                // 查询异常
            }
        }
    );
}

// Example - 获取指定排行榜
private void getLeaderboardInfo(String leaderboardId) {
    Athana.getInstance().getGamingService().getLeaderboardInfo(
        leaderboardId,
        false,
        new GamingRequestListener<List<LeaderboardInfo>>() {
            @Override
            public void onResponse(List<LeaderboardInfo> result) {
                // 查询成功
            }

            @Override
            public void onError(@Nullable Throwable error) {
                // 查询异常
            }
        }
    );
}

LeaderboardInfo 参数说明：

参数名 类型 说明
leaderboardId String 排行榜 ID
name String 排行榜名称
imageUrl String? 排行榜图标 URL

获取排行榜分数数据

分页加载

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
// Example
private fun loadLeaderboardData(
    leaderboardId: String,
    scope: LeaderboardPlayerScope,
    timeScope: LeaderboardTimeSpan,
    pageSize: Int,
    userCenter: Boolean = false // 是否以当前玩家为中心获取
) {
    Athana.getInstance().gamingService.loadLeaderboardData(
        leaderboardId = leaderboardId,
        scope = scope,
        timeScope = timeScope,
        pageSize = pageSize,
        userCenter = userCenter,
        listener = object : GamingRequestListener<ScoreList> {
            override fun onResponse(result: ScoreList) {
                // 查询成功
                // result.scoreList - 分数列表
                // result.hasMore - 是否还有更多数据
            }

            override fun onError(error: Throwable?) {
                // 查询异常
            }
        }
    )
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// Example
private void loadLeaderboardData(
    String leaderboardId,
    LeaderboardPlayerScope scope,
    LeaderboardTimeSpan timeScope,
    int pageSize,
    boolean userCenter
) {
    Athana.getInstance().getGamingService().loadLeaderboardData(
        leaderboardId,
        scope,
        timeScope,
        pageSize,
        userCenter,
        new GamingRequestListener<ScoreList>() {
            @Override
            public void onResponse(ScoreList result) {
                // 查询成功
                // result.getScoreList() - 分数列表
                // result.getHasMore() - 是否还有更多数据
            }

            @Override
            public void onError(@Nullable Throwable error) {
                // 查询异常
            }
        }
    );
}

ScoreData 参数说明：

参数名 类型 说明
rank Long 名次
score Long 原始数值
displayScore String 格式化的分数
player PlayerProfile 玩家信息
extraInfo ScoreExtraInfo 额外信息

加载更多

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Example
private fun loadMoreLeaderboardData(
    leaderboardId: String,
    pageSize: Int,
    pageDirection: PageDirection // NEXT - 下一页, PREV - 上一页
) {
    Athana.getInstance().gamingService.loadMoreLeaderboardData(
        leaderboardId = leaderboardId,
        pageSize = pageSize,
        pageDirection = pageDirection,
        listener = object : GamingRequestListener<ScoreList> {
            override fun onResponse(result: ScoreList) {
                // 查询成功
            }

            override fun onError(error: Throwable?) {
                // 查询异常
            }
        }
    )
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// Example
private void loadMoreLeaderboardData(
    String leaderboardId,
    int pageSize,
    PageDirection pageDirection
) {
    Athana.getInstance().getGamingService().loadMoreLeaderboardData(
        leaderboardId,
        pageSize,
        pageDirection,
        new GamingRequestListener<ScoreList>() {
            @Override
            public void onResponse(ScoreList result) {
                // 查询成功
            }

            @Override
            public void onError(@Nullable Throwable error) {
                // 查询异常
            }
        }
    );
}

释放引用

在不需要使用排行榜数据时调用，释放资源。

1
2
3
4
// Example
private fun releaseLeaderboardData() {
    Athana.getInstance().gamingService.leaderboardDataRelease()
}
1
2
3
4
// Example
private void releaseLeaderboardData() {
    Athana.getInstance().getGamingService().leaderboardDataRelease();
}

成就

解锁成就

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Example
private fun unlockAchievement(achievementId: String) {
    Athana.getInstance().gamingService.unlockAchievement(
        achievementId = achievementId,
        listener = object : GamingRequestListener<Boolean> {
            override fun onResponse(result: Boolean) {
                // 解锁成功
            }

            override fun onError(error: Throwable?) {
                // 解锁异常
            }
        }
    )
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Example
private void unlockAchievement(String achievementId) {
    Athana.getInstance().getGamingService().unlockAchievement(
        achievementId,
        new GamingRequestListener<Boolean>() {
            @Override
            public void onResponse(Boolean result) {
                // 解锁成功
            }

            @Override
            public void onError(@Nullable Throwable error) {
                // 解锁异常
            }
        }
    );
}

更新分步成就

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// Example
private fun updateAchievementProgress(
    achievementId: String,
    progress: Int // 进度值
) {
    Athana.getInstance().gamingService.updateAchievementProgress(
        achievementId = achievementId,
        progress = progress,
        listener = object : GamingRequestListener<Boolean> {
            override fun onResponse(result: Boolean) {
                // 更新成功
            }

            override fun onError(error: Throwable?) {
                // 更新异常
            }
        }
    )
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Example
private void updateAchievementProgress(
    String achievementId,
    int progress
) {
    Athana.getInstance().getGamingService().updateAchievementProgress(
        achievementId,
        progress,
        new GamingRequestListener<Boolean>() {
            @Override
            public void onResponse(Boolean result) {
                // 更新成功
            }

            @Override
            public void onError(@Nullable Throwable error) {
                // 更新异常
            }
        }
    );
}

跳转至成就界面

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Example
private fun openAchievementUI() {
    Athana.getInstance().gamingService.openAchievementUI(
        listener = object : GamingRequestListener<Boolean> {
            override fun onResponse(result: Boolean) {
                // 打开成功
            }

            override fun onError(error: Throwable?) {
                // 打开异常
            }
        }
    )
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// Example
private void openAchievementUI() {
    Athana.getInstance().getGamingService().openAchievementUI(
        new GamingRequestListener<Boolean>() {
            @Override
            public void onResponse(Boolean result) {
                // 打开成功
            }

            @Override
            public void onError(@Nullable Throwable error) {
                // 打开异常
            }
        }
    );
}

获取成就信息

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Example
private fun getAchievementData(forceReload: Boolean = false) {
    Athana.getInstance().gamingService.getAchievementData(
        forceReload = forceReload,
        listener = object : GamingRequestListener<List<Achievement>> {
            override fun onResponse(result: List<Achievement>) {
                // 查询成功
            }

            override fun onError(error: Throwable?) {
                // 查询异常
            }
        }
    )
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Example
private void getAchievementData(boolean forceReload) {
    Athana.getInstance().getGamingService().getAchievementData(
        forceReload,
        new GamingRequestListener<List<Achievement>>() {
            @Override
            public void onResponse(List<Achievement> result) {
                // 查询成功
            }

            @Override
            public void onError(@Nullable Throwable error) {
                // 查询异常
            }
        }
    );
}

Achievement 参数说明：

参数名 类型 说明
achievementId String 成就 ID
title String 成就名称
description String 成就描述
state AchievementState 成就状态：HIDDEN - 隐藏，REVEALED - 已揭示，UNLOCKED - 已解锁
type AchievementType 成就类型：STANDARD - 标准，INCREMENTAL - 增量
progress Double 当前进度（增量成就）
extraInfo AchievementExtraInfo? 额外信息

好友

请求访问好友列表权限

在获取好友列表或查询好友排行榜之前，需要先申请好友列表访问权限。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Example
private fun requestFriendListPermission() {
    Athana.getInstance().gamingService.requestFriendListPermission(
        listener = object : GamingRequestListener<Boolean> {
            override fun onResponse(result: Boolean) {
                // 授权成功
            }

            override fun onError(error: Throwable?) {
                // 授权失败
            }
        }
    )
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// Example
private void requestFriendListPermission() {
    Athana.getInstance().getGamingService().requestFriendListPermission(
        new GamingRequestListener<Boolean>() {
            @Override
            public void onResponse(Boolean result) {
                // 授权成功
            }

            @Override
            public void onError(@Nullable Throwable error) {
                // 授权失败
            }
        }
    );
}

获取好友列表

加载好友列表

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Example
private fun loadFriends(
    pageSize: Int,
    forceReload: Boolean = false
) {
    Athana.getInstance().gamingService.loadFriends(
        pageSize = pageSize,
        forceReload = forceReload,
        listener = object : GamingRequestListener<FriendList> {
            override fun onResponse(result: FriendList) {
                // 查询成功
                // result.friends - 好友列表
                // result.hasMore - 是否还有更多数据
            }

            override fun onError(error: Throwable?) {
                // 查询异常
            }
        }
    )
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
// Example
private void loadFriends(
    int pageSize,
    boolean forceReload
) {
    Athana.getInstance().getGamingService().loadFriends(
        pageSize,
        forceReload,
        new GamingRequestListener<FriendList>() {
            @Override
            public void onResponse(FriendList result) {
                // 查询成功
                // result.getFriends() - 好友列表
                // result.getHasMore() - 是否还有更多数据
            }

            @Override
            public void onError(@Nullable Throwable error) {
                // 查询异常
            }
        }
    );
}

加载更多好友列表

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Example
private fun loadMoreFriends(pageSize: Int) {
    Athana.getInstance().gamingService.loadMoreFriends(
        pageSize = pageSize,
        listener = object : GamingRequestListener<FriendList> {
            override fun onResponse(result: FriendList) {
                // 查询成功
            }

            override fun onError(error: Throwable?) {
                // 查询异常
            }
        }
    )
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// Example
private void loadMoreFriends(int pageSize) {
    Athana.getInstance().getGamingService().loadMoreFriends(
        pageSize,
        new GamingRequestListener<FriendList>() {
            @Override
            public void onResponse(FriendList result) {
                // 查询成功
            }

            @Override
            public void onError(@Nullable Throwable error) {
                // 查询异常
            }
        }
    );
}

FriendList 参数说明：

参数名 类型 说明
friends List 好友列表
hasMore Boolean 是否还有更多数据

跳转至玩家资料界面

1
2
3
4
// Example
private fun openPlayerProfileUI(playerId: String) {
    Athana.getInstance().gamingService.openPlayerProfileUI(playerId)
}
1
2
3
4
// Example
private void openPlayerProfileUI(String playerId) {
    Athana.getInstance().getGamingService().openPlayerProfileUI(playerId);
}

PlayerProfile 参数说明：

参数名 类型 说明
playerId String 玩家 ID，如果返回空字符，表示该玩家不允许访问其信息
playerName String 玩家昵称
avatarUrl String? 玩家头像 URL
0%