Webhooks un API - BoothDock Wiki

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 un eksports reāllaikā ir pieejami tikai operētājsistēmā Windows. Lokālā API no versijas 1.4.0 ir pieejama arī iPad un iPhone ierīcēs.

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

Webhooks iestatīšana

Aizpildi lauku Programma, Adrese (URL) vai abus. Pie katra notikuma fotobokss izsauc abus:

Programma – .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.

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ā.

Notikumi

Notikums	Kad	Parametri
`session_start`	Viesis sāk sesiju, režīms ir noteikts	1: režīms (`PrintOnly`, `PrintAndGIF`, `OnlyGIF`, `SlowMoOr360`, `Video`), 2: BoothDock režīms (`photo`, `gif`, `boomerang`, `video`, `slowmo`, `ai`)
`countdown_start`	Sākas atskaite	1: sekundes
`countdown`	Katra atskaites sekunde	1: progress procentos (no 0)
`capture_start`	Atskaite beigusies, sākas uzņemšana	–
`file_download`	Kamera ir saglabājusi fotoattēlu	1: faila nosaukums, 2: pilns ceļš
`processing_start`	Sākas apstrāde	katram kameras oriģinālam viens faila nosaukums, kā pēdējā vērtība – drukas fails (pašlaik tukšs)
`sharing_screen`	Parādās rezultāta ekrāns (vienreiz katrā sesijā)	–
`printing`	Lapa tiek nosūtīta uz printeri	1: fails (pašlaik tukšs), 2: kopijas, 3: printeris
`file_upload`	Fails 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)
`session_end`	Sesija 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

Komanda	Darbība
`start?mode=print`	Sā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.
`cancel`	Atceļ notiekošo sesiju un atgriežas sākuma ekrānā.
`status`	Atgriež `Data`: viesu režīms ieslēgts/izslēgts, pašreizējais ekrāns, režīms, bloķēts jā/nē.
`print?count=1`	Vēlreiz izdrukā pēdējo rezultātu (no 1 līdz 10 lapām). Video nevar izdrukāt.
`lockscreen/show`	Bloķē fotoboksu ar uzrakstu "Mirklīti – tūlīt turpināsim." Administratora stūris paliek pieejams.
`lockscreen/exit`	Atceļ bloķēšanu.
`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.
`deletetestevent?eventId=…`	Dzēš testa pasākumu, kas izveidots caur API – nekad citus pasākumus.
`ping`	Bez paroles pārbauda, vai API darbojas.

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

Eksports reāllaikā

Tajā pašā cilnē laukā Eksporta mape izvēlies mapi – piemēram, USB zibatmiņu vai mākoņa mapi (OneDrive, Dropbox). Katrs gatavais fails tur nonāk uzreiz, sakārtots pēc pasākuma un tipa (izdrukas, oriģināli, GIF, video – katru var izslēgt atsevišķi). Ja zibatmiņa uz brīdi nav pievienota, fotobokss failus iekopē vēlāk. Ja viesis dzēš savu sesiju pie fotobokša, pazūd arī kopijas.

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. 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.