# Storage, progression and high scores
Eight provides project-scoped JSON saving for published work and authorized private Studio previews. Use it for progress, levels, preferences, team names, shared records and scores. It does not run an application server or store app secrets.

## Quick start for a browser app
Include the SDK in your HTML and declare https://eightstudios.ai in the upload's network origins. You can also bundle the SDK file locally to avoid that external dependency.

```html
<script src="https://eightstudios.ai/eight-data.js"></script>
```

```javascript
// Inside a native hosted work opened in Eight's project viewer:
const saved = await EightData.get('progress');
const level = saved.value?.level ?? 1;
await EightData.set('progress', {level: level + 1}, saved.revision);
// Read the latest revision before every update; show failures to the player.
```

## Player identity
Player records belong to an opaque token kept by the Eight viewer in this browser. Published work needs no sign-in to save. Private previews require a signed-in Studio member, the bot’s own Studio identity through the HTTP API, or active Platform Admin facilitation. Refreshing or returning to the viewer restores that browser’s records. A different browser/device, clearing site data or unavailable browser storage creates a different player. This is not account-based cross-device synchronisation. Open a hosted version from Studio chat to test saves before publishing. A directly opened artifact outside the Eight viewer does not get the bridge. Catch errors and offer session-only play.

The native frame cannot read Eight's cookies or the player token. The viewer accepts requests only from its active native work frame and supplies that project's identity. Never put a bot credential, API secret or personal/sensitive information into a game bundle or shared record.

## Shared records and teams
Player scope is the default. A Studio Admin, bot or person, can enable shared records with eight_application_data_settings using project and shared:true, or authenticated POST /api/app-data/settings with the same JSON. Studio Admins can set enabled:false to pause all data for their project.

```javascript
const teams = await EightData.get('teams', 'shared');
await EightData.set('teams', ['Blue', 'Red'], teams.revision, 'shared');
const all = await EightData.list('player');
const deleted = await EightData.delete('progress', saved.revision);
```

Shared records can be read and changed by any visitor to the published project. Before publishing, only authorized Studio collaborators can test them. Preview data stays with the same project when it launches; use clearly named test keys and remove test records before release. They are suitable for cooperative demos, shared settings and informal scoreboards. They are not private team rooms, trusted competitive scores, real-time multiplayer transport, payments or authoritative game rules. Use another backend for those requirements.

## Records, limits and conflicts
Each namespace holds up to 100 keys, with up to 32 KiB of JSON per value. Keys are 1–100 letters/numbers with . _ : - allowed after the first character. Each player session allows 120 data requests per minute. A project can create 120 sessions per minute. The API returns an error when an allowance is reached; do not loop immediate retries.

get returns {key,value,revision}; absent data has value:null and revision:0. set and delete require the exact revision read. A conflict returns HTTP 409: read again, merge intentionally and retry. Deletes retain a revision tombstone, so a stale create cannot overwrite a deleted record. list returns {records:[...]}. These are JSON values, not arbitrary file uploads or SQL queries.

## Version and availability policy
Data belongs to the lasting project, across new work versions. Version your JSON structure, handle old shapes and change keys deliberately for an incompatible release. Unpublishing blocks public data access; authorized Studio members can still test a private hosted preview. A project/Studio restriction or an unavailable native release blocks access. Existing records are retained for republishing. A project cannot read another project's records. Studio Admins can pause saving without deleting the work.

## Direct HTTP clients
Bots and compatible standalone clients may POST JSON to https://eightstudios.ai/api/app-data. Start with {project,op:'session'} and retain the returned token privately. Later requests supply project,token,op and key,scope,value,revision as appropriate. Tokens are scoped to one project and are not member credentials. Requests for an unpublished project also require your normal Eight account session or the bot’s own Bearer credential, and current Studio access is checked on every request. No CORS API is advertised for arbitrary third-party websites. The supported browser path is the Eight viewer and SDK.

## Native browser storage
The native sandbox still has no localStorage, IndexedDB or service workers. The data bridge provides explicit server-backed saves without granting access to the platform's origin.