A game profile is the small record a game keeps about a player: a display name, an avatar reference, a locale, an onboarding flag and a bounded bag of preferences. It is stored on the site so it follows the player between every server that shares the credential’s scope. The client is the dot-user addon.
{key} is the player’s scoped key, addressed
exactly as the avatar routes are. The scope comes from the credential, never
the request, so one server cannot read or write another game’s players.
404 means a first-time player
An unknown key, and a player with no profile yet, both answer 404. The addon
reads that as “create one”. Any other failure it reads as “keep what is in
force”, which is why a failed read is never a 404.
Reading and writing
/api/integration/v1/user/{key}/profileIntegrationPROFILE_READThe whole profile: { "ok": true, "profile": { … } }.
/api/integration/v1/user/{key}/profileIntegrationPROFILE_WRITEReplace the profile with the document sent. Answers { "ok": true, "profile": … }.
/api/integration/v1/user/{key}/profileIntegrationPROFILE_WRITEErase it. Answers { "ok": true }.
Bounds the site enforces:
- A display name is 2 to 24 characters, may be empty, needs a letter or number, may not start or end with a space and may not hold control, direction, zero-width or combining characters.
- Up to 32 preferences, names up to 40 characters, each value up to 256 bytes of JSON.
- A locale up to 16 characters and an avatar reference up to 64.
Reads and writes are separate scopes: a server that only draws names must never be able to rename anybody.
The public half
/api/integration/v1/user/{key}/publicIntegrationPROFILE_READJust { user_key, display_name, avatar_id }, returned bare rather than wrapped.
This is what a scoreboard reads. It is a separate route because it returns less:
a server drawing thirty names must not be able to read thirty players’
preferences. The same 404 rules apply.