Webhookovi i API - BoothDock Wiki

BoothDock Studio može obavještavati druge programe o svakom koraku sesije (webhookovi) i dopustiti da njime upravljaju drugi programi (lokalni API). Oboje pronalaziš u Admin području pod Sustav → Automatizacija.

U BoothDock Studiju 1.4.0 i starijim verzijama webhookovi se ondje još zovu „Okidači“.

Webhookovi i izvoz u stvarnom vremenu postoje samo u sustavu Windows. Lokalni API od verzije 1.4.0 postoji i na iPadu i iPhoneu.

Tipične primjene: svjetlo ili DMX usklađeni s odbrojavanjem, overlay za stream, brojač na ulazu – ili Stream Deck kao daljinski upravljač za box.

Sustav → Automatizacija: izvoz u stvarnom vremenu, webhookovi i lokalni API

Postavljanje webhookova

Popuni polje Program, polje Adresa (URL) ili oba. Kod svakog događaja box poziva oboje:

Program – .exe, .bat ili .cmd. Poziv: program <događaj> <param1> <param2> …. Svaka vrijednost stiže kao zaseban argument, čak i ako sadrži razmake. Program se pokreće bez prozora, u vlastitoj mapi. PowerShell skriptu (.ps1) pokrećeš preko male .bat datoteke postavljene ispred nje.
Adresa (URL) – http ili https, poziva se putem GET-a: https://tvoj-poslužitelj/hook?event_type=<događaj>&param1=…&param2=…. Vrijednosti su URL-kodirane; parametri koji su već u tvojoj adresi ostaju sačuvani.

Sesija nikad ne čeka tvoj webhook: program i poziv rade usporedno, a jedan poziv smije trajati najviše 5 sekundi. Pošalji test odmah šalje session_start – tako provjeravaš vezu bez pokretanja sesije.

Program i adresa mogu se postaviti samo izravno na boxu, ne preko Huba: putanja programa pravo je da se nešto izvrši na računalu.

Događaji

Događaj	Kada	Parametri
`session_start`	Gost pokreće sesiju, način je određen	1: način (`PrintOnly`, `PrintAndGIF`, `OnlyGIF`, `SlowMoOr360`, `Video`), 2: BoothDock način (`photo`, `gif`, `boomerang`, `video`, `slowmo`, `ai`)
`countdown_start`	Odbrojavanje počinje	1: sekunde
`countdown`	Svaka sekunda odbrojavanja	1: napredak u postocima (od 0)
`capture_start`	Odbrojavanje je završilo, snimanje počinje	–
`file_download`	Kamera je spremila fotografiju	1: naziv datoteke, 2: puna putanja
`processing_start`	Obrada počinje	po jedan naziv datoteke za svaki izvornik s kamere, kao posljednja vrijednost datoteka za ispis (trenutačno prazna)
`sharing_screen`	Pojavljuje se zaslon s rezultatom (jednom po sesiji)	–
`printing`	List ide na pisač	1: datoteka (trenutačno prazna), 2: kopije, 3: pisač
`file_upload`	Datoteka je stigla u Hub (za svaku datoteku)	1: putanja na boxu, 2: poveznica na galeriju, 3: vrsta (`print`, `photo`, `original`, `animation`, `boomerang`, `video`), 4: album (naziv eventa)
`session_end`	Sesija završava – dovršena, prekinuta, istekla ili izbrisana	–

Primjer .bat datoteke koja bilježi svaki događaj: echo %DATE% %TIME% %* >> "%~dp0dogadaji.log"

Lokalni API

Drugi programi upravljaju boxom putem HTTP-a – primjerice Stream Deck, vlastita skripta ili 360° upravljanje s mobitela.

Uključivanje: Sustav → Automatizacija → Uključi API. Tvornički je API isključen. Port 1500, može se promijeniti.
Adresa: http://localhost:1500/api/<naredba> (ili 127.0.0.1). Tvornički box prihvaća samo zahtjeve s ovog računala.
Lozinka: 16 znakova, prikazana u istom odjeljku – kopiraj je ili generiraj novu. Prosljeđuje se kao ?password=…, kao zaglavlje X-Api-Password ili kao Authorization: Bearer …. Samo ping radi bez nje.
Odgovor: uvijek HTTP 200 s JSON-om, na primjer {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Je li uspjelo, piše u IsSuccessful, a razlog u slučaju pogreške u ErrorMessage. Neke naredbe dodatno vraćaju Data.

Potpuni poziv: http://localhost:1500/api/start?mode=print&password=TVOJA-LOZINKA

Upravljanje iz mreže (mobitel, tablet, 360°)

Dodatno uključi Dostupno i iz mreže. Tada box prihvaća zahtjeve uređaja u istoj Wi-Fi/LAN mreži – nikada s interneta.

Adresa za mobitel: piše u statusnom retku, na primjer http://192.168.1.20:1500. Primjer ispod tada odmah prikazuje odgovarajuću adresu.
Bez unosa IP adrese: box se sam najavljuje u mreži (mDNS/Bonjour, vrsta usluge _boothdock._tcp, naziv „BoothDock" plus naziv računala). Aplikacije koje ga traže pronalaze ga automatski.
Blokada: ako uređaj unutar deset minuta deset puta pošalje pogrešnu lozinku, blokira se na 15 minuta. Samo ovo računalo nikad se ne blokira.
Samo u vlastitoj mreži: lozinka putuje mrežom nešifrirano. Mrežni rad koristi samo u vlastitoj, zaštićenoj Wi-Fi mreži – ne u otvorenoj Wi-Fi mreži za goste na lokaciji.
Vatrozid: instalacija postavlja dopuštenje, samo za privatne mreže. Ako statusni redak prikazuje upozorenje vatrozida, ponovno instaliraj BoothDock Studio ili ga u sustavu Windows dopusti pod „Dopusti aplikaciju kroz vatrozid". Ako Windows Wi-Fi mrežu tretira kao javnu, uređaji ne mogu ući – u svojstvima mreže postavi profil na Privatna.

Naredbe

Naredba	Učinak
`start?mode=print`	Pokreće sesiju. Načini: `print` (fotografija), `gif`, `boomerang`, `slowmo` (360°; bez 360° boomerang), `video`, `ai`. Radi samo s početnog zaslona, samo s omogućenim načinom i ne kad je box zaključan.
`cancel`	Prekida tekuću sesiju i vraća se na početni zaslon.
`status`	Vraća u `Data`: način za goste uključen/isključen, trenutačni zaslon, način, zaključan da/ne.
`print?count=1`	Ponovno ispisuje posljednji rezultat (1 do 10 listova). Videozapisi se ne mogu ispisati.
`lockscreen/show`	Zaključava box porukom „Trenutak – odmah nastavljamo." Admin kut ostaje dostupan.
`lockscreen/exit`	Ukida zaključavanje.
`share/email?email=…`	Šalje posljednji rezultat e-poštom – potrebni su uparivanje s Hubom i radnja na rezultatu „Primi e-mailom“ (Sustav → Rad → Radnje na rezultatu (gost); do verzije 1.4.0 prekidač „Fotografija e-poštom (gost)“ pod Dizajn → Zasloni).
`share/sms`	Ne postoji; odgovor to iskreno kaže (`IsSuccessful: false`).
`createtestevent?name=…`	Stvara testni event i aktivira ga. `Data` sadrži `eventId` i `eventName`. Bez naziva dobiva naziv s datumom.
`deletetestevent?eventId=…`	Briše testni event stvoren putem API-ja – nikada druge evente.
`ping`	Bez lozinke provjerava radi li API.

Ako box ne odgovori u roku od 15 sekundi, vraća se IsSuccessful: false s napomenom.

Izvoz u stvarnom vremenu

Na istoj kartici u polju Mapa za izvoz biraš odredište – primjerice USB memoriju ili mapu u oblaku (OneDrive, Dropbox). Svaka gotova datoteka odmah stiže onamo, razvrstana po eventu i vrsti (ispisi, izvornici, GIF-ovi, videozapisi – svaka se vrsta može zasebno isključiti). Ako USB memorija nakratko nedostaje, box naknadno prenosi datoteke. Ako gost izbriše svoju sesiju na boxu, nestaju i kopije.

Pokretanje daljinskim upravljačem

Na istoj kartici pod Pokretanje daljinskim upravljačem dodjeljuješ tipku. Prezenteri, USB tipke i nožne sklopke obično šalju razmaknicu; ona je unaprijed postavljena. Pod Pokreće biraš što tipka aktivira na početnom zaslonu: Kao dodir (uobičajeni tijek) ili odmah određeni način, primjerice 360° na platformi. U verziji BoothDock Studio 1.4.0 i starijima tipka postoji samo za 360°, vidi 360° / Usporeno snimanje.

Rješavanje problema

Ništa se ne događa: ima li nešto u zapisniku? Webhookovi pišu u webhooks.log (do verzije 1.4.0: ausloeser.log), API u lokale-api.log – oboje u mapi %LocalAppData%\Boothdock Studio\logs. Odbijeni zahtjevi (pogrešna lozinka, strani uređaj) bilježe se ondje najviše jednom u minuti.
„Invalid password." – ponovno kopiraj lozinku; nakon Nova lozinka stara više ne vrijedi.
„The booth is not on the start screen …" – start radi samo s početnog zaslona. Najprije cancel, zatim start.
„Too many failed attempts …" – uređaj je prečesto poslao pogrešnu lozinku. Pričekaj 15 minuta i provjeri lozinku.
Mobitel ne dopire do boxa, a na računalu sve radi: gotovo uvijek je uzrok Windows vatrozid ili Wi-Fi mreža označena kao javna – vidi gore. Oba slučaja prijavljuje statusni redak.