← Visi raksti

BoothDock · Wiki

Webhooks un API

BoothDock Studio var informēt citas programmas par katru sesijas soli (Webhooks) un ļaut citām programmām sevi vadīt (lokālā API). Abas funkcijas atradīsi administrēšanas sadaļā Sistēma → Automatizācija.

BoothDock Studio 1.4.0 un vecākās versijās webhooks tur vēl saucas „Trigeri”.

Webhooks ir pieejami operētājsistēmā Windows un no versijas 1.5.10 arī iPad, iPhone un Mac. Lokālā API no versijas 1.4.0 ir pieejama arī iPad, iPhone un Mac ierīcēs, eksports reāllaikā – no versijas 1.5.2.

Tipiski lietojumi: gaisma vai DMX atbilstoši atskaitei, straumes pārklājums, skaitītājs pie ieejas – vai Stream Deck kā fotobokša tālvadības pults.

Sistēma → Automatizācija: eksports reāllaikā, webhooks un lokālā API
Sistēma → Automatizācija: eksports reāllaikā, webhooks un lokālā API

Webhooks iestatīšana

Aizpildi lauku Adrese (URL), operētājsistēmā Windows arī lauku Programma – vai abus. Pie katra notikuma fotobokss izsauc visu, kas ir aizpildīts:

  • Programma (tikai Windows) – .exe, .bat vai .cmd fails. Izsaukums: programma <notikums> <param1> <param2> …. Katra vērtība tiek nodota kā atsevišķs arguments, arī ja tajā ir atstarpes. Programma startē bez loga, savā mapē. PowerShell skriptu (.ps1) palaid caur nelielu .bat failu, kas to izsauc.
  • Adrese (URL) – http vai https, izsaukta ar GET: https://tavs-serveris/hook?event_type=<notikums>&param1=…&param2=…. Vērtības ir URL kodētas; parametri, kas jau ir tavā adresē, saglabājas.

iPad, iPhone un Mac ir tikai adrese. Tur http:// darbojas tikai lokālajā tīklā (IP adrese vai .local) – tātad Shelly, WLED un Tasmota Wi-Fi tīklā darbojas. Adresēm internetā vajag https://.

Sesija nekad negaida, kamēr nostrādās webhooks: programma un izsaukums darbojas paralēli, viens izsaukums drīkst ilgt ne vairāk kā 5 sekundes. Sūtīt testu uzreiz nosūta session_start – tā pārbaudi savienojumu, nesākot sesiju.

Programmu un adresi var iestatīt tikai tieši pie fotobokša, nevis caur Hub: programmas ceļš nozīmē tiesības kaut ko izpildīt datorā.

Atsevišķa adrese katram notikumam

No versijas 1.5.10 sadaļā Atsevišķa adrese katram notikumam (neobligāti) vari katram notikumam papildus norādīt savu adresi – piemēram, Wi-Fi tīkla Shelly kontaktligzdai, WLED vai Tasmota, kas ieslēdzas atpakaļskaitīšanas vai uzņemšanas brīdī. Piemērs notikumam countdown_start: http://192.168.1.50/relay/0?turn=on.

Fotobokss izsauc šo adresi papildus augstāk norādītajai programmai un adresei kā vienkāršu GET bez pievienotām vērtībām. Iepriekšējā adrese un esošie skripti turpina darboties bez izmaiņām. countdown pienāk katru sekundi; pie file_upload fotobokss savu adresi izsauc vienu reizi sesijā (vispārīgo adresi joprojām katram failam).

Notikumi

NotikumsKadParametri
session_startViesis sāk sesiju, režīms ir noteikts1: režīms (PrintOnly, PrintAndGIF, OnlyGIF, SlowMoOr360, Video), 2: BoothDock režīms (photo, gif, boomerang, video, slowmo, ai)
countdown_startSākas atskaite1: sekundes
countdownKatra atskaites sekunde1: progress procentos (no 0)
capture_startAtskaite beigusies, sākas uzņemšana–
file_downloadKamera ir saglabājusi fotoattēlu1: faila nosaukums, 2: pilns ceļš
processing_startSākas apstrādekatram kameras oriģinālam viens faila nosaukums, kā pēdējā vērtība – drukas fails (pašlaik tukšs)
sharing_screenParādās rezultāta ekrāns (vienreiz katrā sesijā)–
printingLapa tiek nosūtīta uz printeri1: fails (pašlaik tukšs), 2: kopijas, 3: printeris
file_uploadFails ir nonācis Hub (katram failam)1: ceļš fotoboksā, 2: galerijas saite, 3: tips (print, photo, original, animation, boomerang, video), 4: albums (pasākuma nosaukums)
lead_submittedViesis nosūtīja veidlapu Viesu dati (veidlapa) (no 1.5.0)– (pašas atbildes ir tikai CSV eksportā)
session_endSesija beidzas – pabeigta, atcelta, beigusies vai dzēsta–

Piemērs .bat failam, kas pieraksta katru notikumu: echo %DATE% %TIME% %* >> "%~dp0notikumi.log"

Lokālā API

Citas programmas vada fotoboksu caur HTTP – piemēram, Stream Deck, paša skripts vai 360° vadība telefonā.

  • Ieslēgšana: Sistēma → Automatizācija → Ieslēgt API. Rūpnīcas iestatījumos API ir izslēgta. Ports 1500, maināms.
  • Adrese: http://localhost:1500/api/<komanda> (vai 127.0.0.1). Rūpnīcas iestatījumos fotobokss pieņem pieprasījumus tikai no šī datora.
  • Parole: 16 rakstzīmes, redzama tajā pašā sadaļā – nokopē vai izveido jaunu. Nodod kā ?password=…, kā galveni X-Api-Password vai kā Authorization: Bearer …. Tikai ping darbojas bez tās.
  • Atbilde: vienmēr HTTP 200 ar JSON, piemēram, {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Vai izdevās, norāda IsSuccessful, kļūdas iemeslu – ErrorMessage. Dažas komandas papildus atgriež Data.

Pilns izsaukums: http://localhost:1500/api/start?mode=print&password=TAVA-PAROLE

Vadība no tīkla (telefons, planšete, 360°)

Papildus ieslēdz Pieejams arī no tīkla. Tad fotobokss pieņem pieprasījumus no ierīcēm tajā pašā Wi-Fi/LAN – nekad no interneta.

  • Adrese telefonam: redzama statusa rindā, piemēram, http://192.168.1.20:1500. Piemērs zem tās tad uzreiz rāda pareizo adresi.
  • Bez IP ievadīšanas: fotobokss pats piesakās tīklā (mDNS/Bonjour, pakalpojuma tips _boothdock._tcp, nosaukums "BoothDock" un datora nosaukums). Lietotnes, kas to meklē, atrod to automātiski.
  • Bloķēšana: ja ierīce desmit minūšu laikā desmit reizes nosūta nepareizu paroli, tā tiek bloķēta uz 15 minūtēm. Šis dators pats nekad netiek bloķēts.
  • Tikai savā tīklā: parole tīklā tiek pārsūtīta nešifrēta. Izmanto tīkla režīmu tikai savā aizsargātajā Wi-Fi – nevis norises vietas atvērtajā viesu Wi-Fi.
  • Ugunsmūris: instalēšana izveido atļauju, tikai privātajiem tīkliem. Ja statusa rindā redzams ugunsmūra brīdinājums, pārinstalē BoothDock Studio vai atļauj to sistēmā Windows sadaļā "Atļaut programmu caur ugunsmūri". Ja Windows Wi-Fi tīklu uzskata par publisku, ierīces netiek iekšā – tīkla rekvizītos iestati profilu Privāts.

Komandas

KomandaDarbība
start?mode=printSāk sesiju. Režīmi: print (foto), gif, boomerang, slowmo (360°; bez 360° – boomerang), video, ai. Darbojas tikai no sākuma ekrāna, tikai ar ieslēgtu režīmu un ne tad, ja fotobokss ir bloķēts. Ar veidni, stilu un fonu: skatīt zemāk.
auswahl?mode=printAtgriež Data, ko šajā režīmā var izvēlēties: vorlagen (Id un nosaukums; tukšs, ja atļauta tikai viena veidne – tā tad ir vorgabeVorlage), hintergruende katrai veidnei un režīmā ai – stile (no 1.5.13).
cancelAtceļ notiekošo sesiju un atgriežas sākuma ekrānā.
statusAtgriež Data: viesu režīms ieslēgts/izslēgts, pašreizējais ekrāns, režīms, bloķēts jā/nē – no 1.5.13 arī sperrgrund (manuell vai zeitfenster) un oeffnetUm.
print?count=1Vēlreiz izdrukā pēdējo rezultātu (no 1 līdz 10 lapām). Video nevar izdrukāt.
lockscreen/showBloķē fotoboksu ar uzrakstu "Mirklīti – tūlīt turpināsim." vai ar tavu paša tekstu un attēlu (skatīt „Bloķēšanas ekrāns” zemāk). Administratora stūris paliek pieejams. No 1.5.13 bloķēšana saglabājas arī pēc lietotnes restartēšanas.
lockscreen/exitAtceļ bloķēšanu – no 1.5.13 arī laika loga bloķēšanu, līdz nākamajai maiņai.
share/email?email=…Nosūta pēdējo rezultātu pa e-pastu – nepieciešama sapārošana ar Hub un rezultāta darbība „Saņemt pa e-pastu” (Sistēma → Darbība → Rezultāta darbības (viesim); līdz 1.4.0 – slēdzis „Fotoattēls pa e-pastu (viesim)” sadaļā Dizains → Ekrāni).
share/smsŠādas komandas nav; atbilde to godīgi pasaka (IsSuccessful: false).
createtestevent?name=…Izveido testa pasākumu un padara to aktīvu. Data satur eventId un eventName. Bez nosaukuma tiek piešķirts nosaukums ar datumu. Tikai ārpus viesu režīma (no 1.5.4).
deletetestevent?eventId=…Dzēš testa pasākumu, kas izveidots caur API – nekad citus pasākumus. Tikai ārpus viesu režīma (no 1.5.4).
pingBez paroles pārbauda, vai API darbojas.

Ja fotobokss neatbild 15 sekunžu laikā, tiek atgriezts IsSuccessful: false ar paskaidrojumu.

Sesijas sākšana ar veidni, stilu un fonu

Sākot ar versiju 1.5.13, start uzreiz pieņem izvēli – fotobokss tad izlaiž tieši šos izvēles ekrānus:

  • vorlage=<Id> (vai template=) – veidne, tikai režīmā print (foto). Id sniedz auswahl?mode=print.
  • stil=<Id> (vai style=) – MI stils, tikai režīmā ai.
  • hintergrund=<Id> (vai background=) – izgriezuma fons, kas atbilst veidnei.

Piemērs: http://localhost:1500/api/start?mode=print&vorlage=hochzeit-gold&hintergrund=strand&password=TAVA-PAROLE

Nezināms vai neatbilstošs Id nesāk sesiju: IsSuccessful ir false, ErrorMessage nosauc iemeslu. Datu aizsardzības piekrišanu un viesu datu veidlapu fotobokss joprojām rāda pats – tās attiecas uz viesi pie fotobokša, un tās nevar nokārtot iepriekš caur API.

Bloķēšanas ekrāns

Sadaļā Pasākumi → Bloķēšanas ekrāns (no 1.5.13) nosaki, ko rāda bloķēts fotobokss: savu tekstu, savu attēlu un – laika loga gadījumā – lielu atpakaļskaitīšanu līdz atvēršanai.

  • Laika logs katram pasākumam: Ar Atveras plkst. un Aizveras plkst. fotobokss ir bloķēts pirms sākuma un pēc beigām.
  • Atbloķēšana ierīcē: Ja ir iestatīts operatora PIN (Sistēma → Aizsardzība), bloķēšanas ekrānā redzama neliela slēdzene. Kas zina PIN, atbloķē fotoboksu. Ja tas atbloķēts pirms sākuma, tas paliek atvērts līdz beigām.
  • Attālināti: Hub sadaļā Kabīnes tu bloķē un atbloķē katru fotoboksu, kas to atbalsta (Studio no 1.5.13). To pašu var izdarīt ar BoothDock Station un ar lockscreen/show / lockscreen/exit.

Notiekošu sesiju nepārtrauc ne bloķēšana no Hub, ne laika logs – fotobokss bloķējas, tiklīdz viesis ir pabeidzis.

Eksports reāllaikā

Tajā pašā cilnē: katrs gatavais fails uzreiz tiek saglabāts pašā fotoboksā (Lokālā kopija) – arī bez Hub, sakārtots pēc pasākuma un tipa (izdrukas, oriģināli, GIF, video – katru var izslēgt atsevišķi). Šī kopija nekad netiek dzēsta automātiski. Sadaļā USB zibatmiņa / otrā mape pievieno otru mērķi: Automātiski rakstīt USB zibatmiņā raksta katrā pievienotajā zibatmiņā, Papildināt izlaistos failus vēlāk ieraksta to, kas radās bez zibatmiņas. Vai arī norādi Fiksētā otrā mape (ir prioritāte), piemēram, mākoņa mapi (OneDrive, Dropbox). Ja viesis dzēš savu sesiju pie fotobokša, pazūd arī kopijas. iPad un iPhone ierīcēs: Lietotnē Faili sadaļā „Manā iPad › BoothDock Studio › Export”. BoothDock Studio 1.5.3 un vecākās versijās tā vietā ir tikai Eksporta mape.

Palaišana ar tālvadību

Tajā pašā cilnē sadaļā Palaišana ar tālvadību piešķir taustiņu. Prezentāciju pulti, USB pogas un kājslēdži parasti sūta atstarpes taustiņu; tas ir iestatīts pēc noklusējuma. Laukā Sāk izvēlies, ko taustiņš palaiž sākuma ekrānā: Kā pieskaroties (parastā plūsma) vai uzreiz kādu režīmu, piemēram, 360° uz platformas. BoothDock Studio 1.4.0 un vecākās versijās taustiņš ir pieejams tikai 360° režīmam, skat. 360° / Palēninājums.

Problēmu risināšana

  • Nekas nenotiek: vai žurnālā kaut kas ir ierakstīts? Webhooks raksta webhooks.log (līdz 1.4.0: ausloeser.log), API – lokale-api.log, abi mapē %LocalAppData%\Boothdock Studio\logs (Windows). Noraidītie pieprasījumi (nepareiza parole, sveša ierīce) tur tiek ierakstīti ne biežāk kā reizi minūtē.
  • "Invalid password." – nokopē paroli vēlreiz; pēc Jauna parole vecā vairs nav derīga.
  • "The booth is not on the start screen …" – start darbojas tikai no sākuma ekrāna. Vispirms cancel, tad start.
  • "Too many failed attempts …" – ierīce pārāk bieži nosūtīja nepareizu paroli. Pagaidi 15 minūtes, pārbaudi paroli.
  • Telefons nesasniedz fotoboksu, bet datorā viss darbojas: gandrīz vienmēr vainīgs Windows ugunsmūris vai Wi-Fi, kas uzskatīts par publisku – skat. augstāk. Abus gadījumus parāda statusa rinda.

Nākamie soļi