Game Leaderboard

For service introduction and console setup instructions, Introduction documentplease refer to.

The game leaderboard is a feature that aggregates users' game scores and lets them check rankings. It connects through the following two functions.

• Submit score: Record the score on the leaderboard after the game ends → submitGameCenterLeaderBoardScore
• Open leaderboard: Call the leaderboard WebView so users can check their ranking → openGameCenterLeaderboard

---

1. Submit scores to the game leaderboard

SDK function: submitGameCenterLeaderBoardScore

submitGameCenterLeaderBoardScoreis A function that submits the user's score to the leaderboard when the game ends. The submitted score will be shown to the user later on the leaderboard screen.

Please note

• Toss app 5.221.0 or lateris supported only. On lower versions, undefinedis returned.
• If you submit a score before the game profile is created, an error may occur. not immediately after entering the game, but after play is complete. Please call it.
• If you call it before mini-app information approval is complete LeaderBoard not found , an error occurs.
• You can also test it in the sandbox environment, but sandbox scores are not reflected in the production leaderboard.
• For security reasons, the user identifier is not included in the response.

Signature

function submitGameCenterLeaderBoardScore(params: {
  score: string;
}): Promise<SubmitGameCenterLeaderBoardScoreResponse | undefined>;

Parameters

• params.score · Required · string

  This is the game score to submit. You must pass a floating-point number as a string. "123.45" or "9999" Please submit it.

Return value

• Promise<SubmitGameCenterLeaderBoardScoreResponse | undefined>

  It returns the score submission result. If the app version is lower than the minimum supported version, it does nothing and undefinedis returned.

Example: Submitting game scores to the Toss Game Center leaderboard

js

import { submitGameCenterLeaderBoardScore } from '@apps-in-toss/web-framework';

async function handleSubmitGameCenterLeaderBoardScore() {
  try {
    const result = await submitGameCenterLeaderBoardScore({ score: '123.45' });

    if (!result) {
      console.warn('Unsupported app version.');
      return;
    }

    if (result.statusCode === 'SUCCESS') {
      console.log('Score submission successful!');
    } else {
      console.error('Score submission failed:', result.statusCode);
    }
  } catch (error) {
    console.error('An error occurred while submitting the score.', error);
  }
}

React

import { submitGameCenterLeaderBoardScore } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

function GameCenterLeaderBoardScoreSubmitButton() {
  async function handleClick() {
    try {
      const result = await submitGameCenterLeaderBoardScore({ score: '123.45' });

      if (!result) {
        console.warn('Unsupported app version.');
        return;
      }

      if (result.statusCode === 'SUCCESS') {
        console.log('Score submission successful!');
      } else {
        console.error('Score submission failed:', result.statusCode);
      }
    } catch (error) {
      console.error('An error occurred while submitting the score.', error);
    }
  }

  return <Button onClick={handleClick}>Submit score</Button>;
}

React Native

import { submitGameCenterLeaderBoardScore } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';

function GameCenterLeaderBoardScoreSubmitButton() {
  async function handlePress() {
    try {
      const result = await submitGameCenterLeaderBoardScore({ score: '123.45' });

      if (!result) {
        console.warn('Unsupported app version.');
        return;
      }

      if (result.statusCode === 'SUCCESS') {
        console.log('Score submission successful!');
      } else {
        console.error('Score submission failed:', result.statusCode);
      }
    } catch (error) {
      console.error('An error occurred while submitting the score.', error);
    }
  }

  return <Button onPress={handlePress}>Submit score</Button>;
}

Try the sample app

apps-in-toss-examples from the repository with-game Download the code, or scan the QR code below to try it yourself.

QR code link: intoss://with-game

---

2. Open the game leaderboard

SDK function: openGameCenterLeaderboard

openGameCenterLeaderboard This function opens the leaderboard WebView so users can check their ranking. You can add friends or share scores with friends.

Please note

• Support starts from Toss app version 5.221.0. In versions that do not support the game leaderboard, undefinedis returned.
• the game profile WebView and screen may overlap. Please avoid calling the leaderboard immediately after entering the game.
• If you call it before mini-app information approval is complete LeaderBoard not found , an error occurs.
• When you open the leaderboard, the mini-app moves to the background. When you return from the leaderboard, it comes back to the foreground, so please pay attention to game state management.
• For security reasons, the user identifier is not included in the response.

Signature

function openGameCenterLeaderboard(): Promise<void>;

Return value

• It opens the leaderboard WebView. If the app version is lower than the minimum supported version (5.221.0), it does nothing and undefinedreturns it. (However, users below the minimum supported version cannot launch the game.)

Example: Opening the leaderboard WebView

js

import { isMinVersionSupported, openGameCenterLeaderboard } from '@apps-in-toss/web-framework';

function handleOpenGameCenterLeaderboard() {
  const isSupported = isMinVersionSupported({
    android: '5.221.0',
    ios: '5.221.0',
  });

  if (!isSupported) {
    console.warn('Unsupported app version.');
    return;
  }

  openGameCenterLeaderboard();
}

React

import { isMinVersionSupported, openGameCenterLeaderboard } from '@apps-in-toss/web-framework';
import { Button } from '@toss/tds-mobile';

// When you press the 'Leaderboard' button, the leaderboard WebView opens.
function GameCenterLeaderboardOpenButton() {
  const isSupported = isMinVersionSupported({
    android: '5.221.0',
    ios: '5.221.0',
  });

  if (!isSupported) {
    return;
  }

  function handleClick() {
    openGameCenterLeaderboard();
  }

  return <Button onClick={handleClick}>Open leaderboard WebView</Button>;
}

React Native

import { isMinVersionSupported, openGameCenterLeaderboard } from '@apps-in-toss/framework';
import { Button } from '@toss/tds-react-native';

// When you press the 'Leaderboard' button, the leaderboard WebView opens.
function GameCenterLeaderboardOpenButton() {
  const isSupported = isMinVersionSupported({
    android: '5.221.0',
    ios: '5.221.0',
  });

  if (!isSupported) {
    return;
  }

  function handlePress() {
    openGameCenterLeaderboard();
  }

  return <Button onPress={handlePress}>Open leaderboard WebView</Button>;
}

Try the sample app

apps-in-toss-examples from the repository with-game Download the code, or scan the QR code below to try it yourself.

QR code link: intoss://with-game

---

Sandbox test

You can also test the leaderboard feature in the sandbox environment. Scores recorded in the sandbox will not be reflected in the production leaderboard.

Please check the minimum supported version of the sandbox app.

• iOS: 2025-12-07
• Android: 2025-12-16

---

Notes

• The game leaderboard feature can only be used in game-category mini-apps. If you call it in a non-game mini-app, it will not work properly.
• Submitting score (submitGameCenterLeaderBoardScore) and opening the leaderboard (openGameCenterLeaderboard) are independent APIs.
• You can open the leaderboard even without submitting a score, and submitting a score does not automatically open the leaderboard.
• Scores must be submitted as numbers in string form, and the server does not provide separate score validation logic. Please handle score calculation and validation directly in your game logic.
• The leaderboard UI and data are managed by Toss Game Center, and you cannot directly modify or delete individual items through the SDK.

---

Frequently asked questions

An error occurs: LeaderBoard not found when the leaderboard function runs.

This is the error that occurs when mini-app information approval has not been completed and you call it.

Mini-app approval takes 1–2 business days. If you contact us via Channel Talk, we'll approve it quickly.

What happens to the mini-app state when the leaderboard is opened?

When you open the leaderboard, the mini-app moves to the background.

When you close the leaderboard and return, it goes back to the foreground, so please implement game state saving or pause handling.

Is only one leaderboard provided per mini-app?

Yes. Currently, only one leaderboard is provided per mini-app.

Can the user identifier be known?

For security reasons, the user identifier is not included in the response for the game profile and leaderboard functions.