> For the complete documentation index, see [llms.txt](https://developers-apps-in-toss.toss.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/common/growth/game-center.md).

# Game leaderboard

For service introduction and console setup instructions, [Introduction document](https://developers-apps-in-toss.toss.im/guide/operation/console-workspace#undefined-18)please 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`

`submitGameCenterLeaderBoardScore`is **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.

{% hint style="info" %}
**Please note**

* Toss app **5.221.0 or later**is supported only. On lower versions, `undefined`is 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.
  {% endhint %}

**Signature**

```typescript
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 `undefined`is returned.

**Example: Submitting game scores to the Toss Game Center leaderboard**

{% tabs %}
{% tab title="js" %}

```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);
  }
}
```

{% endtab %}

{% tab title="React" %}

```tsx
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>;
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
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>;
}
```

{% endtab %}
{% endtabs %}

**Try the sample app**

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) from the repository [with-game](https://github.com/toss/apps-in-toss-examples/tree/main/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.

{% hint style="info" %}
**Please note**

* Support starts from Toss app version 5.221.0. In versions that do not support the game leaderboard, `undefined`is 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.
  {% endhint %}

**Signature**

```typescript
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 `undefined`returns it. (However, users below the minimum supported version cannot launch the game.)

**Example: Opening the leaderboard WebView**

{% tabs %}
{% tab title="js" %}

```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();
}
```

{% endtab %}

{% tab title="React" %}

```tsx
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>;
}
```

{% endtab %}

{% tab title="React Native" %}

```tsx
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>;
}
```

{% endtab %}
{% endtabs %}

**Try the sample app**

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) from the repository [with-game](https://github.com/toss/apps-in-toss-examples/tree/main/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

<details>

<summary>An error occurs: LeaderBoard not found when the leaderboard function runs.</summary>

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.

</details>

<details>

<summary>What happens to the mini-app state when the leaderboard is opened?</summary>

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.

</details>

<details>

<summary>Is only one leaderboard provided per mini-app?</summary>

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

</details>

<details>

<summary>Can the user identifier be known?</summary>

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

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers-apps-in-toss.toss.im/documentation/api-and-sdk-en/common/growth/game-center.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.