JSONBIN_SETUP.md

JSONBin.io Setup Guide

JSONBin.io is a hosted JSON store. Frogspawn uses it as a lightweight state backend: the facilitator control panel writes exercise state to a bin, and participant inboxes poll that bin for updates.

Current Frogspawn state shape:

{
  "day": 0,
  "deployed": [],
  "deployedAt": {}
}

---

1. Create a free JSONBin account

1. Go to https://jsonbin.io and click Sign Up.
2. Verify your email address.

---

2. Create a Bin

1. Log in and click Create a Bin.

2. Paste in the initial record:

{ "day": 0, "deployed": [], "deployedAt": {} }

3. Give it a name, e.g. `frogspawn-artic-table-top`.
4. Click **Create**.
5. Copy the **Bin ID** from the URL — it looks like `684d2a3f...` (24 hex chars).

---

## 3. Get your API keys

In the JSONBin dashboard go to **API Keys**:

| Key | Purpose | Where to use |
|-----|---------|--------------|
| **Master Key** | Read + Write + Privacy updates | Control panel only — never commit this to git |
| **Access Key** (optional) | Read-only | Stored in `settings.json` for inbox/control reads |

If you set the bin to **Public** (in its settings) the Access Key is not
needed for reads; polling inboxes will work without any key.

---

## 4. Add the Bin ID to your activity settings

Edit `activities/<activity-name>/settings.json` and add these fields:

```json
{
"title": "ARTIC Table-Top exercise",
"description": "...",
"location": "...",
"date": "2025-10-25",
"pollInterval": 20000,
"jsonbinBinId": "PASTE_YOUR_BIN_ID_HERE",
"jsonbinAccessKey": "PASTE_READ_ONLY_ACCESS_KEY_OR_LEAVE_EMPTY_IF_PUBLIC"
}

Do not put the Master Key in settings.json. It is entered by the facilitator at runtime in the control panel.

---

5. Open the control panel and enter the Master Key

1. Open controls.html?activity=artic-table-top in your facilitator browser.
2. A Master Key input field is shown in the toolbar.
3. Paste your Master Key and press Connect.
4. The status badges show key status, read status, and bin visibility.
5. Use Start Day in the table to advance deployment day, or toggle individual documents.
6. Use Reset to return to day 0.

Master key storage behavior:

• Default: stored in sessionStorage for the current tab.
• If you enable Remember until cleared, it is stored in localStorage scoped by bin ID.

The Master Key is stored only in sessionStorage for that tab and is never sent to any endpoint other than api.jsonbin.io.

---

6. Open inboxes on participant devices

Participants open one of:

https://<your-host>/inbox.html?activity=artic-table-top

or

https://<your-host>/inbox.html?url=https://<your-host>/activities/artic-table-top/

The inbox polls JSONBin on a timer. When the facilitator updates state, participants see changes within one poll cycle.

---

7. Polling interval

Polling precedence in inbox is:

1. URL ?interval= override
2. settings.json pollInterval
3. default 20000 ms

Example override:

inbox.html?activity=artic-table-top&interval=30000

JSONBin's free tier allows 10 000 requests/month. At 10 s polling:

Concurrent inboxes	Requests/hour	Free tier exhausted in
10	3 600	~70 hours
30	10 800	~23 hours
50	18 000	~14 hours

For larger groups or longer events, increase the interval and/or upgrade to a JSONBin paid plan.

---

8. Resetting for a new session

1. Log in to JSONBin and set the record back to:

   {
     "day": 0,
     "deployed": [],
     "deployedAt": {}
   }

2. Or use the Reset button in control panel.

   Notes:

   • Reset sets current day to 0.
   • Documents with autoDeploy: true for day 0 are re-applied.
   • Deployments from later days are removed.

---

9. Bin privacy toggle (controls)

The control panel has a privacy switch to toggle bin visibility:

• Public -> inboxes can read without access key.
• Private -> inboxes need access key (or master key fallback in controls).

Important:

• Privacy updates require the owner account's master key for that bin.
• If JSONBin returns 401/403, the key is valid format but not authorized for that specific bin/account.

---

10. Security notes

• The Master Key gives full read/write access to all your bins. Treat it like a password.
• The Access Key is read-only; it is safe to commit to settings.json in a private repository, but avoid public repos.
• If a bin is set to Public, no key is needed for reads; anyone who knows the Bin ID can read the current day — which is fine for a training exercise.
• JSONBin does not support real-time WebSocket push; updates arrive at the next poll cycle.