Account Modes

Choose between play-now and sign-in-first saves.

anonymousFirst lets the player save immediately and connect the current Persistly account later. authRequired waits for provider sign-in before cloud sync.

connect lateranonymousFirstauthRequiredconflict-aware

Modes

Pick one mode for each game flow.

anonymousFirst

Best for games that let players start immediately. The current account can connect later with Firebase, Supabase, or Auth0.

authRequired

Recommended for Auth Bridge games. The game can save locally, but cloud account creation waits for provider sign-in.

SDK Example

Use the provider helper after Firebase sign-in.

Configure authRequired before exchanging the provider token. Do not rely on automatic anonymous-account import behavior.

TYPESCRIPT
await PersistlyGameSaves.configure({
  runtimeKey: "ps_test_replace_me",
  accountMode: "authRequired",
});

const token = await getFirebaseIdTokenFromFirebaseAuth();

try {
  await PersistlyGameSaves.shared.signInWithProvider({
    provider: "firebase",
    token,
    deviceLabel: "web",
  });
} catch (error) {
  if (error && typeof error === "object" && "code" in error && error.code === "account_auth_conflict") {
    showAccountConflictUI(error.details);
    return;
  }

  throw error;
}

Connect Later

Connect an existing anonymous save to Firebase.

This keeps the current Persistly account when the provider is unused. If the provider already belongs to another Persistly account, the SDK reports an account_auth_conflict and preserves local progress.

TYPESCRIPT
await PersistlyGameSaves.configure({
  runtimeKey: "ps_test_replace_me",
  accountMode: "anonymousFirst",
});

// The player can save and sync before signing in.
await PersistlyGameSaves.shared.saveData({ level: 7, coins: 420 });
await PersistlyGameSaves.shared.forceSyncData();

// Later, after your Firebase UI signs the player in:
const token = await getFirebaseIdTokenFromFirebaseAuth();

try {
  await PersistlyGameSaves.shared.connectWithFirebaseToken(token);
} catch (error) {
  if (error && typeof error === "object" && "code" in error && error.code === "account_auth_conflict") {
    showAuthConflictChoicesUI();
    return;
  }

  throw error;
}

SDK Example

Use the provider helper after Supabase sign-in.

The Supabase access token belongs only on the Auth Bridge sign-in call. Normal save/load/sync calls use the returned Persistly account session.

TYPESCRIPT
await PersistlyGameSaves.configure({
  runtimeKey: "ps_test_replace_me",
  accountMode: "authRequired",
});

const token = await getSupabaseAccessToken();

try {
  await PersistlyGameSaves.shared.signInWithProvider({
    provider: "supabase",
    token,
    deviceLabel: "web",
  });
} catch (error) {
  if (error && typeof error === "object" && "code" in error && error.code === "account_auth_conflict") {
    showAccountConflictUI(error.details);
    return;
  }

  throw error;
}

Connect Later

Auth0 uses the same connect-later pattern.

Use the provider-specific helper for your login provider, or the generic connectProvider shape when building shared auth code.

TYPESCRIPT
await PersistlyGameSaves.configure({
  runtimeKey: "ps_test_replace_me",
  accountMode: "anonymousFirst",
});

// The player can save and sync before signing in.
await PersistlyGameSaves.shared.saveData({ level: 7, coins: 420 });
await PersistlyGameSaves.shared.forceSyncData();

// Later, after your Auth0 UI signs the player in:
const token = await getAuth0Token();

try {
  await PersistlyGameSaves.shared.connectWithAuth0Token(token);
} catch (error) {
  if (error && typeof error === "object" && "code" in error && error.code === "account_auth_conflict") {
    showAuthConflictChoicesUI();
    return;
  }

  throw error;
}

Sign Out

authRequired sign-out should purge local account state.

This prevents the next local player from reading the previous player's cached account or slots.

Flush or intentionally discard pending local changes according to your game UX.

Clear the local Persistly account, slots, and account session.

Return to signed-out UI and require the next player to sign in before loading cloud saves.

Rules

Keep account mode behavior explicit in game UI.

anonymousFirst is the default mode for games that do not require player sign-in before cloud sync.

authRequired is the recommended Auth Bridge mode for games that require Firebase Auth, Supabase Auth, or Auth0 before cloud sync.

Anonymous-first games can connect the current Persistly account later with the connect helper for Firebase, Supabase, or Auth0.

Connecting later preserves the current local account and cache if the provider identity is already linked to another Persistly account.

In authRequired mode, sign-out should purge local account and slot state so the next player cannot read the previous player's local save.

If a provider identity is already linked to another Persistly account, Persistly returns an account_auth_conflict and keeps the current local progress active instead of importing, merging, or overwriting accounts.

Conflict summaries are for player-safe recovery UI. They should not expose provider subjects, token data, internal ids, or save payloads.

Provider Guides

Configure providers before relying on either mode.

Firebase Auth

Use Firebase ID tokens with Firebase project configuration per environment.

Supabase Auth

Use Supabase access tokens with Supabase project URL configuration per environment.

Auth0

Use Auth0 ID tokens or configured-audience access tokens with Auth0 tenant configuration per environment.