screentinker/Examples/PIP-Welcome-Board

PIP-Welcome-Board

Rotate celebratory cards — welcomes, birthdays, and work anniversaries — onto a ScreenTinker screen (or a whole group) using the PiP overlay API, driven by a simple local CSV. Great for a lobby, break room, or front-desk display.

• Birthdays / anniversaries show only on their day (matched by MM-DD).
• Welcome rows show every day.
• Cards rotate on a timer; the overlay is cleared when you stop the script.

people.csv ──> welcome.js ──poll/rotate──> POST /api/pip ──ws──> player iframe
                                                                  (welcome-overlay.html)

CSV format (csv_file)

type,name,date,note
welcome,Visitors from Acme Corp,,"Thanks for stopping by, room 204"
birthday,Priya Nair,03-14,
anniversary,Dana Olsen,2019-03-14,"Platform team lead"

column	values	notes
type	welcome | birthday | anniversary	accent colour is chosen per type
name	any text	shown large
date	MM-DD or YYYY-MM-DD	required for birthday/anniversary; ignored for welcome. A full YYYY-MM-DD anniversary shows " Years!"
note	any text (quote if it contains a comma)	optional small line

See people.example.csv.

Setup

1. Host the overlay on the signage server (same origin as the player, so the server's CSP allows the external script). Copy both files into the server's frontend/ directory:

   cp welcome-overlay.html welcome-overlay.js /path/to/screentinker/frontend/
   

   They are then served at https://<your-server>/welcome-overlay.html.

2. Configure. Copy config.example.json to config.json and fill in:

   • api_base — your ScreenTinker server
   • api_token — an st_ API token with the full scope
   • overlay_base_url — the hosted welcome-overlay.html URL
   • device_id — a device or group id
   • csv_file, rotate_interval_sec, position, width, height, show_all_when_empty

3. Run:

   npm start          # = node welcome.js
   # Ctrl-C clears the overlay and exits
   

Local quick-start (this machine)

The local player is device DEVICE_OR_GROUP_ID on https://localhost:3443/ (self-signed cert). A working config.json:

{
  "api_base": "https://localhost:3443/",
  "api_token": "st_REPLACE_WITH_A_FULL_SCOPE_TOKEN",
  "overlay_base_url": "https://localhost:3443/welcome-overlay.html",
  "device_id": "DEVICE_OR_GROUP_ID",
  "csv_file": "people.example.csv",
  "rotate_interval_sec": 12,
  "position": "center"
}

Copy the overlay into the local server's frontend/, then:

cp welcome-overlay.html welcome-overlay.js ../../frontend/
NODE_TLS_REJECT_UNAUTHORIZED=0 node welcome.js

(NODE_TLS_REJECT_UNAUTHORIZED=0 is only for the self-signed local cert.)

Test

npm test          # offline, deterministic — prints RESULT: PASS ✅

Covers CSV parsing (incl. quoted fields with commas), MM-DD date matching against a fixed "today", the welcome/always rule, the show_all_when_empty fallback, anniversary year math, and the overlay-URI round-trip.

Notes

• The overlay is a single slot on the player (last-show-wins); rotation just re-pushes.
• All card text is rendered with textContent, so CSV content is never interpreted as HTML.
• config.json and a real people.csv are git-ignored.