← Vsi članki

BoothDock · Wiki

Webhooki in API

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 so na voljo v sistemu Windows, od različice 1.5.10 pa tudi na iPadu, iPhonu in Macu. Lokalni API je od različice 1.4.0 na voljo tudi na iPadu, iPhonu in Macu, izvoz v realnem času od različice 1.5.2.

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
Sistem → Avtomatizacija: izvoz v realnem času, webhooki in lokalni API

Nastavitev webhookov

Izpolni polje Naslov (URL), v sistemu Windows tudi polje Program – ali obe. Ob vsakem dogodku kabina pokliče vse, kar je izpolnjeno:

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

Na iPadu, iPhonu in Macu je samo naslov. Tam http:// deluje samo v lokalnem omrežju (naslov IP ali .local) – Shelly, WLED in Tasmota v omrežju Wi-Fi torej delujejo. Naslovi na internetu potrebujejo https://.

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.

Lasten naslov za vsak dogodek

Od različice 1.5.10 lahko pod Lasten naslov za vsak dogodek (neobvezno) vsakemu dogodku dodatno dodeliš lasten naslov – na primer za vtičnico Shelly, WLED ali Tasmota v omrežju Wi-Fi, ki preklopi ob odštevanju ali zajemu. Primer za countdown_start: http://192.168.1.50/relay/0?turn=on.

Kabina ta naslov pokliče poleg programa in naslova zgoraj, kot preprost GET brez dodanih vrednosti. Dosedanji naslov in obstoječi skripti delujejo nespremenjeno. countdown pride vsako sekundo; pri file_upload kabina lasten naslov pokliče enkrat na sejo (splošni naslov še naprej za vsako datoteko).

Dogodki

DogodekKdajParametri
session_startGost zažene sejo, način je določen1: način (PrintOnly, PrintAndGIF, OnlyGIF, SlowMoOr360, Video), 2: način BoothDock (photo, gif, boomerang, video, slowmo, ai)
countdown_startOdštevanje se začne1: sekunde
countdownVsaka sekunda odštevanja1: napredek v odstotkih (od 0)
capture_startOdštevanje je končano, zajem se začne–
file_downloadFotoaparat je shranil fotografijo1: ime datoteke, 2: polna pot
processing_startObdelava se začneza vsak izvirnik fotoaparata eno ime datoteke, kot zadnja vrednost datoteka za tisk (trenutno prazna)
sharing_screenPrikaže se zaslon z rezultatom (enkrat na sejo)–
printingList gre na tiskalnik1: datoteka (trenutno prazna), 2: kopije, 3: tiskalnik
file_uploadDatoteka 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)
lead_submittedGost je poslal obrazec Podatki gostov (obrazec) (od 1.5.0)– (sami odgovori so samo v izvozu CSV)
session_endSeja 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

UkazUčinek
start?mode=printZaž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. S predlogo, slogom in ozadjem: glej spodaj.
auswahl?mode=printV Data vrne, kaj je mogoče izbrati v tem načinu: vorlagen (Id in ime; prazno, če je odobrena samo ena predloga – ta je potem v vorgabeVorlage), hintergruende za vsako predlogo in v načinu ai še stile (od 1.5.13).
cancelPrekliče trenutno sejo in se vrne na začetni zaslon.
statusV Data vrne: način za goste vklopljen/izklopljen, trenutni zaslon, način, zaklenjeno da/ne – od 1.5.13 tudi sperrgrund (manuell ali zeitfenster) in oeffnetUm.
print?count=1Še enkrat natisne zadnji rezultat (1 do 10 listov). Videov ni mogoče natisniti.
lockscreen/showZaklene kabino z besedilom »Trenutek – takoj nadaljujemo.« ali s tvojim lastnim besedilom in sliko (glej »Zaklenjen zaslon« spodaj). Skrbniški kot ostane dosegljiv. Od 1.5.13 zaklep ostane tudi po ponovnem zagonu aplikacije.
lockscreen/exitOdpravi zaklep – od 1.5.13 tudi zaklep zaradi časovnega okna, do naslednje spremembe.
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/smsNe 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. Samo zunaj načina za goste (od 1.5.4).
deletetestevent?eventId=…Izbriše preizkusni dogodek, ustvarjen prek API-ja – drugih dogodkov nikoli. Samo zunaj načina za goste (od 1.5.4).
pingBrez gesla preveri, ali API teče.

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

Zagon seje s predlogo, slogom in ozadjem

Od različice 1.5.13 start izbiro prevzame takoj – kabina nato preskoči prav te zaslone za izbiro:

  • vorlage=<Id> (ali template=) – predloga, samo v načinu print (fotografija). Id-je vrne auswahl?mode=print.
  • stil=<Id> (ali style=) – slog UI, samo v načinu ai.
  • hintergrund=<Id> (ali background=) – ozadje izreza, ki se ujema s predlogo.

Primer: http://localhost:1500/api/start?mode=print&vorlage=hochzeit-gold&hintergrund=strand&password=TVOJE-GESLO

Neznan ali neustrezen Id ne zažene seje: IsSuccessful je false, ErrorMessage navede razlog. Soglasje za varstvo podatkov in obrazec s podatki gostov kabina še naprej prikaže sama – veljata za gosta pred kabino in ju ni mogoče vnaprej opraviti prek API-ja.

Zaklenjen zaslon

V Dogodki → Zaklenjen zaslon (od 1.5.13) določiš, kaj prikaže zaklenjena kabina: lastno besedilo, lastno sliko in – pri časovnem oknu – veliko odštevanje do odprtja.

  • Časovno okno za vsak dogodek: Z Odpre ob in Zapre ob je kabina pred začetkom in po koncu zaklenjena.
  • Odklep na napravi: Če je nastavljena PIN koda upravljavca (Sistem → Zaščita), zaklenjeni zaslon prikaže majhno ključavnico. Kdor pozna PIN, kabino odklene. Če je odklenjena pred začetkom, ostane odprta do konca.
  • Na daljavo: V Hubu pod Kabine zakleneš in odkleneš vsako kabino, ki to podpira (Studio od 1.5.13). Enako deluje prek BoothDock Station in z lockscreen/show / lockscreen/exit.

Seje, ki poteka, ne prekine niti zaklep iz Huba niti časovno okno – kabina se zaklene, takoj ko gost konča.

Izvoz v realnem času

Na istem zavihku: vsaka dokončana datoteka se takoj shrani na samo kabino (Lokalna kopija) – tudi brez Huba, razvrščena po dogodku in vrsti (odtisi, izvirniki, GIF-ji, videoposnetki – vsako vrsto je mogoče izklopiti posebej). Ta kopija se nikoli ne izbriše samodejno. Pod USB ključek / druga mapa dodaš drugi cilj: Samodejno zapisuj na USB ključek piše na vsak vstavljen ključek, Nadoknadi zamujene datoteke naknadno zapiše, kar je nastalo brez ključka. Lahko pa vneseš Fiksna druga mapa (ima prednost), na primer mapo v oblaku (OneDrive, Dropbox). Če gost na kabini izbriše svojo sejo, izginejo tudi kopije. Na iPadu in iPhonu: V aplikaciji Datoteke pod »Na mojem iPadu › BoothDock Studio › Export«. V BoothDock Studiu 1.5.3 in starejših je namesto tega le Mapa za izvoz.

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

Naslednji koraki