Webhookok és API - BoothDock Wiki

A BoothDock Studio egy munkamenet minden lépéséről értesíteni tud más programokat (webhookok), és hagyja, hogy más programok vezéreljék (helyi API). Mindkettőt az admin-területen a Rendszer → Automatizálás alatt találod.

A BoothDock Studio 1.4.0-s és korábbi verzióiban a webhookok ott még „Eseményindítók” néven szerepelnek.

Webhookok és valós idejű exportálás csak Windows alatt érhetők el. A helyi API az 1.4.0-s verziótól iPaden és iPhone-on is elérhető.

Tipikus felhasználás: fény vagy DMX a visszaszámláláshoz igazítva, stream-overlay, számláló a bejáratnál – vagy egy Stream Deck a box távirányítójaként.

Rendszer → Automatizálás: valós idejű exportálás, webhookok és helyi API

Webhookok beállítása

Töltsd ki a Program mezőt, a Cím (URL) mezőt vagy mindkettőt. A box minden eseménynél mindkettőt meghívja:

Program – egy .exe, .bat vagy .cmd fájl. Hívás: program <esemény> <param1> <param2> …. Minden érték külön argumentumként érkezik, akkor is, ha szóközt tartalmaz. A program ablak nélkül, a saját mappájában indul. Egy PowerShell-szkriptet (.ps1) egy elé tett kis .bat fájllal indíthatsz.
Cím (URL) – http vagy https, GET-kéréssel hívva: https://a-te-szervered/hook?event_type=<esemény>&param1=…&param2=…. Az értékek URL-kódoltak; a címedben már szereplő paraméterek megmaradnak.

A munkamenet sosem vár a webhookodra: a program és a hívás párhuzamosan fut, egy hívás legfeljebb 5 másodpercig tarthat. A Teszt küldése azonnal küld egy session_start eseményt – így munkamenet indítása nélkül ellenőrizheted a kapcsolatot.

A program és a cím csak közvetlenül a boxon állítható be, a Hubon keresztül nem: egy programútvonal jogot ad arra, hogy valamit lefuttassanak a számítógépen.

Események

Esemény	Mikor	Paraméterek
`session_start`	Egy vendég munkamenetet indít, a mód eldőlt	1: mód (`PrintOnly`, `PrintAndGIF`, `OnlyGIF`, `SlowMoOr360`, `Video`), 2: BoothDock-mód (`photo`, `gif`, `boomerang`, `video`, `slowmo`, `ai`)
`countdown_start`	Elindul a visszaszámlálás	1: másodpercek
`countdown`	A visszaszámlálás minden másodperce	1: előrehaladás százalékban (0-tól)
`capture_start`	A visszaszámlálás lejárt, a felvétel elindul	–
`file_download`	A kamera elmentett egy fotót	1: fájlnév, 2: teljes elérési út
`processing_start`	A feldolgozás elindul	minden kamera-eredetihez egy fájlnév, utolsó értékként a nyomtatási fájl (jelenleg üres)
`sharing_screen`	Megjelenik az eredményképernyő (munkamenetenként egyszer)	–
`printing`	Egy lap a nyomtatóra kerül	1: fájl (jelenleg üres), 2: példányszám, 3: nyomtató
`file_upload`	Egy fájl megérkezett a Hubba (fájlonként)	1: elérési út a boxon, 2: galéria-link, 3: típus (`print`, `photo`, `original`, `animation`, `boomerang`, `video`), 4: album (az esemény neve)
`session_end`	A munkamenet véget ér – befejezve, megszakítva, lejárt vagy törölve	–

Példa egy .bat fájlra, amely minden eseményt naplóz: echo %DATE% %TIME% %* >> "%~dp0esemenyek.log"

Helyi API

Más programok HTTP-n keresztül vezérlik a boxot – például egy Stream Deck, egy saját szkript vagy egy 360°-os vezérlés a telefonon.

Bekapcsolás: Rendszer → Automatizálás → API bekapcsolása. Gyárilag az API ki van kapcsolva. Port 1500, módosítható.
Cím: http://localhost:1500/api/<parancs> (vagy 127.0.0.1). Gyárilag a box csak erről a számítógépről fogad kéréseket.
Jelszó: 16 karakter, ugyanebben a szakaszban látható – másold ki, vagy hozz létre újat. Átadható ?password=… formában, X-Api-Password fejlécként vagy Authorization: Bearer … formában. Csak a ping működik nélküle.
Válasz: mindig HTTP 200 JSON-nal, például {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Hogy sikerült-e, az IsSuccessful mutatja, hiba esetén az okot az ErrorMessage. Egyes parancsok ezen felül Data mezőt is visszaadnak.

Egy teljes hívás: http://localhost:1500/api/start?mode=print&password=A-TE-JELSZAVAD

Vezérlés a hálózatról (telefon, tablet, 360°)

Kapcsold be emellett ezt is: A hálózatról is elérhető. Ekkor a box az ugyanazon a Wi-Fi/LAN hálózaton lévő eszközök kéréseit is fogadja – az internetről soha.

Cím a telefonhoz: az állapotsorban látható, például http://192.168.1.20:1500. Az alatta lévő példa ilyenkor rögtön a megfelelő címet mutatja.
IP-cím beírása nélkül: a box magától bejelentkezik a hálózaton (mDNS/Bonjour, szolgáltatástípus _boothdock._tcp, név „BoothDock" plusz a számítógép neve). Az ezt kereső alkalmazások automatikusan megtalálják.
Tiltás: ha egy eszköz tíz percen belül tízszer küld hibás jelszót, 15 percre letiltásra kerül. Maga ez a számítógép soha nem kerül tiltásra.
Csak a saját hálózaton: a jelszó titkosítatlanul halad a hálózaton. A hálózati üzemmódot csak a saját, védett Wi-Fi-hálózatodon használd – ne a helyszín nyitott vendég-Wi-Fi-jén.
Tűzfal: a telepítés beállítja a kivételt, csak magánhálózatokhoz. Ha az állapotsor tűzfal-figyelmeztetést mutat, telepítsd újra a BoothDock Studio alkalmazást, vagy engedélyezd a Windows „Alkalmazás engedélyezése a tűzfalon keresztül" pontjában. Ha a Windows a Wi-Fi-t nyilvános hálózatként kezeli, az eszközök nem jutnak be – állítsd a profilt a hálózati tulajdonságokban Magánhálózat értékre.

Parancsok

Parancs	Hatás
`start?mode=print`	Munkamenetet indít. Módok: `print` (fotó), `gif`, `boomerang`, `slowmo` (360°; 360° nélkül a boomerang), `video`, `ai`. Csak a kezdőképernyőről működik, csak engedélyezett móddal, és zárolt box esetén nem.
`cancel`	Megszakítja a futó munkamenetet, és visszatér a kezdőképernyőre.
`status`	A `Data` mezőben visszaadja: vendégmód be/ki, aktuális képernyő, mód, zárolva igen/nem.
`print?count=1`	Újranyomtatja az utolsó eredményt (1–10 lap). Videókat nem lehet nyomtatni.
`lockscreen/show`	Zárolja a boxot ezzel a szöveggel: „Egy pillanat – mindjárt folytatjuk." Az admin-sarok elérhető marad.
`lockscreen/exit`	Feloldja a zárolást.
`share/email?email=…`	E-mailben elküldi az utolsó eredményt – ehhez Hub-párosítás és a „Kapd meg e-mailen” eredmény-művelet szükséges (Rendszer → Működés → Eredmény-műveletek (vendég); 1.4.0-ig a „Fotó e-mailben (vendég)” kapcsoló a Design → Képernyők alatt).
`share/sms`	Nem létezik; a válasz ezt őszintén megmondja (`IsSuccessful: false`).
`createtestevent?name=…`	Teszteseményt hoz létre és aktiválja. A `Data` tartalmazza az `eventId` és az `eventName` értéket. Név nélkül dátumos nevet kap.
`deletetestevent?eventId=…`	Törli az API-n keresztül létrehozott teszteseményt – más eseményeket soha.
`ping`	Jelszó nélkül ellenőrzi, hogy fut-e az API.

Ha a box 15 másodpercen belül nem válaszol, IsSuccessful: false érkezik vissza egy megjegyzéssel.

Valós idejű exportálás

Ugyanezen a lapon az Exportmappa mezőben választod ki a célt – például egy USB-meghajtót vagy egy felhőmappát (OneDrive, Dropbox). Minden kész fájl azonnal oda kerül, esemény és típus szerint rendezve (nyomatok, eredetik, GIF-ek, videók – külön-külön kikapcsolhatók). Ha a meghajtó rövid ideig hiányzik, a box később pótolja a fájlokat. Ha egy vendég a boxnál törli a munkamenetét, a másolatok is eltűnnek.

Indítás távirányítóval

Ugyanezen a lapon az Indítás távirányítóval pontban tanítasz be egy gombot. A prezenterek, USB-gombok és lábkapcsolók általában szóközt küldenek; ez az alapbeállítás. Az Indítja mezőben választod ki, mit indítson a gomb a kezdőképernyőn: a Mint az érintés (normál folyamat) lehetőséget vagy rögtön egy módot, például a 360°-ot a platformon. A BoothDock Studio 1.4.0-s és korábbi verzióiban a gomb csak a 360°-hoz létezik, lásd: 360° / Lassítás.

Hibaelhárítás

Semmi sem történik: van valami a naplóban? A webhookok a webhooks.log (1.4.0-ig: ausloeser.log), az API a lokale-api.log fájlba ír – mindkettő a %LocalAppData%\Boothdock Studio\logs mappában van. Az elutasított kérések (hibás jelszó, idegen eszköz) ott legfeljebb percenként egyszer jelennek meg.
„Invalid password." – másold ki újra a jelszót; az Új jelszó után a régi már nem érvényes.
„The booth is not on the start screen …" – a start csak a kezdőképernyőről működik. Előbb cancel, aztán start.
„Too many failed attempts …" – az eszköz túl sokszor küldött hibás jelszót. Várj 15 percet, és ellenőrizd a jelszót.
A telefon nem éri el a boxot, a számítógépen minden működik: szinte mindig a Windows tűzfal vagy egy nyilvánosként kezelt Wi-Fi az oka – lásd fent. Mindkét esetet jelzi az állapotsor.