getAnonymousKey

로그인하지 않은 사용자를 미니앱 내에서 식별하기 위한 익명 키를 반환합니다. 반환값은 { type: 'HASH', hash: string } 형태이며, 이 해시를 서버에서 사용자 데이터 관리·세션 추적 등에 활용할 수 있습니다. 앱 버전이 최소 지원 버전보다 낮으면 undefined를 반환합니다.

시그니처

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

interface GetAnonymousKeySuccessResponse {
  hash: string;
  type: 'HASH';
}

declare function getAnonymousKey(): Promise<
  GetAnonymousKeySuccessResponse | 'ERROR' | undefined
>;

파라미터

없음.

반환값

Promise<{ type: 'HASH'; hash: string } | 'ERROR' | undefined>

반환값	의미
{ type: 'HASH', hash: string }	익명 키 조회 성공. hash 필드가 사용자 식별자입니다.
'ERROR'	알 수 없는 오류가 발생했습니다.
undefined	앱 버전이 최소 지원 버전보다 낮습니다.

세 가지 케이스를 모두 처리하세요

반환값이 undefined이거나 'ERROR'인 경우를 명시적으로 처리해야 합니다. hash를 바로 사용하기 전에 반드시 타입 가드를 적용하세요.

권한

권한이 필요하지 않습니다 — getAnonymousKey는 별도의 PermissionName에 바인딩되지 않습니다. 다른 네임스페이스에서 권한을 처리하는 방식은 Guides — 권한 처리 패턴을 참고하세요.

예제

최소 예제

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

async function fetchUserKey() {
  const result = await getAnonymousKey();

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

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

  console.log('익명 키:', result.hash);
}

실전 예제 — 서버에 익명 키 등록

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

// `registerAnonymousSession`은 앱의 실제 서버 API로 대체하세요.
declare function registerAnonymousSession(hash: string): Promise<void>;

function AnonymousSessionManager() {
  const [ready, setReady] = useState(false);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    (async () => {
      const result = await getAnonymousKey();

      if (result === undefined) {
        setError('앱을 업데이트한 후 다시 시도해 주세요.');
        return;
      }

      if (result === 'ERROR') {
        setError('세션 초기화에 실패했어요. 잠시 후 다시 시도해 주세요.');
        return;
      }

      await registerAnonymousSession(result.hash);
      setReady(true);
    })();
  }, []);

  if (error) return <p>{error}</p>;
  if (!ready) return <p>로딩 중...</p>;
  return <p>세션이 준비되었어요.</p>;
}

직접 실행해 보기

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

→sdk-example에서 실행해 보기

관련 API

• appLogin — 로그인이 필요한 경우에는 getAnonymousKey 대신 appLogin을 사용하세요.
• getIsTossLoginIntegratedService — 사용자의 토스 로그인 연동 여부를 확인합니다.

관련 가이드

• Guides — 토스 로그인 흐름 — appLogin부터 서버 측 토큰 교환까지 통합 흐름.
• Guides — 권한 처리 패턴 — 다른 네임스페이스의 권한 흐름 (참고용; getAnonymousKey는 권한이 필요하지 않습니다).

외부 참조

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