101 lines
3.2 KiB
Markdown
101 lines
3.2 KiB
Markdown
# 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:
|
||
```html
|
||
<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:
|
||
|
||
```javascript
|
||
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:
|
||
|
||
```javascript
|
||
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
|