Skip to main content

Control Global Metadata

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 update or create global metadata (including gameMetadata and configMetadata) for a leaderboard 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 Global Metadata Parameters​

Next, define the global metadata parameters you wish to set for the leaderboard. The metadata is a flexible JSON object where you can specify any custom configuration that suits your leaderboard's needs. This method allow you to set both of gameMetadata and configMetadata in the same time.

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

const metadataParams: SetGlobalMetadataParams = {
        leaderboardId: 138,
        gameMetadata: {
          test: 'game_metadata', // Your custom key-values pairs
          key: 'strong',
          value: 'power'
        },
        configMetadata: {
          test: 'config_metadata',  // Your custom metadata key-value pairs
          key1: 'strong',
          value1: 'power'
        }
    };

Input Details:​

Mandatory Fields:

  • leaderboardId (number): The unique ID of the leaderboard.
  • configMetadata (object): - A flexible JSON object for storing config metadata related to the leaderboard. This can include any key-value pairs required by the game developer.
  • gameMetadata (object): - A flexible JSON object for storing specific game metadata related to the leaderboard. This can include any key-value pairs required by the game developer.

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

Step 3: Update or Create Game Metadata​

Once you have defined the game metadata parameters, you can update or create the metadata by calling the setConfigMetadata method on the LeaderboardManager instance.

console.log("Creating global metadata for the leaderboard...");
const globalMetadataResp = await leaderboardManager.setGlobalMetadata(metadataParams);
  
console.log("Creating global metadata for leaderboard response:");
console.log(JSON.stringify(globalMetadataResp, null, 2));

Ouput Details:​

The method returns an LeaderboardData object that contains detailed information about the user's score and the associated leaderboard.

  • leaderboardId (number): The ID of the leaderboard.
  • data (LeaderboardData): Detailed information about the leaderboard.

LeaderboardData 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 setGlobalMetadata method to get the user's score.

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