Share one selected document

Use a replay to learn the generic shared-data API.

1. Keep the three kinds of data separate

Data	Who can read it?
Private state	The authorized player’s game session.
Capsule / showcase	Eligible visitors / profile viewers, according to the player’s sharing choices.
Selected shared document	Authorized visitors of that same game, with separate consent. It is not shown on the app’s profile card.

game.shared stores one selected JSON document per player/project, up to 16 KiB. The API has no ghost-specific endpoint. A replay, garden layout or puzzle challenge can use the same mechanism with its own reviewed schema.

2. Declare the shape

The demo’s reviewed shared schema allows a version, track, car, lap count, duration and bounded sample array. GhostData builds and validates that shape. Extra undeclared fields are rejected. Changing the schema requires review; adding private save keys does not.

A frame is [milliseconds, x, y, z, yaw, lean]. The recorder compacts up to three minutes into at most 256 frames. It publishes only the selected replay fields, never the entire private save, player credentials or arbitrary identifying text.

3. Ask before publishing

The player enables Share selected game data for your game in weBump, and the demo automatically uploads their best complete replay. Slower runs remain private. The game cannot turn on the app setting.

In the demo, a new best run calls WeBumpAPI.sync_best_replay(). That builds a document with GhostData.shared_document() and calls WeBumpAPI.publish_shared_data(). Select just the reviewed replay document. Show sync status, retain local data on failure, and offer a retry only when an upload fails. Reconnecting restores private cloud progress and retries an unsent best; it does not renew an unchanged live replay.

PUT /v1/me/shared
Authorization: Bearer <player access token>
If-Match: <exact current ETag, including its quotes>
Content-Type: application/json

{"publish":true,"value":{"…":"your reviewed document"}}

This shows the HTTP envelope, not a valid replay payload. Use the demo’s builder for a complete document. GET /v1/me/permissions reports shared_data_sharing; 403 consent_required means the separate toggle is off. Keep the saved recording and explain the setting.

4. Read through a visitor reference

GET /v1/me/visitors/<reference>/shared returns an authorized document in data. The demo adds it to its in-memory card as ghost_telemetry, validates it, then creates a ghost driver. That field is a demo adapter convention, not a private-state read or a field on every API visitor card.

Both players need current grants for the same game. The source connection, consent and publication must predate the bump’s rolling epoch. The first publication only reaches later eligible bumps. Updating an unexpired, uninterrupted publication keeps those visitors eligible for the latest data. A withdrawal or expiry gap starts a new eligibility window. Publications expire after seven days; a reference can expire earlier. No historical document versions are retained.

5. Withdraw without deleting private progress

# Wire to an explicit Unshare action in your game:
WeBumpAPI.withdraw_shared_data()

This calls DELETE /v1/me/shared with the current revision. It removes the shared copy and keeps the private save. Disabling consent or disconnecting also removes the publication. On a visitor’s 410, discard the shared copy and use the normal fallback.

Checkpoint

Enable sharing, record a best run, verify automatic publication, and make a new eligible bump afterward. Once revealed, the other player sees the replay. Disable sharing and confirm a fresh read cannot retrieve it. Run the demo’s tests/test_ghost_sharing.gd for local replay checks; it does not replace this two-player consent test.