Achievements & Leaderboards

Leaderboards

Creating a Leaderboard

This section explains how to create a leaderboard for a new or existing game.
A maximum of 20 leaderboards can be created, and each leaderboard ID must be unique within the game.

To create a leaderboard, open the GameRank management page for your game, select Extensions > Add, and click the Create Leaderboard button.

Then fill in the required information for the leaderboard.

Score Formats

• Numeric Leaderboards display scores as numbers. These can be integers or floating-point values, e.g. 3.14159, 3141.59, or 314159.
  Note that the value should not be too large; only single-precision is currently supported.

• Time Leaderboards show scores in the format hours / minutes / seconds / centiseconds or traditional clock format (HH:MM:SS), e.g. 66032, 1:06:3.

• Formatted Scores are displayed in a custom format. Submit the score in the currency unit format, e.g. $19.95.

Background Image Guidelines

The leaderboard background image must be a 1024 × 1024 JPEG file.
It is optional; if not uploaded, the platform default image will be used.
The same background image is used for all locales, so we recommend avoiding text or localized content in the image.

Managing Leaderboards

For the leaderboard list, developers can handle anomalous players as follows:

• Delete: Remove the player's currently displayed leaderboard data.
• Add to Blacklist: Prevent the player from participating in all leaderboards of this game going forward.
  After adding to the blacklist, you can view and remove players from the blacklist across all leaderboards.
• Edit Data: Click to open the edit leaderboard page.
• Delete Leaderboard: Click to delete the specified leaderboard.

Leaderboard Data Submission Fields

When a player's in-game data qualifies for a defined leaderboard, call the data submission API to send the corresponding leaderboard data to the Jogos backend.
The player can then open the leaderboard window on the Jogos platform to view the leaderboard and their own ranking.

Note: The leaderboard name and data type in the API parameters must match those defined in the Developer Center.

The Developer Center allows creation of three submission data types:

• Numeric Score: number
• Time Score: time
• Formatted Score: custom

Submitted data must be key-value pairs. Values can only be number, string, or date, and must match the format configured in the Developer Center.

Leaderboard Data Submission API

API: JOGOS_SDK.game.commitRankingData

/**
 * Submit leaderboard data
 *
 * @param rankingName Leaderboard ID
 * @param data Leaderboard data
 */
await window.JOGOS_SDK.game.commitRankingData(rankingName: string, data: { [key: string]: any });

Open Leaderboard UI API

API: JOGOS_SDK.game.openRankingDialog
To display a specific leaderboard (instead of all), pass the leaderboard name (identical to the name created in the Developer Center) to this method.

/**
 * Open leaderboard window
 *
 * @param rankingName Leaderboard name
 */
await window.JOGOS_SDK.game.openRankingDialog(rankingName: string);

Achievements Integration

When a player unlocks an achievement, call the achievement submission API to send the corresponding data to the Jogos backend.
The player can then open the achievements window on the Jogos platform to view their unlocked achievements.

Note: The achievement name in the API parameters must match the name defined in the Developer Center.

For non-step achievements:

• Only report when the achievement is unlocked. There is no visible progress—reporting means the achievement is complete.

For step achievements:

• Report progress matching the step ID. For example, when step 2 is completed, report progress = 2.

Creating an Achievement

In the Developer Center, open GameService > Achievements and select Create Achievement.
Fill in the form on the Add Achievement page.

Each achievement includes the following core elements:

• Achievement ID: Alphanumeric string, unique per game, used to match in-game reports and display.
• Name: Display name of the achievement (e.g., "Pieman").
• Achievement Condition: Description telling players how to unlock the achievement.
• Icon: Square icon for the achievement. Upload both locked and unlocked versions.
• Achievement Types (single-choice, displayed separately in the UI):
  • Beginner's Exploration Achievements – up to 900.
  • Intermediate Challenge Achievements – up to 50.
  • Advanced Glory Achievements – up to 10.

States

• Hidden Achievement: Details are hidden. Jogos provides a generic placeholder description and icon.
  Use this for spoilers (e.g., "Discover that you were a ghost all along!").

• Revealed Achievement: Player knows about the achievement but has not yet unlocked it.
  Most achievements start in this state.

• Unlocked Achievement: Player has successfully unlocked it.
  Players can unlock achievements offline; the game syncs with Jogos when online.

Step Achievements

• Achievements can be standard or step-based.
  Step achievements require progress over time. Report the player's current step to Jogos, which tracks progress and informs the game (and player) when the achievement is complete.

Icon Guidelines

Icons must be 512 × 512 PNG, JPEG, or JPG files.
Provide only the unlocked icon; we recommend using color to distinguish unlocked achievements.
Use the same icon for all locales—avoid text or localized content.

Achievement Submission API

/**
 * Submit player achievement data
 *
 * @param name Achievement ID
 * @param progress Completion progress
 * @param hidden Hidden flag
 */
await window.JOGOS_SDK.game.commitAchievementsData(name: string, progress: number, hidden: boolean);

Open Achievements UI API

Jogos provides a built-in player achievements window. You can open it from within your game.

// Open player achievements window
await window.JOGOS_SDK.game.openAchievementsDialog();