Webhooky a API - BoothDock Wiki

BoothDock Studio umí jiným programům oznamovat každý krok relace (Webhooky) a samo se nechat ovládat jinými programy (lokální API). Obojí najdeš v administrátorské sekci Systém → Automatizace.

V BoothDock Studiu 1.4.0 a starších verzích se tam webhooky ještě jmenují „Spouštěče“.

Webhooky a export v reálném čase jsou jen pod Windows. Lokální API je od verze 1.4.0 k dispozici také na iPadu a iPhonu.

Typické použití: světla nebo DMX v rytmu odpočtu, overlay pro stream, počítadlo u vchodu – nebo Stream Deck jako dálkové ovládání boxu.

Systém → Automatizace: export v reálném čase, webhooky a lokální API

Nastavení webhooků

Vyplň Program, Adresa (URL), nebo obojí. Při každé události box zavolá obojí:

Program – soubor .exe, .bat nebo .cmd. Volání: program <událost> <param1> <param2> …. Každá hodnota přijde jako samostatný argument, i když obsahuje mezery. Program se spustí bez okna, ve vlastní složce. Skript PowerShellu (.ps1) spustíš přes malý .bat, který před něj předřadíš.
Adresa (URL) – http nebo https, volaná metodou GET: https://tvuj-server/hook?event_type=<událost>&param1=…&param2=…. Hodnoty jsou kódované pro URL; parametry, které už v tvé adrese jsou, zůstanou zachované.

Relace na tvůj webhook nikdy nečeká: program i volání běží souběžně, jedno volání smí trvat nejvýše 5 sekund. Odeslat test hned odešle session_start – tak ověříš spojení, aniž bys spouštěl relaci.

Program a adresu lze nastavit jen přímo na boxu, ne přes Hub: cesta k programu je právo něco na počítači spustit.

Události

Událost	Kdy	Parametry
`session_start`	Host spustí relaci, režim je pevně daný	1: režim (`PrintOnly`, `PrintAndGIF`, `OnlyGIF`, `SlowMoOr360`, `Video`), 2: režim BoothDock (`photo`, `gif`, `boomerang`, `video`, `slowmo`, `ai`)
`countdown_start`	Začíná odpočet	1: sekundy
`countdown`	Každá sekunda odpočtu	1: průběh v procentech (od 0)
`capture_start`	Odpočet skončil, začíná snímání	–
`file_download`	Fotoaparát uložil fotku	1: název souboru, 2: úplná cesta
`processing_start`	Začíná zpracování	za každý originál z fotoaparátu jeden název souboru, jako poslední hodnota tiskový soubor (zatím prázdný)
`sharing_screen`	Zobrazí se obrazovka s výsledkem (jednou za relaci)	–
`printing`	List jde do tiskárny	1: soubor (zatím prázdný), 2: kopie, 3: tiskárna
`file_upload`	Soubor dorazil do Hubu (pro každý soubor)	1: cesta na boxu, 2: odkaz na galerii, 3: typ (`print`, `photo`, `original`, `animation`, `boomerang`, `video`), 4: album (název akce)
`session_end`	Relace končí – dokončená, zrušená, vypršelá nebo smazaná	–

Příklad souboru .bat, který zapisuje každou událost: echo %DATE% %TIME% %* >> "%~dp0udalosti.log"

Lokální API

Jiné programy ovládají box přes HTTP – třeba Stream Deck, vlastní skript nebo ovládání 360° na mobilu.

Zapnutí: Systém → Automatizace → Zapnout API. Ve výchozím stavu je API vypnuté. Port 1500, lze změnit.
Adresa: http://localhost:1500/api/<příkaz> (nebo 127.0.0.1). Ve výchozím stavu box přijímá jen požadavky z tohoto počítače.
Heslo: 16 znaků, zobrazené ve stejné části – zkopíruj ho nebo vytvoř nové. Předává se jako ?password=…, jako hlavička X-Api-Password nebo jako Authorization: Bearer …. Bez hesla funguje jen ping.
Odpověď: vždy HTTP 200 s JSON, například {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Jestli se to povedlo, uvádí IsSuccessful, důvod chyby je v ErrorMessage. Některé příkazy navíc vracejí Data.

Úplné volání: http://localhost:1500/api/start?mode=print&password=TVOJE-HESLO

Ovládání ze sítě (mobil, tablet, 360°)

Zapni navíc Dostupné i ze sítě. Box pak přijímá požadavky ze zařízení ve stejné Wi-Fi/LAN – nikdy z internetu.

Adresa pro mobil: je ve stavovém řádku, například http://192.168.1.20:1500. Příklad pod ním pak rovnou ukazuje správnou adresu.
Bez zadávání IP: Box se v síti sám ohlásí (mDNS/Bonjour, typ služby _boothdock._tcp, název „BoothDock" plus název počítače). Aplikace, které ho hledají, ho najdou automaticky.
Blokování: Pošle-li zařízení desetkrát během deseti minut špatné heslo, bude na 15 minut zablokované. Tento počítač se nikdy nezablokuje.
Jen ve vlastní síti: Heslo jde sítí nešifrované. Síťový režim používej jen ve své vlastní, chráněné Wi-Fi – ne v otevřené Wi-Fi pro hosty v místě akce.
Firewall: Instalace nastaví výjimku, jen pro privátní sítě. Pokud stavový řádek ukazuje varování firewallu, přeinstaluj BoothDock Studio nebo ho ve Windows povol v části „Povolit aplikaci průchod bránou firewall". Pokud Windows považuje Wi-Fi za veřejnou, zařízení se dovnitř nedostanou – ve vlastnostech sítě nastav profil na Privátní.

Příkazy

Příkaz	Účinek
`start?mode=print`	Spustí relaci. Režimy: `print` (foto), `gif`, `boomerang`, `slowmo` (360°; bez 360° boomerang), `video`, `ai`. Funguje jen z úvodní obrazovky, jen se zapnutým režimem a ne při zablokovaném boxu.
`cancel`	Zruší probíhající relaci a vrátí se na úvodní obrazovku.
`status`	Vrací v `Data`: režim pro hosty zapnutý/vypnutý, aktuální obrazovku, režim, zablokováno ano/ne.
`print?count=1`	Vytiskne poslední výsledek znovu (1 až 10 listů). Videa tisknout nelze.
`lockscreen/show`	Zablokuje box hláškou „Chvíličku – hned pokračujeme." Přístup do administrace v rohu zůstává dostupný.
`lockscreen/exit`	Zruší zablokování.
`share/email?email=…`	Pošle poslední výsledek e-mailem – vyžaduje spárování s Hubem a akci s výsledkem „Získat e-mailem“ (Systém → Provoz → Akce s výsledkem (host); do verze 1.4.0 přepínač „Fotka e-mailem (host)“ pod Návrh → Obrazovky).
`share/sms`	Neexistuje; odpověď to poctivě řekne (`IsSuccessful: false`).
`createtestevent?name=…`	Založí testovací akci a nastaví ji jako aktivní. `Data` obsahuje `eventId` a `eventName`. Bez názvu dostane název s datem.
`deletetestevent?eventId=…`	Smaže testovací akci, která byla založena přes API – jiné akce nikdy.
`ping`	Bez hesla ověří, zda API běží.

Pokud box neodpoví do 15 sekund, vrátí se IsSuccessful: false s upozorněním.

Export v reálném čase

Na stejné kartě vybereš v poli Složka pro export cíl – třeba USB flash disk nebo cloudovou složku (OneDrive, Dropbox). Každý hotový soubor tam hned dorazí, roztříděný podle akce a typu (tisky, originály, GIFy, videa – každý typ lze vypnout zvlášť). Když flash disk na chvíli chybí, box soubory doplní později. Když host smaže svou relaci na automatu, zmizí i kopie.

Spuštění dálkovým ovladačem

Na stejné kartě v části Spuštění dálkovým ovladačem naučíš klávesu. Prezentéry, USB tlačítka a nožní spínače většinou posílají mezerník; ten je přednastavený. U Spustí vybereš, co klávesa na úvodní obrazovce spustí: Jako dotyk (běžný průběh) nebo rovnou režim, například 360° na platformě. V BoothDock Studio 1.4.0 a starších verzích je klávesa jen pro 360°, viz 360° / Zpomalení.

Řešení problémů

Nic se neděje: Je něco v protokolu? Webhooky zapisují do webhooks.log (do verze 1.4.0: ausloeser.log), API do lokale-api.log – oba ve složce %LocalAppData%\Boothdock Studio\logs. Odmítnuté požadavky (špatné heslo, cizí zařízení) se tam zapisují nejvýše jednou za minutu.
„Invalid password." – zkopíruj heslo znovu; po kliknutí na Nové heslo už staré neplatí.
„The booth is not on the start screen …" – start funguje jen z úvodní obrazovky. Nejdřív cancel, pak start.
„Too many failed attempts …" – zařízení poslalo příliš často špatné heslo. Počkej 15 minut a zkontroluj heslo.
Mobil se k boxu nedostane, na počítači vše funguje: téměř vždy brána firewall systému Windows nebo Wi-Fi vedená jako veřejná – viz výše. Oba případy hlásí stavový řádek.