jackboxpartypack-gamepicker/docs/external-downstream-stickerwalls.md

Sticker Wall Images — Integration Guide

The vote-app renders per-session sticker walls as 1920×1080 PNG images with transparent backgrounds. These can be loaded directly as <img> sources to display a session's sticker wall.

Endpoints

Retrieve Sticker Wall Image

GET /stickerwalls/{sessionID}.png

Authentication: None (public endpoint)

Response:

• 200 OK — image/png body, Cache-Control: public, max-age=3600
• 404 Not Found — no render has been performed for this session yet

Usage: Load directly as an image source:

<img src="https://vote-app.example.com/stickerwalls/42.png" />

Trigger Render

POST /api/stickerwalls/{sessionID}/render

Authentication: Required — X-API-Key header with the upstream API key.

Response:

• 200 OK — image/png body with the rendered sticker wall
• 403 Forbidden — missing or invalid API key
• 404 Not Found — session has no placed stickers

Response Headers:

• X-Sticker-Wall-Rendered: true — a fresh render was performed
• X-Sticker-Wall-Rendered: false — served from cache (no new stickers since last render)

Behavior

Active Sessions

During an active session, stickers are placed by voters and stored in the database. The sticker wall image is not automatically re-rendered on each sticker purchase (to avoid thrashing).

To get a fresh image during an active session:

1. Call POST /api/stickerwalls/{sessionID}/render
2. If new stickers were placed since the last render, a fresh image is generated
3. The response contains the image bytes directly

Session End

When a session ends, the vote-app automatically renders the final sticker wall image. After this point:

• The image is immutable — it will never be re-rendered
• GET /stickerwalls/{sessionID}.png returns the final image directly
• POST /api/stickerwalls/{sessionID}/render returns the cached final image (with X-Sticker-Wall-Rendered: false)

Historical Sessions

Sessions that existed before this feature was deployed will be rendered on first request (via the render endpoint). Once rendered, they are cached and served normally.

Suggested Integration

Post-Session Retrieval (most common)

After a session ends, load the sticker wall for display or archival:

const sessionId = 42;
const img = new Image();
img.src = `https://vote-app.example.com/stickerwalls/${sessionId}.png`;
img.onload = () => { /* display it */ };
img.onerror = () => { /* no sticker wall for this session */ };

Active Session Preview

To show a "live preview" of the current sticker wall during a session:

async function refreshStickerWall(sessionId) {
  const res = await fetch(`/api/stickerwalls/${sessionId}/render`, {
    method: 'POST',
    headers: { 'X-API-Key': API_KEY }
  });
  if (res.ok) {
    const blob = await res.blob();
    const url = URL.createObjectURL(blob);
    document.getElementById('sticker-wall-preview').src = url;
  }
}

Image Format

• Dimensions: 1920×1080 pixels
• Format: PNG with alpha transparency
• Background: Fully transparent — overlay on any background
• Sticker rendering: Positioned, scaled, and rotated to match the live display