submitGameCenterLeaderBoardScore

사용자의 게임 점수를 토스게임센터 리더보드에 제출합니다. 제출 결과에 따라 성공·실패 상태 코드가 반환되므로, 반환값을 기반으로 사용자에게 적절한 피드백을 제공할 수 있습니다.

시그니처

import { submitGameCenterLeaderBoardScore } from '@apps-in-toss/web-framework';

interface SubmitGameCenterLeaderBoardScoreResponse {
  statusCode: 'SUCCESS' | 'LEADERBOARD_NOT_FOUND' | 'PROFILE_NOT_FOUND' | 'UNPARSABLE_SCORE';
}

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

파라미터

이름	타입	필수	설명
score	string	✓	제출할 점수. 실수(float) 형태의 숫자를 문자열로 전달합니다. 예: "123.45", "9999".

점수 형식

score는 실수 형태의 문자열이어야 합니다. 숫자형(number)을 직접 넘기면 타입 오류가 발생합니다. String(score) 또는 score.toString()으로 변환하세요.

반환값

• Promise<SubmitGameCenterLeaderBoardScoreResponse | undefined>
  • { statusCode: 'SUCCESS' } — 점수 제출 성공.
  • { statusCode: 'LEADERBOARD_NOT_FOUND' } — gameId에 해당하는 리더보드를 찾을 수 없습니다.
  • { statusCode: 'PROFILE_NOT_FOUND' } — 사용자의 게임센터 프로필이 없습니다. getGameCenterGameProfile로 프로필 존재 여부를 먼저 확인하세요.
  • { statusCode: 'UNPARSABLE_SCORE' } — 점수 문자열을 해석할 수 없습니다. 실수 형태의 문자열인지 확인하세요.
  • undefined — 앱 버전이 최소 지원 버전(5.221.0)보다 낮습니다.

권한

권한이 필요하지 않습니다. 토스 세션(계정 연결)이 처리합니다.

예제

최소 예제

import { submitGameCenterLeaderBoardScore } from '@apps-in-toss/web-framework';

const result = await submitGameCenterLeaderBoardScore({ score: '1234.5' });

if (!result) {
  console.warn('앱 버전이 최소 지원 버전보다 낮습니다.');
} else if (result.statusCode === 'SUCCESS') {
  console.log('점수 제출 성공!');
} else {
  console.error('점수 제출 실패:', result.statusCode);
}

실전 예제 — 게임 종료 시 점수 제출 후 리더보드 열기

import {
  getGameCenterGameProfile,
  submitGameCenterLeaderBoardScore,
  openGameCenterLeaderboard,
} from '@apps-in-toss/web-framework';

async function onGameOver(finalScore: number) {
  // 프로필 확인 (프로필이 없으면 PROFILE_NOT_FOUND 방어)
  const profile = await getGameCenterGameProfile();
  if (!profile || profile.statusCode === 'PROFILE_NOT_FOUND') {
    console.log('게임센터 프로필이 없어 점수를 제출할 수 없습니다.');
    return;
  }

  const result = await submitGameCenterLeaderBoardScore({
    score: String(finalScore),
  });

  if (result?.statusCode === 'SUCCESS') {
    // 점수 제출 후 리더보드 오픈
    await openGameCenterLeaderboard();
  } else {
    console.error('점수 제출 실패:', result?.statusCode);
  }
}

직접 실행해 보기

sdk-example의 Game 페이지에서 submitGameCenterLeaderBoardScore 카드를 실행해 결과를 확인할 수 있습니다.

→sdk-example에서 실행해 보기

관련 API

• getGameCenterGameProfile — 프로필 존재 여부를 먼저 확인합니다.
• openGameCenterLeaderboard — 점수 제출 후 리더보드를 열 수 있습니다.

관련 가이드

• Recipes — 게임 종료 후 리더보드 연동 패턴

외부 참조

• @apps-in-toss/web-framework — 상위 SDK 패키지. 실제 export는 내부적으로 @apps-in-toss/web-bridge에서 가져옵니다.