Webhooky a API - BoothDock Wiki

BoothDock Studio vie informovať iné programy o každom kroku relácie (webhooky) a nechať sa ovládať inými programami (lokálne API). Oboje nájdeš v administrátorskej oblasti pod Systém → Automatizácia.

V BoothDock Studiu 1.4.0 a starších verziách sa tam webhooky ešte volajú „Spúšťače“.

Webhooky a export v reálnom čase sú len vo Windows. Lokálne API je od verzie 1.4.0 k dispozícii aj na iPade a iPhone.

Typické použitie: svetlá alebo DMX zladené s odpočítavaním, overlay pre stream, počítadlo pri vchode – alebo Stream Deck ako diaľkové ovládanie boxu.

Systém → Automatizácia: export v reálnom čase, webhooky a lokálne API

Nastavenie webhookov

Vyplň pole Program, pole Adresa (URL) alebo obe. Pri každej udalosti box zavolá oboje:

Program – súbor .exe, .bat alebo .cmd. Volanie: program <udalosť> <param1> <param2> …. Každá hodnota príde ako samostatný argument, aj keď obsahuje medzery. Program sa spustí bez okna, vo vlastnom priečinku. Skript PowerShell (.ps1) spustíš cez malý .bat pred ním.
Adresa (URL) – http alebo https, volaná cez GET: https://tvoj-server/hook?event_type=<udalosť>&param1=…&param2=…. Hodnoty sú zakódované pre URL; parametre, ktoré už sú v tvojej adrese, zostanú zachované.

Relácia nikdy nečaká na tvoj webhook: program aj volanie bežia popri nej, jedno volanie smie trvať najviac 5 sekúnd. Odoslať test hneď pošle session_start – tak overíš spojenie bez spustenia relácie.

Program a adresu možno nastaviť iba priamo na boxe, nie cez Hub: cesta k programu znamená právo niečo na počítači spustiť.

Udalosti

Udalosť	Kedy	Parametre
`session_start`	Hosť spustí reláciu, režim je určený	1: režim (`PrintOnly`, `PrintAndGIF`, `OnlyGIF`, `SlowMoOr360`, `Video`), 2: režim BoothDock (`photo`, `gif`, `boomerang`, `video`, `slowmo`, `ai`)
`countdown_start`	Začína odpočítavanie	1: sekundy
`countdown`	Každá sekunda odpočítavania	1: priebeh v percentách (od 0)
`capture_start`	Odpočítavanie skončilo, začína snímanie	–
`file_download`	Fotoaparát uložil fotku	1: názov súboru, 2: úplná cesta
`processing_start`	Začína spracovanie	pre každý originál z fotoaparátu jeden názov súboru, ako posledná hodnota tlačový súbor (zatiaľ prázdny)
`sharing_screen`	Zobrazí sa obrazovka s výsledkom (raz za reláciu)	–
`printing`	Hárok ide do tlačiarne	1: súbor (zatiaľ prázdny), 2: kópie, 3: tlačiareň
`file_upload`	Súbor dorazil do Hubu (pre každý súbor)	1: cesta na boxe, 2: odkaz na galériu, 3: typ (`print`, `photo`, `original`, `animation`, `boomerang`, `video`), 4: album (názov podujatia)
`session_end`	Relácia končí – dokončená, zrušená, vypršaná alebo vymazaná	–

Príklad súboru .bat, ktorý zapisuje každú udalosť: echo %DATE% %TIME% %* >> "%~dp0udalosti.log"

Lokálne API

Iné programy ovládajú box cez HTTP – napríklad Stream Deck, vlastný skript alebo 360° ovládanie z mobilu.

Zapnutie: Systém → Automatizácia → Zapnúť API. Z výroby je API vypnuté. Port 1500, dá sa zmeniť.
Adresa: http://localhost:1500/api/<príkaz> (alebo 127.0.0.1). Z výroby box prijíma požiadavky iba z tohto počítača.
Heslo: 16 znakov, zobrazené v tej istej sekcii – skopíruj ho alebo vygeneruj nové. Odovzdáš ho ako ?password=…, ako hlavičku X-Api-Password alebo ako Authorization: Bearer …. Bez neho funguje iba ping.
Odpoveď: vždy HTTP 200 s JSON, napríklad {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Či sa to podarilo, uvádza IsSuccessful, dôvod chyby ErrorMessage. Niektoré príkazy vracajú navyše Data.

Úplné volanie: http://localhost:1500/api/start?mode=print&password=TVOJE-HESLO

Ovládanie zo siete (mobil, tablet, 360°)

Zapni navyše Dostupné aj zo siete. Potom box prijíma požiadavky zo zariadení v tej istej Wi-Fi/LAN – nikdy z internetu.

Adresa pre mobil: je v stavovom riadku, napríklad http://192.168.1.20:1500. Príklad pod ním potom rovno ukazuje správnu adresu.
Bez zadávania IP: box sa v sieti sám ohlási (mDNS/Bonjour, typ služby _boothdock._tcp, názov „BoothDock“ plus názov počítača). Aplikácie, ktoré ho hľadajú, ho nájdu automaticky.
Zablokovanie: ak zariadenie pošle desaťkrát za desať minút nesprávne heslo, je na 15 minút zablokované. Samotný počítač boxu sa nikdy nezablokuje.
Iba vo vlastnej sieti: heslo ide sieťou nešifrovane. Sieťový režim používaj iba vo vlastnej, zabezpečenej Wi-Fi – nie v otvorenej Wi-Fi pre hostí v priestoroch podujatia.
Firewall: inštalácia nastaví výnimku, iba pre súkromné siete. Ak stavový riadok ukazuje varovanie brány firewall, preinštaluj BoothDock Studio alebo ho vo Windows povoľ v časti „Povoliť aplikáciu cez bránu firewall“. Ak Windows považuje Wi-Fi za verejnú, zariadenia sa dnu nedostanú – vo vlastnostiach siete prepni profil na Súkromná.

Príkazy

Príkaz	Účinok
`start?mode=print`	Spustí reláciu. Režimy: `print` (foto), `gif`, `boomerang`, `slowmo` (360°; bez 360° boomerang), `video`, `ai`. Funguje iba z úvodnej obrazovky, iba so zapnutým režimom a nie pri zablokovanom boxe.
`cancel`	Zruší prebiehajúcu reláciu a vráti sa na úvodnú obrazovku.
`status`	Vráti v `Data`: režim pre hostí zapnutý/vypnutý, aktuálna obrazovka, režim, zablokovaný áno/nie.
`print?count=1`	Vytlačí posledný výsledok ešte raz (1 až 10 hárkov). Videá sa tlačiť nedajú.
`lockscreen/show`	Zablokuje box textom „Chvíľku strpenia – hneď pokračujeme.“ Roh pre vstup do administrácie zostáva dostupný.
`lockscreen/exit`	Zruší zablokovanie.
`share/email?email=…`	Pošle posledný výsledok e-mailom – vyžaduje spárovanie s Hubom a akciu pri výsledku „Poslať e-mailom“ (Systém → Prevádzka → Akcie pri výsledku (hosť); do verzie 1.4.0 prepínač „Fotka e-mailom (hosť)“ pod Návrh → Obrazovky).
`share/sms`	Neexistuje; odpoveď to úprimne povie (`IsSuccessful: false`).
`createtestevent?name=…`	Vytvorí testovacie podujatie a aktivuje ho. `Data` obsahuje `eventId` a `eventName`. Bez názvu dostane názov s dátumom.
`deletetestevent?eventId=…`	Vymaže testovacie podujatie vytvorené cez API – iné podujatia nikdy.
`ping`	Bez hesla overí, či API beží.

Ak box neodpovie do 15 sekúnd, vráti sa IsSuccessful: false s upozornením.

Export v reálnom čase

Na tej istej karte zvolíš v poli Priečinok exportu cieľ – napríklad USB kľúč alebo cloudový priečinok (OneDrive, Dropbox). Každý hotový súbor tam pristane hneď, zoradený podľa podujatia a typu (Výtlačky, Originály, GIFy, Videá – každý typ sa dá vypnúť zvlášť). Ak kľúč na chvíľu chýba, box súbory doplní neskôr. Ak hosť vymaže svoju reláciu na boxe, zmiznú aj kópie.

Spustenie diaľkovým ovládačom

Na tej istej karte v časti Spustenie diaľkovým ovládačom naučíš kláves. Prezentéry, USB tlačidlá a nožné spínače väčšinou posielajú medzerník; ten je prednastavený. V poli Spustí vyberieš, čo kláves na úvodnej obrazovke vyvolá: Ako dotyk (bežný priebeh) alebo rovno režim, napríklad 360° na plošine. V BoothDock Studio 1.4.0 a starších verziách je kláves len pre 360°, pozri 360° / spomalenie.

Riešenie problémov

Nič sa nedeje: je niečo v protokole? Webhooky zapisujú do webhooks.log (do verzie 1.4.0: ausloeser.log), API do lokale-api.log – oba v priečinku %LocalAppData%\Boothdock Studio\logs. Odmietnuté požiadavky (nesprávne heslo, cudzie zariadenie) sa tam zapisujú najviac raz za minútu.
„Invalid password.“ – skopíruj heslo znova; po kliknutí na Nové heslo staré už neplatí.
„The booth is not on the start screen …“ – start funguje iba z úvodnej obrazovky. Najprv cancel, potom start.
„Too many failed attempts …“ – zariadenie poslalo príliš často nesprávne heslo. Počkaj 15 minút a skontroluj heslo.
Mobil sa k boxu nedostane, na počítači všetko funguje: takmer vždy je príčinou brána firewall systému Windows alebo Wi-Fi vedená ako verejná – pozri vyššie. Oba prípady hlási stavový riadok.