getGameCenterGameProfile

사용자의 토스게임센터 프로필(닉네임, 프로필 이미지 URL)을 조회합니다. 사용자가 프로필을 아직 생성하지 않은 경우 statusCode: 'PROFILE_NOT_FOUND'가 반환됩니다.

시그니처

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

type GameCenterGameProfileResponse =
  | { statusCode: 'PROFILE_NOT_FOUND' }
  | { statusCode: 'SUCCESS'; nickname: string; profileImageUri: string };

declare function getGameCenterGameProfile(): Promise<GameCenterGameProfileResponse | undefined>;

파라미터

없음.

반환값

• Promise<GameCenterGameProfileResponse | undefined> — 프로필 조회 결과.
  • { statusCode: 'SUCCESS'; nickname: string; profileImageUri: string } — 프로필 조회 성공. 닉네임과 프로필 이미지 URL이 포함됩니다.
  • { statusCode: 'PROFILE_NOT_FOUND' } — 사용자가 게임센터 프로필을 생성하지 않았습니다.
  • undefined — 토스 앱 버전이 최소 지원 버전(5.221.0)보다 낮습니다.

권한

권한이 필요하지 않습니다. 토스 세션(계정 연결)이 처리합니다. getPermission() / openPermissionDialog() 유틸은 노출되지 않습니다.

예제

최소 예제

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

const result = await getGameCenterGameProfile();

if (!result) {
  console.warn('앱 버전이 최소 지원 버전보다 낮습니다.');
} else if (result.statusCode === 'PROFILE_NOT_FOUND') {
  console.log('게임센터 프로필이 없습니다. 프로필 생성 안내를 표시하세요.');
} else {
  console.log('닉네임:', result.nickname);
  console.log('프로필 이미지:', result.profileImageUri);
}

실전 예제 — 프로필 카드 표시

import { getGameCenterGameProfile } from '@apps-in-toss/web-framework';
import { useEffect, useState } from 'react';

type ProfileState =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'not_found' }
  | { status: 'success'; nickname: string; profileImageUri: string }
  | { status: 'unsupported' };

function GameProfileCard() {
  const [profile, setProfile] = useState<ProfileState>({ status: 'idle' });

  useEffect(() => {
    setProfile({ status: 'loading' });
    getGameCenterGameProfile().then((result) => {
      if (!result) {
        setProfile({ status: 'unsupported' });
      } else if (result.statusCode === 'PROFILE_NOT_FOUND') {
        setProfile({ status: 'not_found' });
      } else {
        setProfile({
          status: 'success',
          nickname: result.nickname,
          profileImageUri: result.profileImageUri,
        });
      }
    });
  }, []);

  if (profile.status === 'loading') return <p>프로필 로딩 중…</p>;
  if (profile.status === 'unsupported') return <p>앱을 업데이트해 주세요.</p>;
  if (profile.status === 'not_found') return <p>게임센터 프로필을 만들어 보세요!</p>;
  if (profile.status === 'success') {
    return (
      <div>
        <img src={profile.profileImageUri} alt="프로필 이미지" />
        <p>{profile.nickname}</p>
      </div>
    );
  }
  return null;
}

직접 실행해 보기

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

→sdk-example에서 실행해 보기

관련 API

• submitGameCenterLeaderBoardScore — 리더보드에 점수를 제출합니다.
• openGameCenterLeaderboard — 게임센터 리더보드 웹뷰를 엽니다.
• getUserKeyForGame — (Deprecated) 게임용 익명 키. auth 네임스페이스에서 문서화됩니다.

관련 가이드

• Recipes — 게임센터 프로필 연동 패턴

외부 참조

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