User Accounts

User Interface

The User Accounts module provides three main methods:

• login(): Prompts the user to log in if they haven't already
• getUser(): Returns information about the currently logged-in user
• getToken(): Returns a game specific JWT authentication token for the current user

User Data Structure

When a user is logged in, the getUser() method returns a User object with the following properties:

interface User {
  username: string;
  avatarUrl: string;
}

SDK methods

login()

login(): Promise<void>

Prompts the user to log in if they are not already authenticated. If the user is already logged in, this method resolves immediately. Only call it in response to a user interaction that requires an account; avoid calling it automatically on game load.

• If the user successfully logs in, a full page refresh occurs.
• If the user closes the authentication panel or takes too long (45 seconds), the promise is rejected.

try {
  await PokiSDK.login();
  // The page will reload if the user logs in.
  // In case the user is already logged in, the promise resolves instantly and you can continue from here.
  const user = await PokiSDK.getUser();
  console.log("User logged in:", user.username);
} catch (error) {
  console.log("Login failed:", error.message);
  // User closed auth panel or login timed out
}

getUser()

getUser(): Promise<User | null>

Returns the current logged-in user information, or null if no user is logged in. Throws an exception if User Accounts is not enabled, or if the user has opted out of the feature.

Call this after your game loads to handle every possible user state (logged in, logged out, or just after a page refresh caused by an authentication state change). This lets you provide the right experience from the start.

try {
  const user = await PokiSDK.getUser();
  if (user) {
    console.log(`Welcome ${user.username}!`);
  } else {
    // User is not logged in, you can call PokiSDK.login() to prompt it
    console.log("User not logged in");
  }
} catch (error) {
  // user accounts is not available or user opted out of the feature
}

Debug mode (Inspector)

With debug mode enabled, getUser() returns static mock data for local development and testing:

{
  username: 'TestUser',
  avatarUrl: 'https://a.poki-cdn.com/img/placeholder_gradient.png'
}

getToken()

getToken(): Promise<string | null>

Returns a JWT token for the current user, or null if no user is logged in. Throws an exception if User Accounts is not enabled, or if the user has opted out of the feature. This token can then be verified from your backend.

Token generation

try {
  const token = await PokiSDK.getToken();
  if (token) {
    // Send the token to your backend and verify it to obtain the user_id
    fetch("/your/backend/service", ...);
  } else {
    console.log("No authentication token available");
  }
} catch (error) {
  // user accounts is not available or user opted out of the feature
}

Token verification

You can verify the token from your backend using the Poki verification endpoint:

// Backend verification example
async function verifyPokiToken(token, teamApiKey) {
  const response = await fetch(
    "https://user-vault.poki.com/auth/verify-token",
    {
      method: "GET",
      headers: {
        Authorization: `Bearer ${token}`,
        "X-Poki-Team-Api-Key": teamApiKey,
      },
    },
  );

  if (response.ok) {
    const verificationResult = await response.json();
    console.log("Token is valid:", verificationResult); // { user_id: "unique-user-identifier" }
    return verificationResult.user_id;
  } else {
    console.log("Token verification failed");
    return null;
  }
}

The verification endpoint returns a user_id that is immutable and unique per game. Use this user_id as the primary identifier for that user in your backend systems.

Debug mode (Inspector)

With debug mode enabled, getToken() returns a valid, long-lasting JWT token that works with the Poki verification endpoint. When decoded, it resolves to the user_id "debug-user-id", letting you test the full authentication flow including backend verification.

Cloud gamesaves

When a user is logged in, the Poki SDK automatically syncs their game saves to the cloud. This is completely transparent: no extra SDK calls or setup are required. Saves are tied to the logged-in user and restored across sessions and devices.

How it works

Every time a user plays, the SDK attempts to load their gamesave from the cloud and inject it into the game before it starts. During gameplay, the SDK monitors two browser storage APIs for changes, localStorage and IndexedDB, and batches any updates to sync them back to the cloud at a throttled interval, avoiding excessive network activity and bandwidth usage.

Exclude data from cloud gamesaves

If you have data that should never be included in cloud gamesaves, prefix it with poki_ignore.

• localStorage keys that start with poki_ignore are skipped.
• IndexedDB object stores that start with poki_ignore are skipped.
• IndexedDB row keys that start with poki_ignore are skipped.

This is useful for caches, temporary state, analytics buffers, or any other local-only data that should not be restored across devices.

Storage limit

1MB gamesave limit. The gamesave payload must not exceed 1MB after gzip compression. If a player's save exceeds this limit, cloud gamesaves are automatically disabled for that player and their progress is no longer synced. Design your save data to stay well within this limit.