jackboxpartypack-gamepicker/docs/external-downtream-stickers.md

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):

{
  "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):

{
  "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:

{ "mode": "show" }

Response (200):

{ "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):

{ "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:

{ "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