> 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应用 **5.221.0 以上**才支持。在更低版本中 `undefined`会返回。
* 在游戏资料创建之前提交分数，可能会发生错误。 **不是在进入游戏后立即，而是在游玩完成后**请在此时调用。
* 如果在未通过小程序信息审核的状态下调用 `未找到 LeaderBoard` 会发生错误。
* 也可以在沙盒环境中测试，但沙盒中的分数不会反映到实际服务排行榜中。
* 出于安全原因，用户标识不会包含在响应中。
  {% 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) 下载代码，或扫描下方二维码亲自体验。

QR 码链接: intoss\://with-game

***

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

**SDK 函数：** `openGameCenterLeaderboard`

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

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

* 自 Toss App 5.221.0 版本起支持。在不支持游戏排行榜的版本中， `undefined`会返回。
* 可能会与游戏资料 WebView 画面重叠。请避免在进入游戏后立刻调用排行榜。
* 在未通过小程序信息审核的情况下调用时 `未找到 LeaderBoard` 会发生错误。
* **打开排行榜后，小程序会切换到后台状态。** 从排行榜返回后会恢复到前台，请注意游戏状态管理。
* 出于安全原因，用户标识不会包含在响应中。
  {% 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) 下载代码，或扫描下方二维码亲自体验。

QR 码链接: 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.