게임 로그인

지원환경: React NativeReact Native SDKv1.4.0WebViewWebView SDKv1.4.0

실행환경: Toss App최소버전v5.232.0Sandbox App

getUserKeyForGame

getUserKeyForGame 함수는 게임 미니앱에서 유저를 식별할 수 있는 키 값을 가져오는 함수예요.
별도의 서버 연동 없이도 토스 로그인 기능처럼 유저를 구분할 수 있어요.

이 함수로 반환되는 유저 식별자(hash)는 미니앱별로 고유하며, 프로모션(토스 포인트) 기능에서도 함께 사용할 수 있어요.

주의하세요

• 이 함수는 게임 카테고리 미니앱에서만 사용 가능하며, 비게임 카테고리에서 호출하면 오류가 발생해요.
• 토스앱 5.232.0 버전 이상에서 지원돼요. 그 이하 버전에서는 undefined를 반환해요.
• 모든 유저의 식별자를 안정적으로 확보하기 위해 토스앱 최소 지원 버전이 5.232.0 버전으로 상향되었어요.
  • 지원 버전 미만에서는 미니앱 진입 시 업데이트 안내 화면이 표시돼요.
• 게임 유저 식별자는 게임사 내부 유저 식별용 키로만 사용되며, 해당 키로 토스 서버에 직접 요청할 수 없어요.

시그니처

function getUserKeyForGame(): Promise<GetUserKeyForGameSuccessResponse | 'INVALID_CATEGORY' | 'ERROR' | undefined>;

반환 값

• Promise<GetUserKeyForGameSuccessResponse | 'INVALID_CATEGORY' | 'ERROR' | undefined>
  

사용자 키 조회 결과를 반환해요.

• GetUserKeyForGameSuccessResponse: 사용자 키 조회에 성공했어요. { type: 'HASH', hash: string } 형태로 반환돼요.
• 'INVALID_CATEGORY': 게임 카테고리가 아닌 미니앱에서 호출했어요.
• 'ERROR': 알 수 없는 오류가 발생했어요.
• undefined: 앱 버전이 최소 지원 버전보다 낮아요.

예제

React

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

function GameUserKeyButton() {
  async function handleClick() {
      const result = await getUserKeyForGame();

      if (!result) {
        console.warn('지원하지 않는 앱 버전이에요.');
        return;
      }

      if (result === 'INVALID_CATEGORY') {
        console.error('게임 카테고리가 아닌 미니앱이에요.');
        return;
      }

      if (result === 'ERROR') {
        console.error('사용자 키 조회 중 오류가 발생했어요.');
        return;
      }

      if (result.type === 'HASH') {
        console.log('사용자 키:', result.hash);
        // 여기에서 사용자 키를 사용해 게임 데이터를 관리할 수 있어요.
      }
  }

  return (
    <button onClick={handleClick}>유저 키 가져오기</button>
  );
}

React Native

// react-native
import { Button } from 'react-native';
import { getUserKeyForGame } from '@apps-in-toss/framework';

function GameUserKeyButton() {
  async function handlePress() {
      const result = await getUserKeyForGame();

      if (!result) {
        console.warn('지원하지 않는 앱 버전이에요.');
        return;
      }

      if (result === 'INVALID_CATEGORY') {
        console.error('게임 카테고리가 아닌 미니앱이에요.');
        return;
      }

      if (result === 'ERROR') {
        console.error('사용자 키 조회 중 오류가 발생했어요.');
        return;
      }

      if (result.type === 'HASH') {
        console.log('사용자 키:', result.hash);
        // 여기에서 사용자 키를 사용해 게임 데이터를 관리할 수 있어요.
      }
  }

  return (
    <Button onPress={handlePress} title="유저 키 가져오기" />
  );
}