Skip to main content

Get Leaderboard Details

For more detailed examples and guidance on implementing the Myria Leaderboard SDK, please refer to our TypeScript SDK samples on GitHub here. This repository includes practical examples demonstrating how to create, manage, and interact with leaderboards, making it easier for you to integrate leaderboard functionality into your projects.

To retrieve leaderboard details including all of information (gameMetadata, configMetadata, rewardsConfig) using the @myria/leaderboard-ts-sdk, follow the steps below.

Step 1: Initialize the Leaderboard Manager​

First, you need to initialize the LeaderboardManager with the appropriate parameters. These parameters include your environment type (e.g, STAGING, PRODUCTION) and the developerApiKey you received from the Myria Admin.

import { LeaderboardManager, InitLeaderboardParams, LeaderboardEnv } from '@myria/leaderboard-ts-sdk';

const developerApiKey = "YOUR_DEVELOPER_API_KEY";

const leaderboardParams: InitLeaderboardParams = {
  env: LeaderboardEnv.staging, // Use your desired environment type
  apiKey: developerApiKey,
};

const leaderboardManager = new LeaderboardManager(initLeaderboardParams);

Step 2: Define Query Parameters​

Next, define the parameters for retrieving the details of a specific leaderboard. You can specify either the leaderboardId or leaderboardName to fetch the details.

import { GetLeaderboardDetailsInfo } from '@myria/leaderboard-ts-sdk';

const leaderboardParams: GetLeaderboardDetailsInfo = {
    leaderboardIdOrName: "176", // Provide the leaderboard ID or name
};

// or if want to query by leaderboard name
const leaderboardParams: GetLeaderboardDetailsInfo = {
    leaderboardIdOrName: "Monthly Leaderboard", // Provide the leaderboard name
};

Input Details:​

Mandatory Fields:

  • leaderboardIdOrName: string The unique ID or name of the leaderboard for which you want to retrieve details.

Note: The response includes details about the leaderboard and the user's score.

Step 3: Retrieve Leaderboard Details​

Once you have defined the parameters, you can call the getLeaderboardDetailsInfo method to retrieve the details of the leaderboard, including reward configurations and metadata.

console.log("Get leaderboard details with rewards config and metadata...");
const leaderboardDetailsInfo = await leaderboardManager.getLeaderboardDetailsInfo(leaderboardParams);

console.log("Get leaderboard details:");
console.log(JSON.stringify(leaderboardDetailsInfo, null, 2));

Ouput Details:​

The response from the leaderboardData method includes the following fields:

  • leaderboardData (LeaderboardData): Detailed information about the leaderboard.

Leaderboard Data Object (LeaderboardData)

  • name (string): The name of the leaderboard.
  • description (string): A description of the leaderboard.
  • updateScoreStrategy (string): The strategy used to update scores (e.g., OVERWRITE, ACCUMULATE).
  • gameName (string): The name of the game associated with the leaderboard.
  • totalPeriods (number, optional): The total number of periods in the leaderboard.
  • livePeriodInDays (number): The number of days the leaderboard is live.
  • availableAt (string): The timestamp when the leaderboard is available.
  • enableMetadata (boolean, optional): Indicates whether metadata is enabled for the leaderboard.
  • developerId (string, optional): The ID of the developer who created the leaderboard.
  • status (string): The current status of the leaderboard (e.g., ACTIVE, INACTIVE).
  • currentPeriod (number): The current period of the leaderboard.
  • dataPersistenceInDays (number): The number of days the leaderboard data is persisted.
  • expireAt (string): The timestamp when the leaderboard will expire.
  • updatedAt (string, optional): The timestamp when the leaderboard was last updated.
  • createdAt (string, optional): The timestamp when the leaderboard was created.
  • id (number): The unique ID of the leaderboard.
  • enablePeriodRefresh (boolean, optional): Indicates whether period refresh is enabled for the leaderboard.
  • rewards (RewardObject, optional): The dynamically json object for rewards distribution config for period.
  • gameMetadata (JSONObject, optional): The dynamically json object for game metadata of leaderboard.
  • configMetadata (JSONObject, optional): The dynamically json object for config metadata of leaderboard.

RewardObject

The rewards object contains configuration data for the distribution of rewards within specific periods of the leaderboard. The structure is dynamic and organized by period number, where each period can have a list of rewards.

Fields:

  • period (number): The period number during which the rewards are applicable. Each period can have multiple rewards assigned.

Reward Object Fields:

  • createdAt (string): The timestamp indicating when the reward was created, in ISO 8601 format.

  • updatedAt (string): The timestamp indicating the last update to the reward, in ISO 8601 format.

  • id (number): The unique identifier of the reward.

  • name (string): The name of the reward (e.g., "2000 MYRIA").

  • leaderboardId (number): The ID of the leaderboard to which the reward is associated.

  • period (number): The period in which the reward is available, matching the key under the rewards object.

  • detail (object): The detailed configuration of the reward. This object includes information such as the reward type, distribution details, and associated token address for ERC20 rewards.

    • type (string): The type of reward, typically specifying the token type (e.g., ERC20).
    • amount (string): The specific amount of the reward allocated to the user, represented as a string (e.g., "100").
    • tokenAddress (string): The contract address of the token (e.g., for ERC20 tokens).
    • distributionType (string): Specifies how the reward is distributed (e.g., FIXED or PERCENTAGE, where all users in the rank receive a fixed reward).
    • rewardPoolAmount (number): The total amount allocated for the reward pool, used for distribution across multiple winners, if applicable.

  • rank (object): The rank range that determines which users are eligible for the reward. The reward will be given to users whose leaderboard ranks fall within this range.

    • min (number): The minimum rank eligible for the reward (e.g., rank 1).
    • max (number): The maximum rank eligible for the reward (e.g., rank 10).

  • metadata (JSONObject, optional): A flexible JSON object for storing additional metadata or custom fields related to the reward, such as descriptions or additional information for internal use.

Summary​

By following these steps, you can successfully retrieve a specific user's score from a leaderboard using the @myria/leaderboard-ts-sdk. This process involves initializing the LeaderboardManager, defining the query parameters, and invoking the getLeaderboardDetailsInfo method to get the user's score.

For more details on the available options and additional features, refer to the full documentation.