The canonical runtime identifier. Public clients load and sync by explicit save ID.
Core Concepts
Use the same save model everywhere.
These concepts are the stable language of Persistly. Every SDK should preserve them instead of inventing new semantics.
Shared Language
These are the contract concepts game teams should learn first.
Optional developer-owned identity reference. Useful for trusted lookup flows, not public-client discovery.
Small developer-defined JSON for save selection or UI summary data such as character name, slot label, flags, and timestamps.
The full current save JSON stored by Persistly for that save record.
The version the client last loaded. Sync uses it to detect conflicts.
Mental Model
Persistly becomes easier to use when you keep the runtime flow explicit.
These steps matter more than memorizing every field name. If your game follows this flow, it stays aligned with the public runtime contract and future SDKs.
Create a save once and persist the returned saveId in the client.
Load the canonical save by saveId whenever the client resumes.
Sync state plus metadata with baseVersion so Persistly can detect conflicts.
On conflict, replace local canonical state with the server response and decide how the game should handle unsynced local edits.
Important Boundary
externalUserId is a trusted reference, not a public runtime locator.
Public clients create, load, and sync by saveId. They do not discover arbitrary saves by externalUserId.
If a game needs cross-device discovery before Persistly offers platform-owned player auth, that lookup belongs in a trusted operator or developer-managed flow.