BoothDock Studio może informować inne programy o każdym kroku sesji (Webhooki) i pozwalać innym programom na sterowanie sobą (lokalne API). Obie funkcje znajdziesz w sekcji administratora pod System → Automatyzacja.
W BoothDock Studio 1.4.0 i starszych wersjach webhooki nadal nazywają się tam „Wyzwalacze”.
Webhooki są dostępne w systemie Windows, a od wersji 1.5.10 także na iPadzie, iPhonie i Macu. Lokalne API od wersji 1.4.0 działa także na iPadzie, iPhonie i Macu, eksport w czasie rzeczywistym od wersji 1.5.2.
Typowe zastosowania: światło lub DMX zsynchronizowane z odliczaniem, nakładka do streamu, licznik przy wejściu – albo Stream Deck jako pilot do Boxa.

Konfiguracja webhooków
Wpisz Adres (URL), w systemie Windows także Program – lub oba. Przy każdym zdarzeniu Box wywołuje wszystko, co jest wpisane:
- Program (tylko Windows) – plik
.exe,.batlub.cmd. Wywołanie:program <zdarzenie> <param1> <param2> …. Każda wartość trafia jako osobny argument, nawet jeśli zawiera spacje. Program uruchamia się bez okna, we własnym folderze. Skrypt PowerShell (.ps1) uruchamiasz przez mały plik.bat, który go wywołuje. - Adres (URL) –
httplubhttps, wywoływany metodą GET:https://twój-serwer/hook?event_type=<zdarzenie>¶m1=…¶m2=…. Wartości są zakodowane w formacie URL; parametry, które już są w Twoim adresie, zostają zachowane.
Na iPadzie, iPhonie i Macu jest tylko adres. Tam http:// działa tylko w sieci lokalnej (adres IP lub .local) – Shelly, WLED i Tasmota w sieci Wi-Fi działają więc bez problemu. Adresy w internecie wymagają https://.
Sesja nigdy nie czeka na Twój webhook: program i wywołanie działają równolegle, jedno wywołanie może trwać najwyżej 5 sekund. Wyślij test od razu wysyła session_start – w ten sposób sprawdzisz połączenie bez uruchamiania sesji.
Program i adres można ustawić tylko bezpośrednio na Boxie, nie przez Hub: ścieżka programu oznacza uprawnienie do uruchamiania czegoś na komputerze.
Własny adres dla każdego zdarzenia
Od wersji 1.5.10 w sekcji Własny adres dla każdego zdarzenia (opcjonalnie) możesz dodatkowo nadać każdemu zdarzeniu własny adres – na przykład dla gniazdka Shelly, WLED lub Tasmota w sieci Wi-Fi, które przełącza się przy odliczaniu lub przy zdjęciu. Przykład dla countdown_start: http://192.168.1.50/relay/0?turn=on.
Box wywołuje ten adres dodatkowo do programu i adresu powyżej, jako zwykłe GET bez dołączonych wartości. Dotychczasowy adres i istniejące skrypty działają bez zmian. countdown przychodzi co sekundę; przy file_upload Box wywołuje własny adres raz na sesję (adres ogólny nadal dla każdego pliku).
Zdarzenia
| Zdarzenie | Kiedy | Parametry |
|---|---|---|
session_start | Gość rozpoczyna sesję, tryb jest ustalony | 1: tryb (PrintOnly, PrintAndGIF, OnlyGIF, SlowMoOr360, Video), 2: tryb BoothDock (photo, gif, boomerang, video, slowmo, ai) |
countdown_start | Rozpoczyna się odliczanie | 1: sekundy |
countdown | Każda sekunda odliczania | 1: postęp w procentach (od 0) |
capture_start | Odliczanie dobiegło końca, rozpoczyna się nagrywanie lub zdjęcie | – |
file_download | Kamera zapisała zdjęcie | 1: nazwa pliku, 2: pełna ścieżka |
processing_start | Rozpoczyna się przetwarzanie | dla każdego oryginału z kamery nazwa pliku, jako ostatnia wartość plik do druku (obecnie pusty) |
sharing_screen | Pojawia się ekran wyniku (raz na sesję) | – |
printing | Arkusz trafia do drukarki | 1: plik (obecnie pusty), 2: kopie, 3: drukarka |
file_upload | Plik dotarł do Hub (dla każdego pliku) | 1: ścieżka na Boxie, 2: link do galerii, 3: typ (print, photo, original, animation, boomerang, video), 4: album (nazwa eventu) |
lead_submitted | Gość wysłał formularz Dane gości (formularz) (od 1.5.0) | – (same odpowiedzi są tylko w eksporcie CSV) |
session_end | Sesja się kończy – ukończona, przerwana, wygasła lub usunięta | – |
Przykład pliku .bat, który zapisuje każde zdarzenie: echo %DATE% %TIME% %* >> "%~dp0zdarzenia.log"
Lokalne API
Inne programy sterują Boxem przez HTTP – na przykład Stream Deck, własny skrypt albo sterowanie 360° na telefonie.
- Włączanie: System → Automatyzacja → Włącz API. Fabrycznie API jest wyłączone. Port 1500, można go zmienić.
- Adres:
http://localhost:1500/api/<polecenie>(lub127.0.0.1). Fabrycznie Box przyjmuje tylko żądania z tego komputera. - Hasło: 16 znaków, wyświetlane w tej samej sekcji – skopiuj je lub wygeneruj nowe. Przekazuj jako
?password=…, jako nagłówekX-Api-Passwordlub jakoAuthorization: Bearer …. Tylkopingdziała bez hasła. - Odpowiedź: zawsze HTTP 200 z JSON, na przykład
{"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Czy się udało, pokazujeIsSuccessful, przyczynę błędu –ErrorMessage. Niektóre polecenia zwracają dodatkowoData.
Pełne wywołanie: http://localhost:1500/api/start?mode=print&password=TWOJE-HASŁO
Sterowanie z sieci (telefon, tablet, 360°)
Włącz dodatkowo Dostępne także z sieci. Wtedy Box przyjmuje żądania od urządzeń w tej samej sieci Wi-Fi/LAN – nigdy z internetu.
- Adres dla telefonu: widnieje w wierszu stanu, na przykład
http://192.168.1.20:1500. Przykład poniżej od razu pokazuje wtedy właściwy adres. - Bez wpisywania IP: Box sam ogłasza się w sieci (mDNS/Bonjour, typ usługi
_boothdock._tcp, nazwa „BoothDock" plus nazwa komputera). Aplikacje, które go szukają, znajdują go automatycznie. - Blokada: jeśli urządzenie wyśle dziesięć razy w ciągu dziesięciu minut błędne hasło, zostaje zablokowane na 15 minut. Sam ten komputer nigdy nie jest blokowany.
- Tylko we własnej sieci: hasło przechodzi przez sieć niezaszyfrowane. Korzystaj z trybu sieciowego tylko we własnej, zabezpieczonej sieci Wi-Fi – nie w otwartej sieci Wi-Fi dla gości w miejscu imprezy.
- Zapora: instalacja tworzy regułę, tylko dla sieci prywatnych. Jeśli wiersz stanu pokazuje ostrzeżenie zapory, zainstaluj BoothDock Studio ponownie lub zezwól mu w systemie Windows w sekcji „Zezwalaj aplikacji na dostęp przez zaporę". Jeśli Windows traktuje sieć Wi-Fi jako publiczną, urządzenia nie mogą się połączyć – ustaw we właściwościach sieci profil Prywatna.
Polecenia
| Polecenie | Działanie |
|---|---|
start?mode=print | Rozpoczyna sesję. Tryby: print (zdjęcie), gif, boomerang, slowmo (360°; bez 360° boomerang), video, ai. Działa tylko z ekranu startowego, tylko z włączonym trybem i nie przy zablokowanym Boxie. Z szablonem, stylem i tłem: zobacz niżej. |
auswahl?mode=print | Zwraca w Data, co można wybrać w tym trybie: vorlagen (Id i nazwa; puste, jeśli udostępniony jest tylko jeden szablon – jest on wtedy w vorgabeVorlage), hintergruende dla każdego szablonu, a w trybie ai stile (od 1.5.13). |
cancel | Przerywa trwającą sesję i wraca do ekranu startowego. |
status | Zwraca w Data: tryb gościa wł./wył., bieżący ekran, tryb, zablokowany tak/nie – od 1.5.13 także sperrgrund (manuell lub zeitfenster) i oeffnetUm. |
print?count=1 | Drukuje ostatni wynik jeszcze raz (od 1 do 10 arkuszy). Filmów nie da się wydrukować. |
lockscreen/show | Blokuje Box komunikatem „Chwileczkę – zaraz wracamy." lub twoim własnym tekstem i obrazem (zobacz „Ekran blokady” niżej). Narożnik administratora pozostaje dostępny. Od 1.5.13 blokada utrzymuje się także po ponownym uruchomieniu aplikacji. |
lockscreen/exit | Znosi blokadę – od 1.5.13 także blokadę wynikającą z okna czasowego, do następnej zmiany. |
share/email?email=… | Wysyła ostatni wynik e-mailem – wymaga parowania z Hub i akcji wyniku „Otrzymaj przez e-mail” (System → Działanie → Akcje wyniku (gość); do wersji 1.4.0 przełącznika „Zdjęcie e-mailem (gość)” pod Projekt → Ekrany). |
share/sms | Nie istnieje; odpowiedź uczciwie to komunikuje (IsSuccessful: false). |
createtestevent?name=… | Tworzy event testowy i ustawia go jako aktywny. Data zawiera eventId i eventName. Bez nazwy event otrzymuje nazwę z datą. Tylko poza trybem gościa (od 1.5.4). |
deletetestevent?eventId=… | Usuwa event testowy utworzony przez API – nigdy inne eventy. Tylko poza trybem gościa (od 1.5.4). |
ping | Sprawdza bez hasła, czy API działa. |
Jeśli Box nie odpowie w ciągu 15 sekund, zwracane jest IsSuccessful: false z informacją.
Uruchamianie sesji z szablonem, stylem i tłem
Od wersji 1.5.13 start od razu przyjmuje wybór – Box pomija wtedy dokładnie te ekrany wyboru:
vorlage=<Id>(lubtemplate=) – szablon, tylko w trybieprint(zdjęcie). Id zwracaauswahl?mode=print.stil=<Id>(lubstyle=) – styl AI, tylko w trybieai.hintergrund=<Id>(lubbackground=) – tło do wycięcia, pasujące do szablonu.
Przykład: http://localhost:1500/api/start?mode=print&vorlage=hochzeit-gold&hintergrund=strand&password=TWOJE-HASŁO
Nieznane lub niepasujące Id nie uruchamia sesji: IsSuccessful ma wartość false, a ErrorMessage podaje przyczynę. Zgodę na ochronę danych i formularz danych gości Box nadal wyświetla sam – dotyczą one gościa przed Boxem i nie da się ich załatwić z góry przez API.
Ekran blokady
W Wydarzenia → Ekran blokady (od 1.5.13) ustalasz, co pokazuje zablokowany Box: własny tekst, własny obraz i – przy oknie czasowym – duże odliczanie do otwarcia.
- Okno czasowe dla każdego wydarzenia: Dzięki Otwiera o i Zamyka o Box jest zablokowany przed rozpoczęciem i po zakończeniu.
- Odblokowanie na urządzeniu: Jeśli ustawiono PIN operatora (System → Ochrona), ekran blokady pokazuje małą kłódkę. Kto zna PIN, odblokowuje Box. Odblokowany przed rozpoczęciem pozostaje otwarty do końca.
- Zdalnie: W Hub w sekcji Budki blokujesz i odblokowujesz każdy Box, który to obsługuje (Studio od 1.5.13). To samo działa przez BoothDock Station oraz poleceniami
lockscreen/show/lockscreen/exit.
Trwającej sesji nie przerywa ani blokada z Hub, ani okno czasowe – Box blokuje się, gdy tylko gość skończy.
Eksport w czasie rzeczywistym
W tej samej zakładce: każdy gotowy plik od razu zapisuje się na samym Boxie (Kopia lokalna) – także bez Huba, posortowany według eventu i typu (wydruki, oryginały, GIF-y, filmy – każdy typ można wyłączyć osobno). Ta kopia nigdy nie jest usuwana automatycznie. W Pendrive / drugi folder dodajesz drugi cel: Automatycznie zapisuj na pendrive zapisuje na każdym podłączonym pendrivie, Uzupełnij pominięte pliki dopisuje później to, co powstało bez pendrive'a. Możesz też podać Stały drugi folder (ma pierwszeństwo), np. folder w chmurze (OneDrive, Dropbox). Jeśli gość usunie swoją sesję na Boxie, znikają również kopie. Na iPadzie i iPhonie: W aplikacji Pliki w „Na moim iPadzie › BoothDock Studio › Export”. W BoothDock Studio 1.5.3 i starszych jest zamiast tego tylko Folder eksportu.
Start pilotem
W tej samej zakładce, w sekcji Start pilotem, przypisujesz klawisz. Prezentery, przyciski USB i przełączniki nożne zwykle wysyłają spację; jest ona ustawiona domyślnie. W polu Uruchamia wybierasz, co klawisz wywołuje na ekranie startowym: Jak dotknięcie (normalny przebieg) albo od razu tryb, na przykład 360° na platformie. W BoothDock Studio 1.4.0 i starszych wersjach klawisz jest dostępny tylko dla 360°, zob. 360° / zwolnione tempo.
Rozwiązywanie problemów
- Nic się nie dzieje: czy coś jest w dzienniku? Webhooki zapisują do
webhooks.log(do wersji 1.4.0:ausloeser.log), API dolokale-api.log– oba w folderze%LocalAppData%\Boothdock Studio\logs(Windows). Odrzucone żądania (błędne hasło, obce urządzenie) pojawiają się tam najwyżej raz na minutę. - „Invalid password." – skopiuj hasło ponownie; po Nowe hasło stare przestaje obowiązywać.
- „The booth is not on the start screen …" –
startdziała tylko z ekranu startowego. Najpierwcancel, potemstart. - „Too many failed attempts …" – urządzenie zbyt często wysyłało błędne hasło. Odczekaj 15 minut, sprawdź hasło.
- Telefon nie łączy się z Boxem, a na komputerze wszystko działa: prawie zawsze winna jest zapora systemu Windows lub sieć Wi-Fi traktowana jako publiczna – patrz wyżej. Oba przypadki zgłasza wiersz stanu.