FlareScreen

Developers – Externí přehrávač API

Poslední aktualizace: 26. 7. 2026

API pro externí Android (nebo jiné) aplikace, které přehrávají obsah FlareScreen. Registrace probíhá přes QR kód stejně jako u standardního přehrávače; zařízení se v administraci zobrazí s ikonou externího přehrávače.

1. Přehled

Externí aplikace se autentizuje tenant API klíčem (Nastavení → API klíče). Po spárování přes QR získá displayToken a dále volá display API pro playlist, média, heartbeat a telemetry.

Základní URL je origin vaší instance FlareScreen (např. https://flarescreen.com).

2. Autentizace

API klíč vytvořte v Nastavení → API klíče. Klíč se zobrazí pouze jednou – uložte si ho bezpečně do aplikace.

U párovacích endpointů (/api/v1/…) pošlete klíč v hlavičce Authorization: Bearer <klíč> nebo X-API-Key: <klíč>.

Po spárování používáte displayToken v URL cestě /api/display/{displayToken}/… – další hlavička s API klíčem není potřeba.

Authorization: Bearer fs_live_…
# nebo
X-API-Key: fs_live_…

3. Párování (QR kód)

1) Aplikace zavolá POST /api/v1/pair/register a získá pairingCode + claimUrl.

2) Zobrazte uživateli QR kód (obsah claimUrl) nebo 6místný pairingCode.

3) Uživatel naskenuje QR / zadá kód v administraci FlareScreen (stejný postup jako u Raspberry Pi přehrávače).

4) Aplikace polluje GET /api/v1/pair/status?device={deviceId}, dokud paired=true – pak uložte displayToken.

  • POST/api/v1/pair/register

    Registrace zařízení. Tělo (volitelně): { "deviceId": "…" }. Odpověď: deviceId, pairingCode, expiresAt, claimUrl, playerType.

  • GET/api/v1/pair/status?device={deviceId}

    Stav párování. paired:false, nebo paired:true + displayToken, displayUrl, screenId, screenName, playerType.

curl -X POST https://example.com/api/v1/pair/register \
  -H "Authorization: Bearer fs_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'

curl "https://example.com/api/v1/pair/status?device=DEVICE_ID" \
  -H "Authorization: Bearer fs_live_…"

4. Přehrávání obsahu

Po spárování používejte displayToken. Doporučený cyklus: stáhnout manifest (ETag), stáhnout chybějící média, odesílat heartbeat, hlásit přehrání a potvrzovat příkazy.

  • GET/api/display/{token}/manifest

    Playlist / layout pro synchronizaci. Podporuje If-None-Match → 304. Pole revision, items, prefetchItems, schedule, command, cashOnline.

  • GET/api/display/{token}/content/{contentId}

    Stažení / stream média (Range requesty podporovány).

  • GET/api/display/{token}/current

    Aktuální položky playlistu + případný pending command (prohlížečový přehrávač).

  • GET/POST/api/display/{token}/heartbeat

    Online status. Volitelně JSON systemStats (model, version, …) a hlavička x-device-local-ip.

  • POST/api/display/{token}/playback

    Telemetry přehrání. Tělo: { playlistItemId?, contentId?, itemType, playedAt? }.

  • POST/api/display/{token}/command-ack

    Potvrzení zpracování příkazu (restart, refresh, …).

GET /api/display/{token}/manifest
If-None-Match: "revision-etag"

POST /api/display/{token}/heartbeat
Content-Type: application/json
{ "systemStats": { "model": "Android", "agentVersion": "1.0.0" } }

5. Typy položek v manifestu

Každá položka má type: image | video | text | url | stream | app. U image/video použijte content URL z API. U text/url/stream/app postupujte podle metadata v položce.

Pole active říká, zda má obrazovka právě aktivní obsah dle rozvrhu. revision se mění při změně playlistu – ideální pro cache invalidaci.

6. Chyby a limity

401 – chybějící nebo neplatný API klíč.

403 – zařízení patří jinému tenantovi.

404 – neplatný displayToken / content.

429 – rate limit (zkuste později).

Párovací kód platí 15 minut. Limit obrazovek se řídí předplatným tenanta.