← Všechny články

BoothDock · Wiki

Webhooky a API

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 jsou pod Windows a od verze 1.5.10 také na iPadu, iPhonu a Macu. Lokální API je od verze 1.4.0 k dispozici také na iPadu, iPhonu a Macu, export v reálném čase od verze 1.5.2.

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
Systém → Automatizace: export v reálném čase, webhooky a lokální API

Nastavení webhooků

Vyplň Adresa (URL), pod Windows také Program – nebo obojí. Při každé události box zavolá vše, co je vyplněné:

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

Na iPadu, iPhonu a Macu je jen adresa. Tam funguje http:// jen v místní síti (IP adresa nebo .local) – Shelly, WLED a Tasmota ve Wi-Fi tedy fungují. Adresy na internetu potřebují https://.

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.

Vlastní adresa pro každou událost

Od verze 1.5.10 můžeš v části Vlastní adresa pro každou událost (volitelné) dát každé události navíc vlastní adresu – třeba pro zásuvku Shelly, WLED nebo Tasmota ve Wi-Fi, které sepnou při odpočtu nebo při snímání. Příklad pro countdown_start: http://192.168.1.50/relay/0?turn=on.

Box tuto adresu zavolá navíc k programu a adrese výše, jako prosté GET bez připojených hodnot. Dosavadní adresa i stávající skripty fungují beze změny. countdown přichází každou sekundu; u file_upload box zavolá vlastní adresu jednou za relaci (obecnou adresu dál pro každý soubor).

Události

UdálostKdyParametry
session_startHost 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_startZačíná odpočet1: sekundy
countdownKaždá sekunda odpočtu1: průběh v procentech (od 0)
capture_startOdpočet skončil, začíná snímání–
file_downloadFotoaparát uložil fotku1: název souboru, 2: úplná cesta
processing_startZačí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_screenZobrazí se obrazovka s výsledkem (jednou za relaci)–
printingList jde do tiskárny1: soubor (zatím prázdný), 2: kopie, 3: tiskárna
file_uploadSoubor 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)
lead_submittedHost odeslal formulář Údaje o hostech (formulář) (od 1.5.0)– (samotné odpovědi jsou jen v exportu CSV)
session_endRelace 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=printSpustí 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. Se šablonou, stylem a pozadím: viz níže.
auswahl?mode=printVrací v Data, co lze pro tento režim vybrat: vorlagen (Id a název; prázdné, když je povolena jen jedna šablona – ta je pak ve vorgabeVorlage), hintergruende pro každou šablonu a v režimu ai také stile (od 1.5.13).
cancelZruší probíhající relaci a vrátí se na úvodní obrazovku.
statusVrací v Data: režim pro hosty zapnutý/vypnutý, aktuální obrazovku, režim, zablokováno ano/ne – od 1.5.13 také sperrgrund (manuell nebo zeitfenster) a oeffnetUm.
print?count=1Vytiskne poslední výsledek znovu (1 až 10 listů). Videa tisknout nelze.
lockscreen/showZablokuje box hláškou „Chvíličku – hned pokračujeme." nebo tvým vlastním textem a obrázkem (viz „Zamykací obrazovka“ níže). Přístup do administrace v rohu zůstává dostupný. Od 1.5.13 zablokování přetrvá i restart aplikace.
lockscreen/exitZruší zablokování – od 1.5.13 i zablokování časovým oknem, a to do další změny.
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/smsNeexistuje; 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. Jen mimo režim pro hosty (od 1.5.4).
deletetestevent?eventId=…Smaže testovací akci, která byla založena přes API – jiné akce nikdy. Jen mimo režim pro hosty (od 1.5.4).
pingBez hesla ověří, zda API běží.

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

Spuštění relace se šablonou, stylem a pozadím

Od verze 1.5.13 přijme start výběr rovnou – box pak přeskočí právě tyto obrazovky výběru:

  • vorlage=<Id> (nebo template=) – šablona, jen v režimu print (foto). Id získáš přes auswahl?mode=print.
  • stil=<Id> (nebo style=) – AI styl, jen v režimu ai.
  • hintergrund=<Id> (nebo background=) – pozadí pro vyříznutí, odpovídající šabloně.

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

Neznámé nebo nehodící se Id nespustí žádnou relaci: IsSuccessful je false, ErrorMessage uvádí důvod. Souhlas s ochranou osobních údajů a formulář údajů hostů zobrazuje box dál sám – týkají se hosta před boxem a přes API je nelze vyřídit předem.

Zamykací obrazovka

V Akce → Zamykací obrazovka (od 1.5.13) určíš, co zablokovaný box zobrazí: vlastní text, vlastní obrázek a – u časového okna – velké odpočítávání do otevření.

  • Časové okno pro každou akci: S Otevírá v a Zavírá v je box před začátkem a po konci zablokovaný.
  • Odemknutí na zařízení: Pokud je nastaven PIN provozovatele (Systém → Ochrana), zobrazí zamykací obrazovka malý zámek. Kdo zná PIN, box odemkne. Pokud je odemčen před začátkem, zůstane otevřený až do konce.
  • Na dálku: V Hubu v sekci Boxy zablokuješ a odblokuješ každý box, který to umí (Studio od 1.5.13). Totéž jde přes BoothDock Station a pomocí lockscreen/show / lockscreen/exit.

Probíhající relaci nepřeruší ani zablokování z Hubu, ani časové okno – box se zablokuje, jakmile host skončí.

Export v reálném čase

Na stejné kartě: každý hotový soubor se hned uloží přímo na box (Místní kopie) – i bez Hubu, roztříděný podle akce a typu (tisky, originály, GIFy, videa – každý typ lze vypnout). Tato kopie se nikdy nemaže automaticky. V USB flash disk / druhá složka přidáš druhý cíl: Automaticky zapisovat na USB flash disk zapisuje na každý zasunutý flash disk, Doplnit zmeškané soubory dopíše, co vzniklo bez flash disku. Případně zadáš Pevná druhá složka (má přednost), třeba cloudovou složku (OneDrive, Dropbox). Když host smaže svou relaci na automatu, zmizí i kopie. Na iPadu a iPhonu: V aplikaci Soubory pod „Na mém iPadu › BoothDock Studio › Export“. V BoothDock Studio 1.5.3 a starším je místo toho jen Složka pro export.

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

Další kroky