游戏排行榜

服务介绍和控制台设置方法是 介绍文档请参考。

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

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

---

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

SDK 函数： submitGameCenterLeaderBoardScore

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

请注意

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

签名

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

参数

• params.score · 必填 · string

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

返回值

• Promise<SubmitGameCenterLeaderBoardScoreResponse | undefined>

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

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

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

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

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

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

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

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

体验示例应用

apps-in-toss-examples 在仓库中 with-game 下载代码，或扫描下方二维码亲自体验。

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

---

2. 打开游戏排行榜

SDK 函数： openGameCenterLeaderboard

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

请注意

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

签名

function openGameCenterLeaderboard(): Promise<void>;

返回值

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

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

  openGameCenterLeaderboard();
}

React

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

React Native

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

体验示例应用

apps-in-toss-examples 在仓库中 with-game 下载代码，或扫描下方二维码亲自体验。

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

---

沙盒测试

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

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

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

---

参考事项

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

---

常见问题

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

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

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

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

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

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

每个迷你应用只提供 1 个排行榜吗？

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

可以知道用户识别值吗？

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