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

게임이 끝나면 두 가지를 빠르게 해야 합니다. 점수 제출, 그리고 리더보드 표시. 패턴은 두 가지입니다. 하나는 제출 결과를 기다렸다 리더보드를 여는 것(await-then-show), 다른 하나는 제출과 화면 전환을 동시에 트리거하는 낙관적(optimistic) 방식입니다.

await-then-show

가장 단순한 패턴. 제출이 성공하면 리더보드를 엽니다.

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

async function onGameOver(finalScore: number): Promise<void> {
  // 프로필이 없으면 PROFILE_NOT_FOUND가 반환되므로 먼저 확인합니다.
  const profile = await getGameCenterGameProfile();
  if (!profile || profile.statusCode === 'PROFILE_NOT_FOUND') {
    // 프로필 생성 안내를 표시하세요.
    return;
  }

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

  if (result?.statusCode === 'SUCCESS') {
    await openGameCenterLeaderboard();
  } else {
    // LEADERBOARD_NOT_FOUND, UNPARSABLE_SCORE 등 — 인라인 메시지로 안내.
    console.error('점수 제출 실패:', result?.statusCode);
  }
}

score는 반드시 문자열입니다. String(finalScore) 또는 finalScore.toString()으로 변환하세요.

Optimistic — 제출과 화면 전환 동시 시작

점수 제출 지연이 체감될 만큼 길 때는 리더보드를 먼저 열고 제출을 백그라운드에서 처리할 수 있습니다. 제출 실패는 리더보드 화면 안에서 별도 toast/배너로 처리합니다.

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

async function onGameOverOptimistic(finalScore: number): Promise<void> {
  // 제출과 리더보드 오픈을 동시에 시작합니다.
  const [result] = await Promise.all([
    submitGameCenterLeaderBoardScore({ score: String(finalScore) }),
    openGameCenterLeaderboard(),
  ]);

  if (result?.statusCode !== 'SUCCESS') {
    // 리더보드가 이미 열린 상태 — 배너나 토스트로 실패를 알리세요.
    console.error('점수 제출 실패:', result?.statusCode);
  }
}

두 방식 중 선택은 네트워크 지연과 UX 우선순위에 따라 결정합니다. 점수 정합성이 중요하다면 await-then-show, 속도감이 중요하다면 optimistic.

관련 API

• submitGameCenterLeaderBoardScore — 게임 점수를 리더보드에 제출.
• openGameCenterLeaderboard — 게임센터 리더보드 웹뷰를 열기.
• getGameCenterGameProfile — 프로필 존재 여부를 사전 확인.

관련 가이드

• 익명 키 게임 세션 — 로그인 없이 게임 진행도를 식별하고, 점수 등록 시점에 로그인을 트리거하는 패턴.