> 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-zh/common/growth/game-center.md).

# 游戏排行榜

服务介绍和控制台设置方法是 [介绍文档](https://developers-apps-in-toss.toss.im/guide/operation/console-workspace#undefined-18)请参考。

游戏排行榜是 **用于汇总用户的游戏分数并查看排名的功能**。它通过以下两个函数进行联动。

* **提交分数**: 游戏结束后将分数记录到排行榜中 → `submitGameCenterLeaderBoardScore`
* **打开排行榜**: 调用排行榜 WebView，让用户查看自己的排名 → `openGameCenterLeaderboard`

***

### 1. 向游戏排行榜提交分数

**SDK 函数：** `submitGameCenterLeaderBoardScore`

`submitGameCenterLeaderBoardScore`是 **在游戏结束时将用户分数提交到排行榜的函数**。提交的分数之后会在排行榜界面展示给用户。

{% hint style="info" %}
**请注意**

* Toss App **5.221.0 及以上**。在较低版本中， `undefined`则返回。
* 在游戏资料创建之前提交分数可能会出错。 **不是在进入游戏后立刻，而是在游玩完成后**请在此时调用。
* 如果在迷你应用信息尚未审核通过的状态下调用 `LeaderBoard not found` 会发生错误。
* 也可以在沙盒环境中测试，但沙盒中的分数不会反映到正式服务的排行榜中。
* 出于安全原因，响应中不会包含用户标识符。
  {% endhint %}

**签名**

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

**参数**

* **params.score** · 必填 · `string`

  这是要提交的游戏分数。需要将浮点数形式的数字以字符串传递。 `"123.45"` 或 `"9999"` 请提交。

**返回值**

* `Promise<SubmitGameCenterLeaderBoardScoreResponse | undefined>`

  会返回分数提交结果。如果应用版本低于最低支持版本，则不会执行任何操作，并且 `undefined`则返回。

**示例：将游戏分数提交到 Toss 游戏中心排行榜**

{% 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('不支持的应用版本。');
      return;
    }

    if (result.statusCode === 'SUCCESS') {
      console.log('分数提交成功！');
    } else {
      console.error('分数提交失败：', result.statusCode);
    }
  } catch (error) {
    console.error('提交分数时发生错误。', 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('不支持的应用版本。');
        return;
      }

      if (result.statusCode === 'SUCCESS') {
        console.log('分数提交成功！');
      } else {
        console.error('分数提交失败：', result.statusCode);
      }
    } catch (error) {
      console.error('提交分数时发生错误。', error);
    }
  }

  return <Button onClick={handleClick}>提交分数</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('不支持的应用版本。');
        return;
      }

      if (result.statusCode === 'SUCCESS') {
        console.log('分数提交成功！');
      } else {
        console.error('分数提交失败：', result.statusCode);
      }
    } catch (error) {
      console.error('提交分数时发生错误。', error);
    }
  }

  return <Button onPress={handlePress}>提交分数</Button>;
}
```

{% endtab %}
{% endtabs %}

**体验示例应用**

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 在仓库中 [with-game](https://github.com/toss/apps-in-toss-examples/tree/main/with-game) 下载代码，或扫描下方二维码亲自体验。

二维码链接：intoss\://with-game

***

### 2. 打开游戏排行榜

**SDK 函数：** `openGameCenterLeaderboard`

`openGameCenterLeaderboard` 这个函数会打开排行榜 WebView，让用户查看自己的排名。还可以添加好友，或与好友分享分数。

{% hint style="info" %}
**请注意**

* Toss App 5.221.0 版本起支持。在不支持游戏排行榜的版本中 `undefined`则返回。
* 可能会与游戏资料 WebView 画面重叠。请避免在进入游戏后立刻调用排行榜。
* 如果在迷你应用信息尚未审核通过的情况下调用 `LeaderBoard not found` 会发生错误。
* **打开排行榜后，迷你应用会切换到后台状态。** 从排行榜返回后会恢复到前台，请注意游戏状态管理。
* 出于安全原因，响应中不会包含用户标识符。
  {% endhint %}

**签名**

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

**返回值**

* 会调用排行榜 WebView。如果应用版本低于最低支持版本（5.221.0），则不会执行任何操作，并且 `undefined`会返回它。（不过，低于最低支持版本的用户无法运行游戏。）

**示例：调用排行榜 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('不支持的应用版本。');
    return;
  }

  openGameCenterLeaderboard();
}
```

{% endtab %}

{% tab title="React" %}

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

// 按下“排行榜”按钮后，会打开排行榜 WebView。
function GameCenterLeaderboardOpenButton() {
  const isSupported = isMinVersionSupported({
    android: '5.221.0',
    ios: '5.221.0',
  });

  if (!isSupported) {
    return;
  }

  function handleClick() {
    openGameCenterLeaderboard();
  }

  return <Button onClick={handleClick}>调用排行榜 WebView</Button>;
}
```

{% endtab %}

{% tab title="React Native" %}

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

// 按下“排行榜”按钮后，会打开排行榜 WebView。
function GameCenterLeaderboardOpenButton() {
  const isSupported = isMinVersionSupported({
    android: '5.221.0',
    ios: '5.221.0',
  });

  if (!isSupported) {
    return;
  }

  function handlePress() {
    openGameCenterLeaderboard();
  }

  return <Button onPress={handlePress}>调用排行榜 WebView</Button>;
}
```

{% endtab %}
{% endtabs %}

**体验示例应用**

[apps-in-toss-examples](https://github.com/toss/apps-in-toss-examples) 在仓库中 [with-game](https://github.com/toss/apps-in-toss-examples/tree/main/with-game) 下载代码，或扫描下方二维码亲自体验。

二维码链接：intoss\://with-game

***

### 沙盒测试

也可以在沙盒环境中测试排行榜功能。在沙盒中记录的分数不会反映到正式服务的排行榜中。

请确认沙盒应用的最低支持版本。

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

***

### 参考事项

* 游戏排行榜功能仅可在游戏类迷你应用中使用。在非游戏迷你应用中调用时不会正常工作。
* 提交分数(`submitGameCenterLeaderBoardScore`)与打开排行榜(`openGameCenterLeaderboard`)是彼此独立的 API。
* 即使不提交分数也可以打开排行榜，提交分数后排行榜也不会自动打开。
* 分数必须以字符串形式的数字提交，服务器不会提供单独的分数校验逻辑。请在游戏逻辑中自行处理分数计算和有效性检查。
* 排行榜 UI 和数据由 Toss 游戏中心管理，无法通过 SDK 直接修改或删除单个条目。

***

### 常见问题

<details>

<summary>执行排行榜函数时会发生 LeaderBoard not found 错误。</summary>

这是在迷你应用信息尚未审核通过时调用所导致的错误。

迷你应用审核通常需要 1～2 个工作日。如通过 ChannelTalk 联系我们，我们会尽快为您审核。

</details>

<details>

<summary>打开排行榜后，迷你应用状态会怎样？</summary>

打开排行榜后，迷你应用会切换到后台状态。

关闭排行榜并返回后会重新进入前台状态，请实现游戏状态保存或暂停处理等逻辑。

</details>

<details>

<summary>每个迷你应用只提供 1 个排行榜吗？</summary>

是的。目前每个迷你应用只提供一个排行榜。

</details>

<details>

<summary>可以知道用户识别值吗？</summary>

出于安全原因，在游戏资料和排行榜函数中，响应不会包含用户标识符。

</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-zh/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.