Skip to main content

getAnonymousKey

Returns an anonymous identifier for identifying a user within a mini-app without requiring them to log in. The result is { type: 'HASH', hash: string } — use the hash on your server to manage user data or track sessions. Returns undefined when the app version is below the minimum supported version.

Signature​

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

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

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

Parameters​

None.

Returns​

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

ValueMeaning
{ type: 'HASH', hash: string }Success — hash is the user identifier.
'ERROR'An unknown error occurred.
undefinedThe app version is below the minimum supported version.
Handle all three outcomes

Always guard against undefined and 'ERROR' before accessing hash. Skipping the checks leads to runtime errors.

Permission​

No permission required — getAnonymousKey is not bound to any PermissionName. For how other namespaces handle permissions, see Guides — Permissions pattern.

Examples​

Minimal​

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

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

  if (result === undefined) {
    console.warn('App version is too old — update required.');
    return;
  }

  if (result === 'ERROR') {
    console.error('Failed to retrieve anonymous key.');
    return;
  }

  console.log('Anonymous key:', result.hash);
}

Realistic — register anonymous session on mount​

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

// Replace `registerAnonymousSession` with your actual server 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('Please update the app and try again.');
        return;
      }

      if (result === 'ERROR') {
        setError('Session initialization failed — please try again later.');
        return;
      }

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

  if (error) return <p>{error}</p>;
  if (!ready) return <p>Loading…</p>;
  return <p>Session ready.</p>;
}

Try it live​

Run the getAnonymousKey card on the Auth page in sdk-example.

Open in sdk-example
  • appLogin — Use appLogin when the user needs to be authenticated, instead of relying on the anonymous key.
  • getIsTossLoginIntegratedService — Check whether the user has integrated Toss login.

External references​