← Visi straipsniai

BoothDock · Wiki

Webhooks ir API

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 veikia Windows sistemoje, o nuo 1.5.10 versijos – ir iPad, iPhone bei Mac. Vietinė API nuo 1.4.0 versijos veikia ir iPad, iPhone bei Mac įrenginiuose, eksportas realiuoju laiku – nuo 1.5.2 versijos.

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
Sistema → Automatizavimas: eksportas realiuoju laiku, webhooks ir vietinė API

Webhooks nustatymas

Užpildyk lauką Adresas (URL), Windows sistemoje ir lauką Programa – arba abu. Įvykus kiekvienam įvykiui dėžė iškviečia viską, kas užpildyta:

  • Programa (tik Windows) – .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.

iPad, iPhone ir Mac yra tik adresas. Ten http:// veikia tik vietiniame tinkle (IP adresas arba .local) – taigi Shelly, WLED ir Tasmota „Wi-Fi“ tinkle veikia. Adresams internete reikia https://.

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.

Atskiras adresas kiekvienam įvykiui

Nuo 1.5.10 versijos skiltyje Atskiras adresas kiekvienam įvykiui (neprivaloma) gali papildomai kiekvienam įvykiui nurodyti atskirą adresą – pavyzdžiui, „Wi-Fi“ tinkle esančiam Shelly lizdui, WLED ar Tasmota, kurie įsijungia per atgalinį skaičiavimą ar fotografavimą. Pavyzdys countdown_start: http://192.168.1.50/relay/0?turn=on.

Dėžė iškviečia šį adresą papildomai prie aukščiau nurodytos programos ir adreso, kaip paprastą GET be pridėtų reikšmių. Ankstesnis adresas ir esami scenarijai veikia nepakitę. countdown ateina kas sekundę; per file_upload dėžė atskirą adresą iškviečia vieną kartą per sesiją (bendrą adresą – kaip ir anksčiau, kiekvienam failui).

Įvykiai

ĮvykisKadaParametrai
session_startSvečias pradeda sesiją, režimas nustatytas1: režimas (PrintOnly, PrintAndGIF, OnlyGIF, SlowMoOr360, Video), 2: BoothDock režimas (photo, gif, boomerang, video, slowmo, ai)
countdown_startPrasideda atgalinė atskaita1: sekundės
countdownKiekviena atgalinės atskaitos sekundė1: eiga procentais (nuo 0)
capture_startAtgalinė atskaita baigėsi, prasideda fotografavimas–
file_downloadKamera išsaugojo nuotrauką1: failo pavadinimas, 2: visas kelias
processing_startPrasideda apdorojimaskiekvienam kameros originalui po failo pavadinimą, paskutinė reikšmė – spausdinimo failas (šiuo metu tuščia)
sharing_screenPasirodo rezultato ekranas (kartą per sesiją)–
printingLapas siunčiamas į spausdintuvą1: failas (šiuo metu tuščia), 2: kopijos, 3: spausdintuvas
file_uploadFailas pasiekė Hub'ą (kiekvienam failui)1: kelias dėžėje, 2: galerijos nuoroda, 3: tipas (print, photo, original, animation, boomerang, video), 4: albumas (renginio pavadinimas)
lead_submittedSvečias išsiuntė formą Svečių duomenys (forma) (nuo 1.5.0)– (patys atsakymai yra tik CSV eksporte)
session_endSesija 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

KomandaVeikimas
start?mode=printPradeda 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. Su šablonu, stiliumi ir fonu: žr. toliau.
auswahl?mode=printGrąžina Data, ką galima pasirinkti šiame režime: vorlagen (Id ir pavadinimas; tuščia, jei leidžiamas tik vienas šablonas – jis tada yra vorgabeVorlage), hintergruende kiekvienam šablonui ir režime ai – stile (nuo 1.5.13).
cancelNutraukia vykstančią sesiją ir grįžta į pradžios ekraną.
statusGrąžina Data: svečio režimas įjungtas/išjungtas, dabartinis ekranas, režimas, užrakinta taip/ne – nuo 1.5.13 taip pat sperrgrund (manuell arba zeitfenster) ir oeffnetUm.
print?count=1Dar kartą atspausdina paskutinį rezultatą (nuo 1 iki 10 lapų). Vaizdo įrašų spausdinti negalima.
lockscreen/showUžrakina dėžę su užrašu „Akimirką – tuoj tęsime." arba tavo paties tekstu ir paveikslėliu (žr. „Užrakinimo ekranas“ toliau). Administratoriaus kampas lieka pasiekiamas. Nuo 1.5.13 užraktas išlieka ir paleidus programėlę iš naujo.
lockscreen/exitPanaikina užraktą – nuo 1.5.13 ir laiko lango užraktą, iki kito pasikeitimo.
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/smsTokios 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. Tik ne svečių režime (nuo 1.5.4).
deletetestevent?eventId=…Ištrina bandomąjį renginį, sukurtą per API – niekada kitų renginių. Tik ne svečių režime (nuo 1.5.4).
pingBe slaptažodžio patikrina, ar API veikia.

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

Sesijos paleidimas su šablonu, stiliumi ir fonu

Nuo 1.5.13 versijos start iš karto priima pasirinkimą – dėžė tada praleidžia būtent šiuos pasirinkimo ekranus:

  • vorlage=<Id> (arba template=) – šablonas, tik režime print (foto). Id pateikia auswahl?mode=print.
  • stil=<Id> (arba style=) – DI stilius, tik režime ai.
  • hintergrund=<Id> (arba background=) – iškirpimo fonas, tinkantis šablonui.

Pavyzdys: http://localhost:1500/api/start?mode=print&vorlage=hochzeit-gold&hintergrund=strand&password=TAVO-SLAPTAŽODIS

Nežinomas arba netinkamas Id nepaleidžia sesijos: IsSuccessful yra false, ErrorMessage nurodo priežastį. Sutikimą dėl duomenų apsaugos ir svečių duomenų formą dėžė ir toliau rodo pati – jie skirti svečiui prie dėžės ir jų negalima atlikti iš anksto per API.

Užrakinimo ekranas

Skiltyje Renginiai → Užrakinimo ekranas (nuo 1.5.13) nustatai, ką rodo užrakinta dėžė: savo tekstą, savo paveikslėlį ir – esant laiko langui – didelę atgalinę atskaitą iki atidarymo.

  • Laiko langas kiekvienam renginiui: Su Atsidaro ir Užsidaro dėžė užrakinta prieš pradžią ir po pabaigos.
  • Atrakinimas įrenginyje: Jei nustatytas operatoriaus PIN (Sistema → Apsauga), užrakinimo ekrane rodoma maža spyna. Kas žino PIN, atrakina dėžę. Atrakinta prieš pradžią, ji lieka atidaryta iki pabaigos.
  • Nuotoliniu būdu: Hub'e po Kabinos užrakini ir atrakini kiekvieną dėžę, kuri tai palaiko (Studio nuo 1.5.13). Tą patį gali padaryti per BoothDock Station ir su lockscreen/show / lockscreen/exit.

Vykstančios sesijos nenutraukia nei užraktas iš Hub, nei laiko langas – dėžė užsirakina, kai tik svečias baigia.

Eksportas realiuoju laiku

Tame pačiame skirtuke: kiekvienas paruoštas failas iškart išsaugomas pačioje dėžėje (Vietinė kopija) – ir be Hub, surūšiuotas pagal renginį ir tipą (spaudiniai, originalai, GIF, vaizdo įrašai – kiekvieną galima išjungti atskirai). Ši kopija niekada netrinama automatiškai. Skiltyje USB atmintinė / antras aplankas pridedi antrą paskirties vietą: Automatiškai rašyti į USB atmintinę rašo į kiekvieną prijungtą atmintinę, Papildyti praleistus failus vėliau įrašo tai, kas atsirado be atmintinės. Arba nurodai Fiksuotas antras aplankas (turi pirmenybę), pavyzdžiui, debesies aplanką (OneDrive, Dropbox). Jei svečias ištrina savo sesiją prie dėžės, išnyksta ir kopijos. iPad ir iPhone įrenginiuose: Programoje „Failai“ skiltyje „Mano iPad › BoothDock Studio › Export“. BoothDock Studio 1.5.3 ir senesnėse versijose vietoj to yra tik Eksporto aplankas.

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

Kiti žingsniai