Webhooki i API - BoothDock Wiki

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 i eksport w czasie rzeczywistym są dostępne tylko w systemie Windows. Lokalne API od wersji 1.4.0 działa także na iPadzie i iPhonie.

Typowe zastosowania: światło lub DMX zsynchronizowane z odliczaniem, nakładka do streamu, licznik przy wejściu – albo Stream Deck jako pilot do Boxa.

System → Automatyzacja: eksport w czasie rzeczywistym, webhooki i lokalne API

Konfiguracja webhooków

Wpisz Program, Adres (URL) lub oba. Przy każdym zdarzeniu Box wywołuje oba:

Program – plik .exe, .bat lub .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) – http lub https, wywoływany metodą GET: https://twój-serwer/hook?event_type=<zdarzenie>&param1=…&param2=…. Wartości są zakodowane w formacie URL; parametry, które już są w Twoim adresie, zostają zachowane.

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.

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)
`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> (lub 127.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łówek X-Api-Password lub jako Authorization: Bearer …. Tylko ping działa bez hasła.
Odpowiedź: zawsze HTTP 200 z JSON, na przykład {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Czy się udało, pokazuje IsSuccessful, przyczynę błędu – ErrorMessage. Niektóre polecenia zwracają dodatkowo Data.

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.
`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.
`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." Narożnik administratora pozostaje dostępny.
`lockscreen/exit`	Znosi blokadę.
`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ą.
`deletetestevent?eventId=…`	Usuwa event testowy utworzony przez API – nigdy inne eventy.
`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ą.

Eksport w czasie rzeczywistym

W tej samej zakładce wybierasz Folder eksportu – na przykład pendrive USB lub folder w chmurze (OneDrive, Dropbox). Każdy gotowy plik trafia tam od razu, posortowany według eventu i typu (wydruki, oryginały, GIF-y, filmy – każdy typ można wyłączyć osobno). Jeśli pendrive'a przez chwilę brakuje, Box później uzupełnia pliki. Jeśli gość usunie swoją sesję na Boxie, znikają również kopie.

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 do lokale-api.log – oba w folderze %LocalAppData%\Boothdock Studio\logs. 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 …" – start działa tylko z ekranu startowego. Najpierw cancel, potem start.
„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.