← Všetky články

BoothDock · Wiki

Webhooky a API

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 sú vo Windows a od verzie 1.5.10 aj na iPade, iPhone a Macu. Lokálne API je od verzie 1.4.0 k dispozícii aj na iPade, iPhone a Macu, export v reálnom čase od verzie 1.5.2.

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
Systém → Automatizácia: export v reálnom čase, webhooky a lokálne API

Nastavenie webhookov

Vyplň pole Adresa (URL), vo Windows aj pole Program – alebo obe. Pri každej udalosti box zavolá všetko, čo je vyplnené:

  • Program (iba Windows) – 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é.

Na iPade, iPhone a Macu je iba adresa. Tam funguje http:// iba v miestnej sieti (IP adresa alebo .local) – Shelly, WLED a Tasmota vo Wi-Fi teda fungujú. Adresy na internete potrebujú https://.

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ť.

Vlastná adresa pre každú udalosť

Od verzie 1.5.10 môžeš v časti Vlastná adresa pre každú udalosť (voliteľné) dať každej udalosti navyše vlastnú adresu – napríklad pre zásuvku Shelly, WLED alebo Tasmota vo Wi-Fi, ktoré zopnú pri odpočítavaní alebo pri snímaní. Príklad pre countdown_start: http://192.168.1.50/relay/0?turn=on.

Box túto adresu zavolá navyše k programu a adrese vyššie, ako jednoduché GET bez pripojených hodnôt. Doterajšia adresa aj existujúce skripty fungujú bez zmeny. countdown prichádza každú sekundu; pri file_upload box zavolá vlastnú adresu raz za reláciu (všeobecnú adresu naďalej pre každý súbor).

Udalosti

UdalosťKedyParametre
session_startHosť 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_startZačína odpočítavanie1: sekundy
countdownKaždá sekunda odpočítavania1: priebeh v percentách (od 0)
capture_startOdpočítavanie skončilo, začína snímanie–
file_downloadFotoaparát uložil fotku1: názov súboru, 2: úplná cesta
processing_startZačína spracovaniepre každý originál z fotoaparátu jeden názov súboru, ako posledná hodnota tlačový súbor (zatiaľ prázdny)
sharing_screenZobrazí sa obrazovka s výsledkom (raz za reláciu)–
printingHárok ide do tlačiarne1: súbor (zatiaľ prázdny), 2: kópie, 3: tlačiareň
file_uploadSú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)
lead_submittedHosť odoslal formulár Údaje hostí (formulár) (od 1.5.0)– (samotné odpovede sú len v exporte CSV)
session_endRelá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=printSpustí 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. So šablónou, štýlom a pozadím: pozri nižšie.
auswahl?mode=printVráti v Data, čo sa dá v tomto režime vybrať: vorlagen (Id a názov; prázdne, ak je povolená iba jedna šablóna – tá je potom vo vorgabeVorlage), hintergruende pre každú šablónu a v režime ai stile (od 1.5.13).
cancelZruší prebiehajúcu reláciu a vráti sa na úvodnú obrazovku.
statusVráti v Data: režim pre hostí zapnutý/vypnutý, aktuálna obrazovka, režim, zablokovaný áno/nie – od 1.5.13 aj sperrgrund (manuell alebo zeitfenster) a oeffnetUm.
print?count=1Vytlačí posledný výsledok ešte raz (1 až 10 hárkov). Videá sa tlačiť nedajú.
lockscreen/showZablokuje box textom „Chvíľku strpenia – hneď pokračujeme.“ alebo tvojím vlastným textom a obrázkom (pozri „Uzamknutá obrazovka“ nižšie). Roh pre vstup do administrácie zostáva dostupný. Od 1.5.13 zablokovanie pretrvá aj po reštarte aplikácie.
lockscreen/exitZruší zablokovanie – od 1.5.13 aj zablokovanie časovým oknom, až do ďalšej zmeny.
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/smsNeexistuje; 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. Len mimo režimu pre hostí (od 1.5.4).
deletetestevent?eventId=…Vymaže testovacie podujatie vytvorené cez API – iné podujatia nikdy. Len mimo režimu pre hostí (od 1.5.4).
pingBez hesla overí, či API beží.

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

Spustenie relácie so šablónou, štýlom a pozadím

Od verzie 1.5.13 prijme start výber hneď – box potom preskočí práve tieto obrazovky výberu:

  • vorlage=<Id> (alebo template=) – šablóna, iba v režime print (foto). Id získaš cez auswahl?mode=print.
  • stil=<Id> (alebo style=) – AI štýl, iba v režime ai.
  • hintergrund=<Id> (alebo background=) – pozadie pre vystrihnutie, zodpovedajúce šablóne.

Príklad: http://localhost:1500/api/start?mode=print&vorlage=hochzeit-gold&hintergrund=strand&password=TVOJE-HESLO

Neznáme alebo nevhodné Id nespustí žiadnu reláciu: IsSuccessful je false, ErrorMessage uvádza dôvod. Súhlas s ochranou osobných údajov a formulár údajov hostí zobrazuje box naďalej sám – týkajú sa hosťa pred boxom a cez API ich nemožno vybaviť vopred.

Uzamknutá obrazovka

V Podujatia → Uzamknutá obrazovka (od 1.5.13) určíš, čo zobrazí zablokovaný box: vlastný text, vlastný obrázok a – pri časovom okne – veľké odpočítavanie do otvorenia.

  • Časové okno pre každé podujatie: S Otvára o a Zatvára o je box pred začiatkom a po skončení zablokovaný.
  • Odomknutie na zariadení: Ak je nastavený PIN prevádzkovateľa (Systém → Ochrana), zamykacia obrazovka zobrazí malý zámok. Kto pozná PIN, box odomkne. Ak sa odomkne pred začiatkom, zostane otvorený až do konca.
  • Na diaľku: V Hube pod Boxy zablokuješ a odblokuješ každý box, ktorý to podporuje (Studio od 1.5.13). To isté ide cez BoothDock Station a pomocou lockscreen/show / lockscreen/exit.

Prebiehajúcu reláciu nepreruší ani zablokovanie z Hubu, ani časové okno – box sa zablokuje, hneď ako hosť skončí.

Export v reálnom čase

Na tej istej karte: každý hotový súbor sa hneď uloží priamo na box (Lokálna kópia) – aj bez Hubu, zoradený podľa podujatia a typu (výtlačky, originály, GIFy, videá – každý typ sa dá vypnúť zvlášť). Táto kópia sa nikdy nemaže automaticky. V USB kľúč / druhý priečinok pridáš druhý cieľ: Automaticky zapisovať na USB kľúč zapisuje na každý vložený kľúč, Doplniť zmeškané súbory dopíše, čo vzniklo bez kľúča. Prípadne zadáš Pevný druhý priečinok (má prednosť), napríklad cloudový priečinok (OneDrive, Dropbox). Ak hosť vymaže svoju reláciu na boxe, zmiznú aj kópie. Na iPade a iPhone: V aplikácii Súbory pod „Na mojom iPade › BoothDock Studio › Export“. V BoothDock Studio 1.5.3 a staršom je namiesto toho len Priečinok exportu.

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 (Windows). 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.

Ďalšie kroky