Persistly
Start free
Contents
The DifferenceWhy Stage MattersWhat To Test Before ProductionKeep Test Data Out Of ProductionBuild Configuration PatternWhen To Switch To ProductionCommon MistakesLaunch ChecklistRelated Resources
GuidePlatform

Stage vs Production Runtime Keys For Game Saves

Use stage runtime keys for integration testing, production runtime keys for real players, and separate save data before launch.

Published Updated 7 min readbeginner

Game save systems need a test environment.

You should be able to break save formats, reset test accounts, try new SDK versions, and test conflict handling without touching real player progress. That is why Persistly projects have separate stage and production runtime keys.

Use stage while building. Use production when real players are involved.

The Difference

Stage keys are for integration testing.

Production keys are for live player saves.

Think of them as two doors into the same project:

  • stage: experiments, test players, local builds, QA, demos
  • production: real players, live builds, paid users

The SDK setup looks the same. The runtime key decides which environment receives the save.

typescript
await PersistlyGameSaves.configure({
  runtimeKey: "ps_test_replace_me",
});

For a production build, use the live runtime key from the production environment.

typescript
await PersistlyGameSaves.configure({
  runtimeKey: "ps_live_replace_me",
});

Do not ship a public production build with a stage key.

Why Stage Matters

Stage gives you space to test risky save behavior:

  • first save creation
  • old save migrations
  • schema version changes
  • slot rename or slot selection UI
  • conflict handling
  • restore flows
  • engine or SDK upgrades
  • test accounts with bad data

Without stage, every integration mistake touches production data.

What To Test Before Production

Before switching a game build to production keys, test:

  • fresh install with no local save
  • returning player with an existing local save
  • offline save then later sync
  • browser refresh or app restart
  • two devices editing the same slot
  • corrupted or old local save data
  • a save payload near your expected large-save size
  • the actual SDK version you plan to ship

For one-save games, test saveData, loadData, and forceSyncData.

For slot-based games, test saveSlot, loadSlot, listSlots, and conflict handling for the same slot.

Keep Test Data Out Of Production

Stage saves should look like stage saves.

Good habits:

  • name test projects and slots clearly
  • use fake player data
  • avoid real purchases or private player information
  • keep test runtime keys out of production config files
  • keep production runtime keys out of public examples

Runtime keys are designed for game clients, but they still identify the project and environment. Treat them like environment-specific configuration.

Build Configuration Pattern

Use build-time environment variables or engine-specific config files.

For a web game:

typescript
await PersistlyGameSaves.configure({
  runtimeKey: import.meta.env.VITE_PERSISTLY_RUNTIME_KEY,
});

For Unity or Godot, keep the key in a project setting, build config, or small save-service wrapper instead of scattering it through scene code.

The important part is not the exact config system. The important part is that stage and production builds cannot accidentally share the same key.

When To Switch To Production

Switch to production when:

  • save/load works in stage
  • offline recovery works
  • the build uses the intended SDK version
  • your save schema has a migration plan
  • you have tested at least one new account path
  • you have tested at least one returning account path
  • your team knows where production runtime keys are stored

For public demos, decide intentionally. A small demo can use production if real players should keep progress. A test build, QA build, or private integration build should stay on stage.

Common Mistakes

Avoid these:

  • using production to test destructive save migrations
  • publishing examples with real runtime keys
  • treating stage data as player data
  • forgetting to switch keys before release
  • mixing stage and production account screenshots in support docs
  • testing only the happy path with a fresh save

Most cloud-save bugs show up when a player returns with old data. Stage is where you should find those bugs first.

Launch Checklist

Before release:

  • stage key tested locally
  • production key configured in the release build
  • save schema version is present
  • first-save path works
  • returning-save path works
  • offline path works
  • conflict path is understood
  • save-menu preview data is small
  • support team knows which project/environment to inspect

Stage is not ceremony. It is how you protect real player progress while still moving fast.