← Összes cikk

BoothDock · Wiki

Webhookok és API

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 Windows alatt, a 1.5.10-es verziótól iPaden, iPhone-on és Macen is elérhetők. A helyi API az 1.4.0-s verziótól iPaden, iPhone-on és Macen is elérhető, a valós idejű exportálás az 1.5.2-es verziótól.

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
Rendszer → Automatizálás: valós idejű exportálás, webhookok és helyi API

Webhookok beállítása

Töltsd ki a Cím (URL) mezőt, Windows alatt a Program mezőt is – vagy mindkettőt. A box minden eseménynél meghív mindent, ami ki van töltve:

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

iPaden, iPhone-on és Macen csak a cím van. Ott a http:// csak a helyi hálózaton működik (IP-cím vagy .local) – a Wi-Fin lévő Shelly, WLED és Tasmota tehát működik. Az interneten lévő címekhez https:// kell.

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.

Saját cím eseményenként

A 1.5.10-es verziótól a Saját cím eseményenként (opcionális) résznél minden eseménynek adhatsz külön saját címet is – például egy Wi-Fin lévő Shelly konnektornak, WLED-nek vagy Tasmotának, amely a visszaszámlálásnál vagy a felvételnél kapcsol. Példa a countdown_start eseményre: http://192.168.1.50/relay/0?turn=on.

A box ezt a címet a fenti program és cím mellett hívja meg, egyszerű GET-ként, hozzáfűzött értékek nélkül. A korábbi cím és a meglévő szkriptek változatlanul működnek tovább. A countdown minden másodpercben érkezik; a file_upload eseménynél a box a saját címet munkamenetenként egyszer hívja meg (az általános címet továbbra is fájlonként).

Események

EseményMikorParaméterek
session_startEgy vendég munkamenetet indít, a mód eldőlt1: mód (PrintOnly, PrintAndGIF, OnlyGIF, SlowMoOr360, Video), 2: BoothDock-mód (photo, gif, boomerang, video, slowmo, ai)
countdown_startElindul a visszaszámlálás1: másodpercek
countdownA visszaszámlálás minden másodperce1: előrehaladás százalékban (0-tól)
capture_startA visszaszámlálás lejárt, a felvétel elindul–
file_downloadA kamera elmentett egy fotót1: fájlnév, 2: teljes elérési út
processing_startA feldolgozás elindulminden kamera-eredetihez egy fájlnév, utolsó értékként a nyomtatási fájl (jelenleg üres)
sharing_screenMegjelenik az eredményképernyő (munkamenetenként egyszer)–
printingEgy lap a nyomtatóra kerül1: fájl (jelenleg üres), 2: példányszám, 3: nyomtató
file_uploadEgy 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)
lead_submittedEgy vendég elküldte a Vendégadatok (űrlap) űrlapot (1.5.0-tól)– (maguk a válaszok csak a CSV-exportban vannak)
session_endA 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

ParancsHatás
start?mode=printMunkamenetet 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. Sablonnal, stílussal és háttérrel: lásd lent.
auswahl?mode=printA Data mezőben visszaadja, mit lehet ebben a módban választani: vorlagen (Id és név; üres, ha csak egy sablon engedélyezett – az ekkor a vorgabeVorlage mezőben van), hintergruende sablononként, és ai módban a stile (1.5.13-tól).
cancelMegszakítja a futó munkamenetet, és visszatér a kezdőképernyőre.
statusA Data mezőben visszaadja: vendégmód be/ki, aktuális képernyő, mód, zárolva igen/nem – 1.5.13-tól a sperrgrund (manuell vagy zeitfenster) és az oeffnetUm is.
print?count=1Újranyomtatja az utolsó eredményt (1–10 lap). Videókat nem lehet nyomtatni.
lockscreen/showZárolja a boxot ezzel a szöveggel: „Egy pillanat – mindjárt folytatjuk." vagy a saját szövegeddel és képeddel (lásd lent: „Zárolási képernyő”). Az admin-sarok elérhető marad. 1.5.13-tól a zárolás az alkalmazás újraindítása után is megmarad.
lockscreen/exitFeloldja a zárolást – 1.5.13-tól az időablak miatti zárolást is, a következő váltásig.
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/smsNem 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. Csak a vendégmódon kívül (1.5.4-től).
deletetestevent?eventId=…Törli az API-n keresztül létrehozott teszteseményt – más eseményeket soha. Csak a vendégmódon kívül (1.5.4-től).
pingJelszó 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.

Munkamenet indítása sablonnal, stílussal és háttérrel

Az 1.5.13-as verziótól a start azonnal átveszi a választást – a box ilyenkor pontosan ezeket a választóképernyőket ugorja át:

  • vorlage=<Id> (vagy template=) – a sablon, csak print (fotó) módban. Az Id-ket az auswahl?mode=print adja.
  • stil=<Id> (vagy style=) – az MI-stílus, csak ai módban.
  • hintergrund=<Id> (vagy background=) – a kivágás háttere, a sablonhoz illően.

Példa: http://localhost:1500/api/start?mode=print&vorlage=hochzeit-gold&hintergrund=strand&password=A-TE-JELSZAVAD

Ismeretlen vagy nem illő Id nem indít munkamenetet: az IsSuccessful értéke false, az ErrorMessage megnevezi az okot. Az adatvédelmi hozzájárulást és a vendégadat-űrlapot a box továbbra is maga jeleníti meg – ezek a box előtt álló vendégre vonatkoznak, és az API-n keresztül nem lehet előre elintézni őket.

Zárolási képernyő

Az Események → Zárolási képernyő alatt (1.5.13-tól) állítod be, mit mutat a zárolt box: saját szöveget, saját képet és – időablaknál – nagy visszaszámlálást a nyitásig.

  • Időablak eseményenként: A Nyit és a Zár beállítással a box a kezdés előtt és a befejezés után zárolva van.
  • Feloldás az eszközön: Ha be van állítva üzemeltetői PIN (Rendszer → Védelem), a zárolási képernyőn egy kis lakat jelenik meg. Aki ismeri a PIN-t, feloldja a boxot. Ha a kezdés előtt feloldják, a végéig nyitva marad.
  • Távolról: A Hub-ban a Boxok alatt minden olyan boxot zárolhatsz és feloldhatsz, amely ezt támogatja (Studio 1.5.13-tól). Ugyanez működik a BoothDock Stationön keresztül és a lockscreen/show / lockscreen/exit paranccsal is.

A folyamatban lévő munkamenetet sem a Hubból indított zárolás, sem az időablak nem szakítja meg – a box akkor zárol, amint a vendég végzett.

Valós idejű exportálás

Ugyanezen a lapon: minden kész fájl azonnal magára a boxra kerül (Helyi másolat) – Hub nélkül is, esemény és típus szerint rendezve (nyomatok, eredetik, GIF-ek, videók – külön-külön kikapcsolhatók). Ezt a másolatot a box soha nem törli automatikusan. Az USB-pendrive / második mappa alatt második célt adsz meg: az Automatikus írás USB-pendrive-ra minden bedugott pendrive-ra ír, a Kimaradt fájlok pótlása utólag kiírja, ami pendrive nélkül készült. Ehelyett megadhatsz egy Rögzített második mappa (elsőbbséget élvez) értéket is, például egy felhőmappát (OneDrive, Dropbox). Ha egy vendég a boxnál törli a munkamenetét, a másolatok is eltűnnek. iPaden és iPhone-on: A Fájlok appban: „Az iPademen › BoothDock Studio › Export”. A BoothDock Studio 1.5.3-as és régebbi verzióiban ehelyett csak az Exportmappa van.

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

Következő lépések