> 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, please refer to [Introduction document](https://developers-apps-in-toss.toss.im/guide/operation/console-workspace#undefined-18).

The game leaderboard **is a feature that aggregates users' game scores and lets them check their rankings**It is. It works with 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 rankings → `openGameCenterLeaderboard`

***

### 1. Submit a score to the game leaderboard

**SDK function:** `submitGameCenterLeaderBoardScore`

`submitGameCenterLeaderBoardScore`is **A function that submits the user's score to the leaderboard when the game ends**It is. The submitted score will later be shown to the user on the leaderboard screen.

{% hint style="info" %}
**Caution**

* Toss app **5.221.0 or later**only supported in. On lower versions, `undefined`is returned.
* If you submit a score before the game profile is created, an error may occur. **After play is completed, not immediately after entering the game**please call it.
* If you call it before the mini app information is approved, `LeaderBoard not found` an error occurs.
* You can test it in the sandbox environment too, but sandbox scores are not reflected in the production leaderboard.
* For security reasons, user identifiers are 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 decimal number as a string. `"123.45"` or `"9999"` please submit it.

**Return value**

* `Promise<SubmitGameCenterLeaderBoardScoreResponse | undefined>`

  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 a game score 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('This app version is not supported.');
      return;
    }

    if (result.statusCode === 'SUCCESS') {
      console.log('Score submitted successfully!');
    } 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('This app version is not supported.');
        return;
      }

      if (result.statusCode === 'SUCCESS') {
        console.log('Score submitted successfully!');
      } 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('This app version is not supported.');
        return;
      }

      if (result.statusCode === 'SUCCESS') {
        console.log('Score submitted successfully!');
      } 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 example 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 rankings. They can add friends or share scores with friends.

{% hint style="info" %}
**Caution**

* Supported from Toss app version 5.221.0. In versions that do not support the game leaderboard, `undefined`is returned.
* it may overlap with the game profile WebView. Please avoid opening the leaderboard immediately after entering the game.
* If you call it before the mini app information is approved, `LeaderBoard not found` an error occurs.
* **When the leaderboard opens, the mini app switches to the background.** When you return from the leaderboard, it comes back to the foreground, so please be careful managing game state.
* For security reasons, user identifiers are not included in the response.
  {% endhint %}

**Signature**

```typescript
function openGameCenterLeaderboard(): Promise<void>;
```

**Return value**

* Calls 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 run 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('This app version is not supported.');
    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 example 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 test leaderboard functionality in the sandbox environment too. Scores recorded in the sandbox are not 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 is available only in mini apps in the game category. If you call it from a non-game mini app, it will not work properly.
* Score submission(`submitGameCenterLeaderBoardScore`) and opening the leaderboard (`openGameCenterLeaderboard`) are independent APIs.
* You can open the leaderboard 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 'LeaderBoard not found' error occurs when the leaderboard function is executed.</summary>

This error occurs when you call it before mini app information approval.

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 opens?</summary>

When the leaderboard opens, the mini app switches 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 I know the user's identifier?</summary>

For security reasons, user identifiers are 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.