163 lines
4.2 KiB
Markdown
163 lines
4.2 KiB
Markdown
# Sticker Layer Visibility Control
|
|
|
|
Integration guide for the Jackbox Game Picker to toggle sticker layer visibility on the vote-app overlay.
|
|
|
|
## Overview
|
|
|
|
The vote-app overlay shows stickers that voters purchase throughout a game session. By default, stickers are visible whenever a poll is displayed and hidden between polls. This API allows the Game Picker host to override that behavior — showing accumulated stickers between rounds (a "sticker wall showcase") or hiding them during a poll for a cleaner view.
|
|
|
|
## Modes
|
|
|
|
| Mode | Behavior |
|
|
|--------|-------------------------------------------------|
|
|
| `auto` | Default — stickers visible during polls, hidden between polls |
|
|
| `show` | Force stickers visible regardless of poll state |
|
|
| `hide` | Force stickers hidden regardless of poll state |
|
|
|
|
**Auto-reset:** When a new poll is generated, mode automatically resets to `auto`. The Game Picker receives a notification so its UI can update.
|
|
|
|
## WebSocket Integration (Primary)
|
|
|
|
### Sending: Set Mode
|
|
|
|
Send on the existing upstream WebSocket connection (`/api/sessions/live`):
|
|
|
|
```json
|
|
{
|
|
"type": "stickers.setMode",
|
|
"data": {
|
|
"mode": "show"
|
|
}
|
|
}
|
|
```
|
|
|
|
Valid values for `mode`: `"auto"`, `"show"`, `"hide"`.
|
|
|
|
### Receiving: Mode Changed
|
|
|
|
The vote-app sends this whenever the mode changes (including auto-resets):
|
|
|
|
```json
|
|
{
|
|
"type": "stickers.mode",
|
|
"mode": "auto"
|
|
}
|
|
```
|
|
|
|
**When you'll receive this:**
|
|
- After you send `stickers.setMode` (confirmation)
|
|
- When a new poll starts (mode resets to `auto`)
|
|
- When a session starts/ends (mode resets to `auto`)
|
|
- When the debug panel changes the mode
|
|
|
|
**Use this to keep your UI in sync.** If you show a toggle button, update its state whenever you receive this message.
|
|
|
|
## HTTP API (Fallback)
|
|
|
|
### Set Mode
|
|
|
|
```
|
|
PUT /api/stickers/visibility
|
|
```
|
|
|
|
**Headers:**
|
|
- `Content-Type: application/json`
|
|
- `X-API-Key: <UPSTREAM_API_KEY>`
|
|
|
|
**Request body:**
|
|
```json
|
|
{ "mode": "show" }
|
|
```
|
|
|
|
**Response (200):**
|
|
```json
|
|
{ "mode": "show", "previousMode": "auto" }
|
|
```
|
|
|
|
**Error responses:**
|
|
- `403` — Invalid or missing API key
|
|
- `400` — Invalid mode value (not `auto`/`show`/`hide`)
|
|
|
|
### Get Current Mode
|
|
|
|
```
|
|
GET /api/stickers/visibility
|
|
```
|
|
|
|
No auth required.
|
|
|
|
**Response (200):**
|
|
```json
|
|
{ "mode": "auto" }
|
|
```
|
|
|
|
Use this on startup to sync your UI state.
|
|
|
|
## Suggested UX
|
|
|
|
### Simple Toggle Button
|
|
|
|
A two-state toggle that alternates between `show` and `auto`:
|
|
|
|
```
|
|
[Show Stickers] ← when mode is "auto" or "hide"
|
|
[Hide Stickers] ← when mode is "show"
|
|
```
|
|
|
|
When receiving `stickers.mode` with `"auto"`, reset the button to "Show Stickers" state.
|
|
|
|
### Three-State Control (Advanced)
|
|
|
|
If you prefer explicit control:
|
|
|
|
```
|
|
( ) Auto — stickers follow poll visibility
|
|
(•) Show — always visible
|
|
( ) Hide — always hidden
|
|
```
|
|
|
|
Highlight the current selection. Update when receiving `stickers.mode`.
|
|
|
|
### Handling Auto-Reset
|
|
|
|
When a poll starts, mode resets and you'll receive:
|
|
```json
|
|
{ "type": "stickers.mode", "mode": "auto" }
|
|
```
|
|
|
|
Your UI should:
|
|
1. Update the button/toggle state to reflect `auto`
|
|
2. Optionally show a brief indicator ("Sticker mode reset")
|
|
|
|
## Example Flows
|
|
|
|
### Show stickers between games
|
|
|
|
1. Game ends, poll results shown, winner selected
|
|
2. Host wants to show off sticker wall before next game
|
|
3. Host clicks "Show Stickers" → sends `stickers.setMode` with `mode: "show"`
|
|
4. Sticker layer becomes visible on the overlay
|
|
5. Next poll starts → mode auto-resets to `auto`
|
|
6. Game Picker receives `stickers.mode: "auto"` → updates button
|
|
|
|
### Hide stickers during a busy poll
|
|
|
|
1. Poll is active, stickers are distracting
|
|
2. Host clicks "Hide Stickers" → sends `stickers.setMode` with `mode: "hide"`
|
|
3. Sticker layer hides on the overlay
|
|
4. Poll ends, new poll starts → mode auto-resets to `auto`
|
|
5. Stickers show normally with the new poll
|
|
|
|
### Sync on reconnect
|
|
|
|
1. Game Picker reconnects to vote-app
|
|
2. Call `GET /api/stickers/visibility` to get current mode
|
|
3. Update UI to match
|
|
|
|
## Notes
|
|
|
|
- Stickers accumulate in the DOM regardless of visibility — toggling just shows/hides the layer
|
|
- The sticker layer is at z-index 1, behind the poll overlay (z-index 9997)
|
|
- Sticker data persists across server restarts (stored in SQLite)
|
|
- Stickers are cleared on `session.started` and `session.ended` events
|