Beacon API

Record listening engagement for analytics.

Endpoint

POST /api/beacon

Quick Test

curl -X POST https://huebsch.schoenreden.com/api/beacon \
  -H "Content-Type: application/json" \
  -d '["550e8400-e29b-41d4-a716-446655440000", 0, 120]'

Request Body

A tuple array (not an object) to minimize payload size:

["track-uuid", 0, 120]

Validation

• end must be greater than begin
• Duration (end - begin) must exceed 2 seconds to be recorded
• All values must be non-negative finite numbers

Response

Success

{
  "ok": true,
  "val": null
}

Error

{
  "ok": false,
  "val": {
    "error": "Validation of data failed",
    "code": "422.2",
    "issues": [...]
  }
}

For error codes, see Error Codes.

Privacy

Beacons are anonymized:

• IP address and user agent are hashed together
• Only the hash is stored, not the original values
• Hash enables session grouping without identifying users

Usage

Typically called via navigator.sendBeacon() when the player page unloads:

const beacon = [trackId, beginSeconds, endSeconds];
navigator.sendBeacon('/api/beacon', JSON.stringify(beacon));

This endpoint is designed for fire-and-forget analytics. The 2-second minimum threshold filters accidental page visits.