Account Modes

Use authRequired for provider-backed cloud saves.

anonymousFirst remains available for no-auth games. The safe anonymous-to-auth upgrade path is a future phase with its own merge policy.

anonymousFirstauthRequiredconflict-aware

Modes

Pick one mode for each game flow.

anonymousFirst

Best for games that do not require player sign-in before cloud saves. It remains the default non-auth flow.

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 silent anonymous-account merge 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;
}

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;
}

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-to-auth upgrade is future Phase 1D work. Do not silently merge an anonymous account into an existing provider-linked 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 instead of silently merging 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.