← Svi članci

BoothDock · Wiki

Webhookovi i API

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 postoje u sustavu Windows, a od verzije 1.5.10 i na iPadu, iPhoneu i Macu. Lokalni API od verzije 1.4.0 postoji i na iPadu, iPhoneu i Macu, izvoz u stvarnom vremenu od verzije 1.5.2.

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
Sustav → Automatizacija: izvoz u stvarnom vremenu, webhookovi i lokalni API

Postavljanje webhookova

Popuni polje Adresa (URL), u sustavu Windows i polje Program – ili oba. Kod svakog događaja box poziva sve što je upisano:

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

Na iPadu, iPhoneu i Macu postoji samo adresa. Tamo http:// radi samo u lokalnoj mreži (IP adresa ili .local) – Shelly, WLED i Tasmota na Wi-Fiju dakle rade. Adrese na internetu trebaju https://.

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.

Vlastita adresa po događaju

Od verzije 1.5.10 pod Vlastita adresa po događaju (neobavezno) možeš svakom događaju dodatno dati vlastitu adresu – na primjer za utičnicu Shelly, WLED ili Tasmota na Wi-Fiju koja se uključuje pri odbrojavanju ili snimanju. Primjer za countdown_start: http://192.168.1.50/relay/0?turn=on.

Box poziva ovu adresu uz program i adresu iznad, kao jednostavan GET bez dodanih vrijednosti. Dosadašnja adresa i postojeće skripte rade nepromijenjeno. countdown stiže svake sekunde; kod file_upload box poziva vlastitu adresu jednom po sesiji (opću adresu i dalje po datoteci).

Događaji

DogađajKadaParametri
session_startGost pokreće sesiju, način je određen1: način (PrintOnly, PrintAndGIF, OnlyGIF, SlowMoOr360, Video), 2: BoothDock način (photo, gif, boomerang, video, slowmo, ai)
countdown_startOdbrojavanje počinje1: sekunde
countdownSvaka sekunda odbrojavanja1: napredak u postocima (od 0)
capture_startOdbrojavanje je završilo, snimanje počinje–
file_downloadKamera je spremila fotografiju1: naziv datoteke, 2: puna putanja
processing_startObrada počinjepo jedan naziv datoteke za svaki izvornik s kamere, kao posljednja vrijednost datoteka za ispis (trenutačno prazna)
sharing_screenPojavljuje se zaslon s rezultatom (jednom po sesiji)–
printingList ide na pisač1: datoteka (trenutačno prazna), 2: kopije, 3: pisač
file_uploadDatoteka 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)
lead_submittedGost je poslao obrazac Podaci o gostima (obrazac) (od 1.5.0)– (sami odgovori nalaze se samo u CSV izvozu)
session_endSesija 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

NaredbaUčinak
start?mode=printPokreć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. S predloškom, stilom i pozadinom: vidi niže.
auswahl?mode=printVraća u Data što se u ovom načinu može odabrati: vorlagen (Id i naziv; prazno ako je odobren samo jedan predložak – on je tada u vorgabeVorlage), hintergruende po predlošku i u načinu ai stile (od 1.5.13).
cancelPrekida tekuću sesiju i vraća se na početni zaslon.
statusVraća u Data: način za goste uključen/isključen, trenutačni zaslon, način, zaključan da/ne – od 1.5.13 i sperrgrund (manuell ili zeitfenster) te oeffnetUm.
print?count=1Ponovno ispisuje posljednji rezultat (1 do 10 listova). Videozapisi se ne mogu ispisati.
lockscreen/showZaključava box porukom „Trenutak – odmah nastavljamo." ili tvojim vlastitim tekstom i slikom (vidi „Zaključani zaslon” niže). Admin kut ostaje dostupan. Od 1.5.13 zaključavanje ostaje i nakon ponovnog pokretanja aplikacije.
lockscreen/exitUkida zaključavanje – od 1.5.13 i zaključavanje vremenskim prozorom, do sljedeće promjene.
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/smsNe 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. Samo izvan načina za goste (od 1.5.4).
deletetestevent?eventId=…Briše testni event stvoren putem API-ja – nikada druge evente. Samo izvan načina za goste (od 1.5.4).
pingBez lozinke provjerava radi li API.

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

Pokretanje sesije s predloškom, stilom i pozadinom

Od verzije 1.5.13 start odmah prima odabir – box tada preskače upravo te zaslone za odabir:

  • vorlage=<Id> (ili template=) – predložak, samo u načinu print (fotografija). Id-ove daje auswahl?mode=print.
  • stil=<Id> (ili style=) – AI stil, samo u načinu ai.
  • hintergrund=<Id> (ili background=) – pozadina za izrezivanje, u skladu s predloškom.

Primjer: http://localhost:1500/api/start?mode=print&vorlage=hochzeit-gold&hintergrund=strand&password=TVOJA-LOZINKA

Nepoznat ili neodgovarajući Id ne pokreće sesiju: IsSuccessful je false, a ErrorMessage navodi razlog. Privolu za zaštitu podataka i obrazac s podacima gostiju box i dalje prikazuje sam – odnose se na gosta ispred boxa i ne mogu se unaprijed riješiti putem API-ja.

Zaključani zaslon

Pod Događaji → Zaključani zaslon (od 1.5.13) određuješ što prikazuje zaključan box: vlastiti tekst, vlastitu sliku i – kod vremenskog prozora – veliko odbrojavanje do otvaranja.

  • Vremenski prozor po događaju: S Otvara se u i Zatvara se u box je zaključan prije početka i nakon završetka.
  • Otključavanje na uređaju: Ako je postavljen PIN operatera (Sustav → Zaštita), zaslon zaključavanja prikazuje mali lokot. Tko zna PIN, otključava box. Ako je otključan prije početka, ostaje otvoren do kraja.
  • Na daljinu: U Hubu pod Kabine zaključavaš i otključavaš svaki box koji to podržava (Studio od 1.5.13). Isto radi preko BoothDock Stationa i s lockscreen/show / lockscreen/exit.

Sesiju u tijeku ne prekida ni zaključavanje iz Huba ni vremenski prozor – box se zaključava čim gost završi.

Izvoz u stvarnom vremenu

Na istoj kartici: svaka gotova datoteka odmah se sprema na sam box (Lokalna kopija) – i bez Huba, razvrstana po eventu i vrsti (ispisi, izvornici, GIF-ovi, videozapisi – svaka se vrsta može zasebno isključiti). Ta se kopija nikad ne briše automatski. Pod USB stick / druga mapa dodaješ drugo odredište: Automatski zapisuj na USB stick zapisuje na svaki umetnuti stick, Nadoknadi propuštene datoteke naknadno zapisuje ono što je nastalo bez sticka. Umjesto toga možeš unijeti Fiksna druga mapa (ima prednost), npr. mapu u oblaku (OneDrive, Dropbox). Ako gost izbriše svoju sesiju na boxu, nestaju i kopije. Na iPadu i iPhoneu: U aplikaciji Datoteke pod „Na mom iPadu › BoothDock Studio › Export”. U BoothDock Studiju 1.5.3 i starijem umjesto toga postoji samo Mapa za izvoz.

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

Sljedeći koraci