Webhookid ja API - BoothDock Wiki

BoothDock Studio oskab teisi programme seansi igast sammust teavitada (webhookid) ja lasta teistel programmidel end juhtida (kohalik API). Mõlemad leiad admin-alal rubriigis Süsteem → Automatiseerimine.

BoothDock Studio versioonis 1.4.0 ja vanemates on webhookide nimi seal veel „Päästikud“.

Webhookid ja reaalajas eksport on olemas ainult Windowsis. Kohalik API on alates versioonist 1.4.0 olemas ka iPadis ja iPhone'is.

Tüüpilised kasutusviisid: valgus või DMX tagasiloenduse rütmis, voo ülekate (stream overlay), loendur sissepääsu juures – või Stream Deck Boxi kaugjuhtimispuldina.

Süsteem → Automatiseerimine: reaalajas eksport, webhookid ja kohalik API

Webhookide seadistamine

Täida väli Programm, väli Aadress (URL) või mõlemad. Iga sündmuse korral kutsub Box välja mõlemad:

Programm – .exe, .bat või .cmd. Väljakutse: programm <sündmus> <param1> <param2> …. Iga väärtus saabub eraldi argumendina, ka siis, kui see sisaldab tühikuid. Programm käivitub ilma aknata, oma kaustas. PowerShelli skripti (.ps1) käivitad selle ette pandud väikese .bat-faili kaudu.
Aadress (URL) – http või https, kutsutakse välja GET-päringuga: https://sinu-server/hook?event_type=<sündmus>&param1=…&param2=…. Väärtused on URL-kodeeritud; parameetrid, mis on juba sinu aadressis, säilivad.

Seanss ei oota kunagi sinu webhooki: programm ja väljakutse jooksevad kõrvalt, üks väljakutse võib kesta kõige rohkem 5 sekundit. Saada test saadab kohe sündmuse session_start – nii kontrollid ühendust ilma seanssi alustamata.

Programmi ja aadressi saab seadistada ainult otse Boxi juures, mitte Hubi kaudu: programmitee on õigus arvutis midagi käivitada.

Sündmused

Sündmus	Millal	Parameetrid
`session_start`	Külaline alustab seanssi, režiim on valitud	1: režiim (`PrintOnly`, `PrintAndGIF`, `OnlyGIF`, `SlowMoOr360`, `Video`), 2: BoothDocki režiim (`photo`, `gif`, `boomerang`, `video`, `slowmo`, `ai`)
`countdown_start`	Tagasiloendus algab	1: sekundid
`countdown`	Tagasiloenduse iga sekund	1: edenemine protsentides (alates 0)
`capture_start`	Tagasiloendus on läbi, jäädvustus algab	–
`file_download`	Kaamera on foto salvestanud	1: failinimi, 2: täielik tee
`processing_start`	Töötlemine algab	iga kaamera originaali kohta üks failinimi, viimase väärtusena prindifail (praegu tühi)
`sharing_screen`	Tulemuskuva ilmub (üks kord seansi kohta)	–
`printing`	Leht läheb printerisse	1: fail (praegu tühi), 2: koopiad, 3: printer
`file_upload`	Fail on Hubi jõudnud (iga faili kohta)	1: tee Boxis, 2: galerii link, 3: tüüp (`print`, `photo`, `original`, `animation`, `boomerang`, `video`), 4: album (ürituse nimi)
`session_end`	Seanss lõpeb – valmis, katkestatud, aegunud või kustutatud	–

Näide .bat-failist, mis logib iga sündmuse: echo %DATE% %TIME% %* >> "%~dp0sundmused.log"

Kohalik API

Teised programmid juhivad Boxi HTTP kaudu – näiteks Stream Deck, oma skript või 360° juhtimine telefonist.

Sisselülitamine: Süsteem → Automatiseerimine → Lülita API sisse. Tehaseseadena on API väljas. Port 1500, muudetav.
Aadress: http://localhost:1500/api/<käsk> (või 127.0.0.1). Tehaseseadena võtab Box vastu ainult selle arvuti päringuid.
Parool: 16 märki, kuvatakse samas jaotises – kopeeri see või loo uus. Edasta kujul ?password=…, päisena X-Api-Password või kujul Authorization: Bearer …. Ainult ping töötab ilma.
Vastus: alati HTTP 200 koos JSON-iga, näiteks {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Kas see õnnestus, näitab IsSuccessful, vea korral on põhjus väljas ErrorMessage. Mõned käsud tagastavad lisaks Data.

Täielik väljakutse: http://localhost:1500/api/start?mode=print&password=SINU-PAROOL

Juhtimine võrgust (telefon, tahvelarvuti, 360°)

Lülita lisaks sisse Kättesaadav ka võrgust. Siis võtab Box vastu päringuid seadmetelt samas Wi-Fi-/LAN-võrgus – mitte kunagi internetist.

Aadress telefoni jaoks: on kirjas olekureal, näiteks http://192.168.1.20:1500. Selle all olev näide näitab siis kohe sobivat aadressi.
Ilma IP-d sisestamata: Box annab võrgus ise endast teada (mDNS/Bonjour, teenuse tüüp _boothdock._tcp, nimi „BoothDock" pluss arvuti nimi). Rakendused, mis seda otsivad, leiavad selle automaatselt.
Blokeering: kui seade saadab kümne minuti jooksul kümme korda vale parooli, blokeeritakse see 15 minutiks. Seda arvutit ennast ei blokeerita kunagi.
Ainult oma võrgus: parool liigub võrgus krüpteerimata. Kasuta võrgurežiimi ainult oma kaitstud Wi-Fi-võrgus – mitte toimumiskoha avatud külaliste Wi-Fi-võrgus.
Tulemüür: paigaldus seadistab loa, ainult privaatvõrkude jaoks. Kui olekureal on tulemüüri hoiatus, installi BoothDock Studio uuesti või luba see Windowsis jaotises „Rakenduse lubamine läbi tulemüüri". Kui Windows käsitleb Wi-Fi-võrku avalikuna, ei pääse seadmed sisse – vali võrgu atribuutides profiiliks Privaatvõrk.

Käsud

Käsk	Toime
`start?mode=print`	Alustab seanssi. Režiimid: `print` (foto), `gif`, `boomerang`, `slowmo` (360°; ilma 360°-ta boomerang), `video`, `ai`. Toimib ainult avakuvalt, ainult lubatud režiimiga ja mitte siis, kui Box on lukus.
`cancel`	Katkestab käimasoleva seansi ja naaseb avakuvale.
`status`	Tagastab väljas `Data`: külaliserežiim sees/väljas, praegune kuva, režiim, lukus jah/ei.
`print?count=1`	Prindib viimase tulemuse uuesti (1 kuni 10 lehte). Videoid printida ei saa.
`lockscreen/show`	Lukustab Boxi tekstiga „Üks hetk – kohe läheb edasi." Admin-nurk jääb kättesaadavaks.
`lockscreen/exit`	Tühistab lukustuse.
`share/email?email=…`	Saadab viimase tulemuse e-postiga – vajab Hubiga sidumist ja tulemuse toimingut „Saada e-mailiga“ (Süsteem → Töö → Tulemuse toimingud (külaline); kuni 1.4.0 lülitit „Foto e-postiga (külaline)“ rubriigis Kujundus → Ekraanid).
`share/sms`	Seda ei ole; vastus ütleb seda ausalt (`IsSuccessful: false`).
`createtestevent?name=…`	Loob testürituse ja teeb selle aktiivseks. `Data` sisaldab välju `eventId` ja `eventName`. Ilma nimeta saab üritus kuupäevaga nime.
`deletetestevent?eventId=…`	Kustutab API kaudu loodud testürituse – teisi üritusi mitte kunagi.
`ping`	Kontrollib ilma paroolita, kas API töötab.

Kui Box ei vasta 15 sekundi jooksul, tuleb tagasi IsSuccessful: false koos selgitusega.

Reaalajas eksport

Samal vahekaardil valid väljal Ekspordikaust sihtkoha – näiteks USB-mälupulga või pilvekausta (OneDrive, Dropbox). Iga valmis fail jõuab sinna kohe, sorteerituna ürituse ja tüübi järgi (prindid, originaalid, GIF-id, videod – igaühe saab eraldi välja lülitada). Kui mälupulk on korraks eemal, kopeerib Box failid hiljem järele. Kui külaline kustutab oma seansi Boxi juures, kaovad ka koopiad.

Käivitus puldiga

Samal vahekaardil määrad jaotises Käivitus puldiga klahvi. Esitluspuldid, USB-nupud ja jalglülitid saadavad tavaliselt tühikuklahvi; see on vaikimisi määratud. Väljal Käivitab valid, mida klahv avakuval käivitab: Nagu puudutus (tavaline voog) või kohe mõne režiimi, näiteks 360° platvormil. BoothDock Studio 1.4.0-s ja vanemates versioonides on klahv olemas ainult 360° jaoks, vaata 360° / Aegluup.

Probleemi lahendamine

Midagi ei juhtu: Kas logis on midagi? Webhookid kirjutavad faili webhooks.log (kuni 1.4.0: ausloeser.log), API faili lokale-api.log – mõlemad kaustas %LocalAppData%\Boothdock Studio\logs. Tagasilükatud päringud (vale parool, võõras seade) kirjutatakse sinna kõige rohkem kord minutis.
„Invalid password." – kopeeri parool uuesti; pärast nuppu Uus parool vana enam ei kehti.
„The booth is not on the start screen …" – start toimib ainult avakuvalt. Kõigepealt cancel, siis start.
„Too many failed attempts …" – seade on liiga tihti vale parooli saatnud. Oota 15 minutit ja kontrolli parooli.
Telefon ei jõua Boxini, arvutis töötab kõik: peaaegu alati on põhjus Windowsi tulemüüris või avalikuks märgitud Wi-Fi-võrgus – vt ülalt. Mõlemast juhtumist annab teada olekurida.