Webhooks ir API - BoothDock Wiki

BoothDock Studio gali pranešti kitoms programoms apie kiekvieną sesijos žingsnį (Webhooks) ir leisti kitoms programoms save valdyti (vietinė API). Abi funkcijas rasi administravimo srityje po Sistema → Automatizavimas.

BoothDock Studio 1.4.0 ir senesnėse versijose webhooks ten dar vadinasi „Paleidikliai“.

Webhooks ir eksportas realiuoju laiku veikia tik Windows sistemoje. Vietinė API nuo 1.4.0 versijos veikia ir iPad bei iPhone įrenginiuose.

Tipiniai panaudojimo atvejai: šviesa arba DMX pagal atgalinę atskaitą, transliacijos perdanga, skaitiklis prie įėjimo – arba Stream Deck kaip dėžės nuotolinio valdymo pultas.

Sistema → Automatizavimas: eksportas realiuoju laiku, webhooks ir vietinė API

Webhooks nustatymas

Užpildyk lauką Programa, Adresas (URL) arba abu. Įvykus kiekvienam įvykiui dėžė iškviečia abu:

Programa – .exe, .bat arba .cmd failas. Iškvietimas: programa <įvykis> <param1> <param2> …. Kiekviena reikšmė perduodama kaip atskiras argumentas, net jei joje yra tarpų. Programa paleidžiama be lango, savo aplanke. PowerShell scenarijų (.ps1) paleisk per nedidelį .bat failą, kuris jį iškviečia.
Adresas (URL) – http arba https, iškviečiamas GET užklausa: https://tavo-serveris/hook?event_type=<įvykis>&param1=…&param2=…. Reikšmės yra URL koduotos; parametrai, kurie jau yra tavo adrese, išlieka.

Sesija niekada nelaukia, kol suveiks tavo webhooks: programa ir iškvietimas vyksta lygiagrečiai, vienas iškvietimas gali trukti ne ilgiau kaip 5 sekundes. Siųsti bandymą iš karto išsiunčia session_start – taip patikrini ryšį nepradėdamas sesijos.

Programą ir adresą galima nustatyti tik tiesiogiai prie dėžės, ne per Hub'ą: programos kelias suteikia teisę ką nors vykdyti kompiuteryje.

Įvykiai

Įvykis	Kada	Parametrai
`session_start`	Svečias pradeda sesiją, režimas nustatytas	1: režimas (`PrintOnly`, `PrintAndGIF`, `OnlyGIF`, `SlowMoOr360`, `Video`), 2: BoothDock režimas (`photo`, `gif`, `boomerang`, `video`, `slowmo`, `ai`)
`countdown_start`	Prasideda atgalinė atskaita	1: sekundės
`countdown`	Kiekviena atgalinės atskaitos sekundė	1: eiga procentais (nuo 0)
`capture_start`	Atgalinė atskaita baigėsi, prasideda fotografavimas	–
`file_download`	Kamera išsaugojo nuotrauką	1: failo pavadinimas, 2: visas kelias
`processing_start`	Prasideda apdorojimas	kiekvienam kameros originalui po failo pavadinimą, paskutinė reikšmė – spausdinimo failas (šiuo metu tuščia)
`sharing_screen`	Pasirodo rezultato ekranas (kartą per sesiją)	–
`printing`	Lapas siunčiamas į spausdintuvą	1: failas (šiuo metu tuščia), 2: kopijos, 3: spausdintuvas
`file_upload`	Failas pasiekė Hub'ą (kiekvienam failui)	1: kelias dėžėje, 2: galerijos nuoroda, 3: tipas (`print`, `photo`, `original`, `animation`, `boomerang`, `video`), 4: albumas (renginio pavadinimas)
`session_end`	Sesija baigiasi – užbaigta, nutraukta, pasibaigusi arba ištrinta	–

.bat failo, kuris užrašo kiekvieną įvykį, pavyzdys: echo %DATE% %TIME% %* >> "%~dp0ivykiai.log"

Vietinė API

Kitos programos valdo dėžę per HTTP – pavyzdžiui, Stream Deck, tavo paties scenarijus arba 360° valdymas telefone.

Įjungimas: Sistema → Automatizavimas → Įjungti API. Gamykliškai API išjungta. Prievadas 1500, galima keisti.
Adresas: http://localhost:1500/api/<komanda> (arba 127.0.0.1). Gamykliškai dėžė priima užklausas tik iš šio kompiuterio.
Slaptažodis: 16 simbolių, rodomas tame pačiame skyriuje – nukopijuok arba sugeneruok naują. Perduok kaip ?password=…, kaip antraštę X-Api-Password arba kaip Authorization: Bearer …. Tik ping veikia be jo.
Atsakymas: visada HTTP 200 su JSON, pavyzdžiui, {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Ar pavyko, nurodo IsSuccessful, klaidos priežastį – ErrorMessage. Kai kurios komandos papildomai grąžina Data.

Pilnas iškvietimas: http://localhost:1500/api/start?mode=print&password=TAVO-SLAPTAŽODIS

Valdymas iš tinklo (telefonas, planšetė, 360°)

Papildomai įjunk Pasiekiama ir iš tinklo. Tada dėžė priima užklausas iš įrenginių tame pačiame Wi-Fi/LAN tinkle – niekada iš interneto.

Adresas telefonui: nurodytas būsenos eilutėje, pavyzdžiui, http://192.168.1.20:1500. Žemiau esantis pavyzdys tada iškart rodo tinkamą adresą.
Be IP įvedimo: dėžė pati praneša apie save tinkle (mDNS/Bonjour, paslaugos tipas _boothdock._tcp, pavadinimas „BoothDock" ir kompiuterio pavadinimas). Programėlės, kurios jos ieško, randa ją automatiškai.
Blokavimas: jei įrenginys per dešimt minučių dešimt kartų atsiunčia neteisingą slaptažodį, jis užblokuojamas 15 minučių. Pats šis kompiuteris niekada neužblokuojamas.
Tik savo tinkle: slaptažodis tinklu keliauja nešifruotas. Tinklo režimą naudok tik savo apsaugotame Wi-Fi tinkle – ne atvirame renginio vietos svečių Wi-Fi.
Užkarda: diegimo programa sukuria leidimą, tik privatiems tinklams. Jei būsenos eilutėje rodomas užkardos įspėjimas, iš naujo įdiek BoothDock Studio arba leisk jį sistemoje Windows skiltyje „Leisti programėlę per užkardą". Jei Windows Wi-Fi tinklą laiko viešuoju, įrenginiai neprisijungia – tinklo ypatybėse nustatyk profilį Privatusis.

Komandos

Komanda	Veikimas
`start?mode=print`	Pradeda sesiją. Režimai: `print` (foto), `gif`, `boomerang`, `slowmo` (360°; be 360° – boomerang), `video`, `ai`. Veikia tik iš pradžios ekrano, tik su įjungtu režimu ir ne tada, kai dėžė užrakinta.
`cancel`	Nutraukia vykstančią sesiją ir grįžta į pradžios ekraną.
`status`	Grąžina `Data`: svečio režimas įjungtas/išjungtas, dabartinis ekranas, režimas, užrakinta taip/ne.
`print?count=1`	Dar kartą atspausdina paskutinį rezultatą (nuo 1 iki 10 lapų). Vaizdo įrašų spausdinti negalima.
`lockscreen/show`	Užrakina dėžę su užrašu „Akimirką – tuoj tęsime." Administratoriaus kampas lieka pasiekiamas.
`lockscreen/exit`	Panaikina užraktą.
`share/email?email=…`	Išsiunčia paskutinį rezultatą el. paštu – reikia susiejimo su Hub'u ir rezultato veiksmo „Gauti el. paštu“ (Sistema → Veikimas → Rezultato veiksmai (svečiui); iki 1.4.0 – jungiklio „Nuotrauka el. paštu (svečiui)“ po Dizainas → Ekranai).
`share/sms`	Tokios komandos nėra; atsakymas tai sąžiningai pasako (`IsSuccessful: false`).
`createtestevent?name=…`	Sukuria bandomąjį renginį ir padaro jį aktyvų. `Data` lauke yra `eventId` ir `eventName`. Be pavadinimo renginys gauna pavadinimą su data.
`deletetestevent?eventId=…`	Ištrina bandomąjį renginį, sukurtą per API – niekada kitų renginių.
`ping`	Be slaptažodžio patikrina, ar API veikia.

Jei dėžė neatsako per 15 sekundžių, grąžinamas IsSuccessful: false su paaiškinimu.

Eksportas realiuoju laiku

Tame pačiame skirtuke lauke Eksporto aplankas pasirenki aplanką – pavyzdžiui, USB atmintinę arba debesies aplanką (OneDrive, Dropbox). Kiekvienas paruoštas failas iškart patenka ten, surūšiuotas pagal renginį ir tipą (spaudiniai, originalai, GIF, vaizdo įrašai – kiekvieną galima išjungti atskirai). Jei atmintinės trumpam nėra, dėžė failus nukopijuoja vėliau. Jei svečias ištrina savo sesiją prie dėžės, išnyksta ir kopijos.

Paleidimas nuotolinio valdymo pultu

Tame pačiame skirtuke skiltyje Paleidimas nuotolinio valdymo pultu priskiri mygtuką. Pristatymų pultai, USB mygtukai ir kojiniai jungikliai dažniausiai siunčia tarpo klavišą; jis nustatytas iš anksto. Lauke Paleidžia pasirenki, ką mygtukas paleidžia pradžios ekrane: Kaip palietus (įprasta eiga) arba iškart konkretų režimą, pavyzdžiui, 360° ant platformos. BoothDock Studio 1.4.0 ir senesnėse versijose mygtukas yra tik 360° režimui, žr. 360° / Sulėtinimas.

Problemų sprendimas

Nieko nevyksta: ar žurnale kas nors įrašyta? Webhooks rašo į webhooks.log (iki 1.4.0: ausloeser.log), API – į lokale-api.log, abu aplanke %LocalAppData%\Boothdock Studio\logs. Atmestos užklausos (neteisingas slaptažodis, svetimas įrenginys) ten įrašomos ne dažniau kaip kartą per minutę.
„Invalid password." – iš naujo nukopijuok slaptažodį; paspaudus Naujas slaptažodis senasis nebegalioja.
„The booth is not on the start screen …" – start veikia tik iš pradžios ekrano. Pirma cancel, tada start.
„Too many failed attempts …" – įrenginys per dažnai siuntė neteisingą slaptažodį. Palauk 15 minučių, patikrink slaptažodį.
Telefonas nepasiekia dėžės, o kompiuteryje viskas veikia: beveik visada kalta Windows užkarda arba viešuoju laikomas Wi-Fi tinklas – žr. aukščiau. Abu atvejus praneša būsenos eilutė.