成就與排行榜

排行榜

創建排行榜

本部分將介紹如何為新遊戲或現有遊戲創建排行榜。最多上限 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();