Webhooki in API - BoothDock Wiki

BoothDock Studio lahko druge programe obvešča o vsakem koraku seje (webhooki) in se pusti upravljati drugim programom (lokalni API). Oboje najdeš v skrbniškem območju pod Sistem → Avtomatizacija.

V BoothDock Studiu 1.4.0 in starejših različicah se webhooki tam še imenujejo »Sprožilci«.

Webhooki in izvoz v realnem času so na voljo samo v sistemu Windows. Lokalni API je od različice 1.4.0 na voljo tudi na iPadu in iPhonu.

Tipične uporabe: luči ali DMX, usklajeni z odštevanjem, prekrivni sloj za pretakanje, števec ob vhodu – ali Stream Deck kot daljinski upravljalnik za kabino.

Sistem → Avtomatizacija: izvoz v realnem času, webhooki in lokalni API

Nastavitev webhookov

Izpolni polje Program, polje Naslov (URL) ali obe. Ob vsakem dogodku kabina pokliče oboje:

Program – datoteka .exe, .bat ali .cmd. Klic: program <dogodek> <param1> <param2> …. Vsaka vrednost pride kot samostojen argument, tudi če vsebuje presledke. Program se zažene brez okna, v lastni mapi. Skript PowerShell (.ps1) zaženeš prek majhne datoteke .bat pred njim.
Naslov (URL) – http ali https, poklican z GET: https://tvoj-streznik/hook?event_type=<dogodek>&param1=…&param2=…. Vrednosti so kodirane za URL; parametri, ki so že v tvojem naslovu, ostanejo ohranjeni.

Seja nikoli ne čaka na tvoj webhook: program in klic tečeta vzporedno, en klic sme trajati največ 5 sekund. Pošlji preizkus takoj pošlje session_start – tako preveriš povezavo, ne da bi zagnal sejo.

Program in naslov je mogoče nastaviti samo neposredno na kabini, ne prek Huba: pot do programa pomeni pravico, da se na računalniku nekaj izvede.

Dogodki

Dogodek	Kdaj	Parametri
`session_start`	Gost zažene sejo, način je določen	1: način (`PrintOnly`, `PrintAndGIF`, `OnlyGIF`, `SlowMoOr360`, `Video`), 2: način BoothDock (`photo`, `gif`, `boomerang`, `video`, `slowmo`, `ai`)
`countdown_start`	Odštevanje se začne	1: sekunde
`countdown`	Vsaka sekunda odštevanja	1: napredek v odstotkih (od 0)
`capture_start`	Odštevanje je končano, zajem se začne	–
`file_download`	Fotoaparat je shranil fotografijo	1: ime datoteke, 2: polna pot
`processing_start`	Obdelava se začne	za vsak izvirnik fotoaparata eno ime datoteke, kot zadnja vrednost datoteka za tisk (trenutno prazna)
`sharing_screen`	Prikaže se zaslon z rezultatom (enkrat na sejo)	–
`printing`	List gre na tiskalnik	1: datoteka (trenutno prazna), 2: kopije, 3: tiskalnik
`file_upload`	Datoteka je prispela v Hub (za vsako datoteko)	1: pot na kabini, 2: povezava do galerije, 3: vrsta (`print`, `photo`, `original`, `animation`, `boomerang`, `video`), 4: album (ime dogodka)
`session_end`	Seja se konča – dokončana, preklicana, potekla ali izbrisana	–

Primer datoteke .bat, ki zapiše vsak dogodek: echo %DATE% %TIME% %* >> "%~dp0dogodki.log"

Lokalni API

Drugi programi upravljajo kabino prek HTTP – na primer Stream Deck, lasten skript ali 360° upravljanje na telefonu.

Vklop: Sistem → Avtomatizacija → Vklopi API. Privzeto je API izklopljen. Vrata 1500, nastavljiva.
Naslov: http://localhost:1500/api/<ukaz> (ali 127.0.0.1). Privzeto kabina sprejema zahteve samo s tega računalnika.
Geslo: 16 znakov, prikazano v istem razdelku – kopiraj ga ali ustvari novo. Pošlji ga kot ?password=…, kot glavo X-Api-Password ali kot Authorization: Bearer …. Brez njega deluje samo ping.
Odgovor: vedno HTTP 200 z JSON, na primer {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Ali je uspelo, piše v IsSuccessful, razlog za napako pa v ErrorMessage. Nekateri ukazi vrnejo še Data.

Celoten klic: http://localhost:1500/api/start?mode=print&password=TVOJE-GESLO

Upravljanje iz omrežja (telefon, tablica, 360°)

Dodatno vklopi Dosegljivo tudi iz omrežja. Potem kabina sprejema zahteve naprav v istem omrežju Wi-Fi/LAN – nikoli iz interneta.

Naslov za telefon: piše v vrstici stanja, na primer http://192.168.1.20:1500. Primer pod njo nato takoj pokaže pravi naslov.
Brez vnosa IP-ja: kabina se v omrežju sama oglasi (mDNS/Bonjour, vrsta storitve _boothdock._tcp, ime »BoothDock« in ime računalnika). Aplikacije, ki jo iščejo, jo najdejo samodejno.
Zaklep: če naprava v desetih minutah desetkrat pošlje napačno geslo, je za 15 minut zaklenjena. Računalnik same kabine ni nikoli zaklenjen.
Samo v lastnem omrežju: geslo potuje po omrežju nešifrirano. Omrežni način uporabljaj samo v lastnem, zaščitenem omrežju Wi-Fi – ne v odprtem omrežju Wi-Fi za goste na prizorišču.
Požarni zid: namestitev nastavi pravilo, samo za zasebna omrežja. Če vrstica stanja pokaže opozorilo požarnega zidu, znova namesti BoothDock Studio ali ga v sistemu Windows dovoli pod »Dovoli aplikacijo skozi požarni zid«. Če Windows omrežje Wi-Fi obravnava kot javno, naprave ne pridejo noter – v lastnostih omrežja nastavi profil na Zasebno.

Ukazi

Ukaz	Učinek
`start?mode=print`	Zažene sejo. Načini: `print` (fotografija), `gif`, `boomerang`, `slowmo` (360°; brez 360° boomerang), `video`, `ai`. Deluje samo z začetnega zaslona, samo z vklopljenim načinom in ne pri zaklenjeni kabini.
`cancel`	Prekliče trenutno sejo in se vrne na začetni zaslon.
`status`	V `Data` vrne: način za goste vklopljen/izklopljen, trenutni zaslon, način, zaklenjeno da/ne.
`print?count=1`	Še enkrat natisne zadnji rezultat (1 do 10 listov). Videov ni mogoče natisniti.
`lockscreen/show`	Zaklene kabino z besedilom »Trenutek – takoj nadaljujemo.« Skrbniški kot ostane dosegljiv.
`lockscreen/exit`	Odpravi zaklep.
`share/email?email=…`	Pošlje zadnji rezultat po e-pošti – potrebuje seznanitev s Hubom in dejanje pri rezultatu »Pošlji po e-pošti« (Sistem → Delovanje → Dejanja pri rezultatu (gost); do različice 1.4.0 stikalo »Fotografija po e-pošti (gost)« pod Oblikovanje → Zasloni).
`share/sms`	Ne obstaja; odgovor to pošteno pove (`IsSuccessful: false`).
`createtestevent?name=…`	Ustvari preizkusni dogodek in ga aktivira. `Data` vsebuje `eventId` in `eventName`. Brez imena dobi ime z datumom.
`deletetestevent?eventId=…`	Izbriše preizkusni dogodek, ustvarjen prek API-ja – drugih dogodkov nikoli.
`ping`	Brez gesla preveri, ali API teče.

Če kabina ne odgovori v 15 sekundah, se vrne IsSuccessful: false z opombo.

Izvoz v realnem času

Na istem zavihku v polju Mapa za izvoz izbereš cilj – na primer ključek USB ali mapo v oblaku (OneDrive, Dropbox). Vsaka dokončana datoteka pride tja takoj, razvrščena po dogodku in vrsti (Odtisi, Izvirniki, GIF-ji, Videoposnetki – vsako vrsto je mogoče izklopiti posebej). Če ključka za kratek čas ni, kabina datoteke prenese naknadno. Če gost na kabini izbriše svojo sejo, izginejo tudi kopije.

Zagon z daljinskim upravljalnikom

Na istem zavihku pod Zagon z daljinskim upravljalnikom naučiš tipko. Upravljalniki za predstavitve, gumbi USB in nožna stikala običajno pošljejo preslednico; ta je prednastavljena. Pri Zažene izbereš, kaj tipka sproži na začetnem zaslonu: Kot dotik (običajni potek) ali takoj način, na primer 360° na platformi. V BoothDock Studio 1.4.0 in starejših različicah je tipka na voljo samo za 360°, glej 360° / počasni posnetek.

Odpravljanje težav

Nič se ne zgodi: je kaj v dnevniku? Webhooki pišejo v webhooks.log (do različice 1.4.0: ausloeser.log), API v lokale-api.log – oba v mapi %LocalAppData%\Boothdock Studio\logs. Zavrnjene zahteve (napačno geslo, tuja naprava) so tam zapisane največ enkrat na minuto.
»Invalid password.« – geslo znova kopiraj; po kliku na Novo geslo staro ne velja več.
»The booth is not on the start screen …« – start deluje samo z začetnega zaslona. Najprej cancel, nato start.
»Too many failed attempts …« – naprava je prepogosto poslala napačno geslo. Počakaj 15 minut in preveri geslo.
Telefon ne doseže kabine, na računalniku vse deluje: skoraj vedno je kriv požarni zid sistema Windows ali omrežje Wi-Fi, ki ga Windows obravnava kot javno – glej zgoraj. Oba primera javi vrstica stanja.