成就与排行榜

排行榜

创建排行榜

本部分将介绍如何为新游戏或现有游戏创建排行榜。最多上限 20 个，每个游戏中榜单 ID 唯一。

如需为游戏创建排行榜，请进入与您的游戏相对应的 GameRank 管理页面中，选择拓展 > Add 点击创建排行榜按钮。

然后，只需填写此排行榜所需的信息。

得分格式

• 数字排行榜以数字形式显示得分。这些得分可以显示为整数或浮点数，例如 3.14159、3141.59 或 314159；需要注意数值不宜过大，目前仅支持单精度。

• 时间排行榜将以小时 / 分钟 / 秒/百分之一秒的格式显示得分，或传统时钟格式（如 HH:MM:SS），例如 66032、 1:06:3。

• 格式化分数将以自定义格式显示得分。货币单位的 $19.95 为单位提交得分。例如，$19.95。

背景图指南

榜单的背景图片，应创建为 1024 x 1024 的 JPEG 文件。可选项，未上传时，使用平台默认图片。 所有语言区域均使用相同的背景图片，因此我们建议您不要在图片中添加任何文本或本地化内容。

调整排行榜

对于榜单的列表，开发者可以对异常玩家进行处理：

• 删除：去除玩家的当前展示的榜单数据。
• 添加至黑名单：后续取消玩家参与当前游戏全部排行榜的资格。 已添加后黑名单后，在全部榜单下可以查看增加的黑名单账号列表，可以操作将玩家账号移出黑名单。
• 编辑数据：点击打开编辑排行榜页面。
• 删除榜单：点击删除指定的排行榜列表。

排行榜数据上报字段

如果玩家游戏中的数据进入了某个定义的排行榜，可调用提交排行榜数据接口，提交相应的榜单数据到 Jogos 后台服务，玩家即可在 Jogos 平台打开排行榜窗口查看游戏的排行榜与自己的排名情况。

注意：接口参数中的排行榜名称与排行榜数据，必需与开发者中心定义的名称与数据类型保持一致

开发者后台可创建以下三种类型的上报数据类型：

• 数字分数：number
• 时间分数：time
• 格式化分数：自定义

上报数据为键值对，值只能是数字，字符串和日期三者之一，需与在开发者中心配置数据格式保持一致。

排行榜数据上报接口

上报排行榜数据接口：JOGOS_SDK.game.commitRankingData

/**
 * 提交排行榜数据
 *
 * @param rankingName 排行榜ID
 * @param data 排行榜数据
 */
await window.JOGOS_SDK.game.commitRankingData(rankingName: string, data: { [key: string]: any });

打开排行榜界面接口：

打开排行榜界面接口：JOGOS_SDK.game.openRankingDialog 如果您希望显示特定排行榜（而不是所有排行榜），则可以向该方法传递一个排行榜名称（与开发者后台创建名字一致）；

/**
 * 打开排行榜窗口
 *
 * @param rankingName 排行榜名称
 */
await window.JOGOS_SDK.game.openRankingDialog(rankingName: string);

成就接入

如玩家达成某项成就，可调用提交玩家成就数据接口提交相应数据到 Jogos 后台服务，玩家即可在 Jogos 平台打开玩家成就窗口查看玩家达成的成就。

注意：接口参数中的成就名称是在开发者中心定义的名称，必须保持一致

成就不为分布成就情况下：

• 达成对应成就时才需上报，即成就无显示进度，上报即表示成就达成。
• 成就设置为了分步成就情况下：进度 progress 需对应步骤 id 上报，即完成步骤 2 上报 progress = 2。

创建成就

在开发者后台 GameService 服务 - 成就页面上，选择创建成就。
在添加成就页面中，填写表单。

每一项成就都有以下相关联的基本元素：

• 成就 ID：支持字母数字的组合，用于匹配游戏玩家上报和网站中展示成就。该值同一款游戏必须唯一。
• 名称：成就的明称（例如“Pieman”）。
• 成就条件：成就条件描述。通常情况下，该值会告知玩家如何达成成就
• Icon：与您的成就相关联的方形图标。需要上传未解锁和已解锁的图片。
• 成就类型（*Achievement Types），支持 3 种类型，单选，在前台按类型顺序分开展示成就列表：
  • 初级探索成就（Beginner's Exploration Achievements），可以创建 900 条。
  • 中级挑战成就（Intermediate Challenge Achievements），可以创建 50 条。
  • 高级荣耀成就（Advanced Glory Achievements），可以创建 10 条。

状态：成就可以处于以下三种不同的状态之一：

• 隐藏成就 是指成就的详细信息将对玩家隐藏。Jogos 游戏服务将为处于隐藏状态的成就提供通用的占位符说明和图标。如果某个成就包含您不想过早显示的游戏剧透（例如，“Discover that you were a ghost all along!”），我们建议您将其设为隐藏。
• 揭密成就 表示玩家已知晓该成就，但尚未达成该成就。大多数成就刚开始就处于揭密状态。
• 达成成就 表示玩家已成功达成该成就。玩家可以离线达成成就。当游戏上线后，它会与 Jogos 游戏服务同步以更新成就的达成状态。

分步成就

• 可以将成就指定为标准或分步成就。通常情况下，分步成就是指玩家需要在较长的一段时间内逐步达成成就。当玩家在分步成就中取得进展时，您可以向 Jogos 游戏服务报告该玩家已完成的进度。
• Jogos 服务会跟踪进度信息，在玩家达到达成该成就所需的条件时提醒游戏，并告知玩家距离实现该目标还有多远。

图标指南

图标应创建为 512 x 512 的 PNG、JPEG 或 JPG 文件。您只需向我们提供已达成的成就的图标。我们建议您在成就图标中包含彩色元素，以便用户区分显示的成就和达成的成就。 所有语言区域均使用相同的图标，因此我们建议您不要在图标中添加任何文本或本地化内容。

上报成就接口

/**
 * 提交玩家成就数据
 *
 * @param name 成就ID
 * @param progress 完成进度
 * @param hidden 隐藏标记
 */
await window.JOGOS_SDK.game.commitAchievementsData(name: string, progress: number, hidden: boolean);

打开成就界面接口：

Jogos 平台有提供打开玩家成就窗口的功能，如有需要，也可以在游戏中调用接口打开玩家成就窗口。

// 打开玩家成就窗口
await window.JOGOS_SDK.game.openAchievementsDialog();