Webhooks og API - BoothDock Wiki

BoothDock Studio kan informere andre programmer om hvert trin i en session (Webhooks) og selv lade sig styre af andre programmer (lokal API). Begge dele finder du i admin-området under System → Automatisering.

I BoothDock Studio 1.4.0 og tidligere versioner hedder webhooks dér stadig „Udløsere“.

Webhooks og eksport i realtid findes kun under Windows. Den lokale API findes fra version 1.4.0 også på iPad og iPhone.

Typiske anvendelser: lys eller DMX, der passer til nedtællingen, et stream-overlay, en tæller ved indgangen – eller et Stream Deck som fjernbetjening til boksen.

System → Automatisering: eksport i realtid, webhooks og lokal API

Opsætning af webhooks

Angiv et Program, en Adresse (URL) eller begge dele. Ved hver hændelse kalder boksen begge:

Program – en .exe, .bat eller .cmd. Kald: program <hændelse> <param1> <param2> …. Hver værdi kommer som et separat argument, også hvis den indeholder mellemrum. Programmet starter uden vindue, i sin egen mappe. Et PowerShell-script (.ps1) starter du via en lille .bat foran.
Adresse (URL) – http eller https, kaldt via GET: https://din-server/hook?event_type=<hændelse>&param1=…&param2=…. Værdierne er URL-kodede; parametre, der allerede står i din adresse, bevares.

Sessionen venter aldrig på din webhook: program og kald kører ved siden af, og et kald må højst tage 5 sekunder. Send test sender straks en session_start – sådan tjekker du forbindelsen uden at starte en session.

Program og adresse kan kun indstilles direkte på boksen, ikke via Hub'en: en programsti er en ret til at køre noget på computeren.

Hændelser

Hændelse	Hvornår	Parametre
`session_start`	En gæst starter en session, tilstanden ligger fast	1: tilstand (`PrintOnly`, `PrintAndGIF`, `OnlyGIF`, `SlowMoOr360`, `Video`), 2: BoothDock-tilstand (`photo`, `gif`, `boomerang`, `video`, `slowmo`, `ai`)
`countdown_start`	Nedtællingen begynder	1: sekunder
`countdown`	Hvert sekund af nedtællingen	1: fremskridt i procent (fra 0)
`capture_start`	Nedtællingen er slut, optagelsen begynder	–
`file_download`	Kameraet har gemt et foto	1: filnavn, 2: fuld sti
`processing_start`	Behandlingen begynder	ét filnavn pr. kameraoriginal, som sidste værdi printfilen (i øjeblikket tom)
`sharing_screen`	Resultatskærmen vises (én gang pr. session)	–
`printing`	Et ark sendes til en printer	1: fil (i øjeblikket tom), 2: kopier, 3: printer
`file_upload`	En fil er nået frem til Hub'en (pr. fil)	1: sti på boksen, 2: gallerilink, 3: type (`print`, `photo`, `original`, `animation`, `boomerang`, `video`), 4: album (eventnavn)
`session_end`	Sessionen slutter – færdig, afbrudt, udløbet eller slettet	–

Eksempel på en .bat, der logger hver hændelse: echo %DATE% %TIME% %* >> "%~dp0events.log"

Lokal API

Andre programmer styrer boksen via HTTP – f.eks. et Stream Deck, dit eget script eller en 360°-styring på mobilen.

Slå til: System → Automatisering → Slå API til. Fra fabrikken er API'en slået fra. Port 1500, kan ændres.
Adresse: http://localhost:1500/api/<kommando> (eller 127.0.0.1). Fra fabrikken tager boksen kun imod forespørgsler fra denne computer.
Adgangskode: 16 tegn, vises i samme afsnit – kopier den eller opret en ny. Angives som ?password=…, som headeren X-Api-Password eller som Authorization: Bearer …. Kun ping virker uden.
Svar: altid HTTP 200 med JSON, for eksempel {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Om det lykkedes, står i IsSuccessful, og årsagen ved fejl i ErrorMessage. Nogle kommandoer returnerer desuden Data.

Et komplet kald: http://localhost:1500/api/start?mode=print&password=DIN-ADGANGSKODE

Styring fra netværket (mobil, tablet, 360°)

Slå desuden Også tilgængelig fra netværket til. Så tager boksen imod forespørgsler fra enheder på samme Wi-Fi/LAN – aldrig fra internettet.

Adresse til mobilen: står i statuslinjen, for eksempel http://192.168.1.20:1500. Eksemplet nedenunder viser så straks den passende adresse.
Uden at indtaste IP: Boksen melder sig selv på netværket (mDNS/Bonjour, tjenestetype _boothdock._tcp, navnet „BoothDock" plus computernavnet). Apps, der søger efter den, finder den automatisk.
Spærring: Sender en enhed en forkert adgangskode ti gange inden for ti minutter, spærres den i 15 minutter. Denne computer bliver aldrig spærret.
Kun på dit eget netværk: Adgangskoden sendes ukrypteret over netværket. Brug kun netværksdrift på dit eget, beskyttede Wi-Fi – ikke på stedets åbne gæste-Wi-Fi.
Firewall: Installationen opretter undtagelsen, kun for private netværk. Viser statuslinjen en firewall-advarsel, så geninstaller BoothDock Studio eller tillad det i Windows under „Tillad en app gennem firewall". Behandler Windows dit Wi-Fi som offentligt, kan enheder ikke komme ind – sæt profilen til Privat i netværksegenskaberne.

Kommandoer

Kommando	Virkning
`start?mode=print`	Starter en session. Tilstande: `print` (foto), `gif`, `boomerang`, `slowmo` (360°; uden 360° boomerang), `video`, `ai`. Virker kun fra startskærmen, kun med en aktiveret tilstand og ikke, når boksen er spærret.
`cancel`	Afbryder den igangværende session og går tilbage til startskærmen.
`status`	Returnerer i `Data`: gæstetilstand til/fra, aktuel skærm, tilstand, spærret ja/nej.
`print?count=1`	Udskriver det seneste resultat igen (1 til 10 ark). Videoer kan ikke udskrives.
`lockscreen/show`	Spærrer boksen med „Lige et øjeblik – vi fortsætter straks." Admin-hjørnet forbliver tilgængeligt.
`lockscreen/exit`	Ophæver spærringen.
`share/email?email=…`	Sender det seneste resultat pr. e-mail – kræver Hub-koblingen og resultathandlingen „Få via e-mail“ (System → Drift → Resultathandlinger (gæst); til og med 1.4.0 kontakten „Foto pr. e-mail (gæst)“ under Design → Skærme).
`share/sms`	Findes ikke; svaret siger det ærligt (`IsSuccessful: false`).
`createtestevent?name=…`	Opretter et testevent og gør det aktivt. `Data` indeholder `eventId` og `eventName`. Uden navn får det et navn med dato.
`deletetestevent?eventId=…`	Sletter et testevent, der er oprettet via API'en – aldrig andre events.
`ping`	Tjekker uden adgangskode, om API'en kører.

Svarer boksen ikke inden for 15 sekunder, kommer IsSuccessful: false tilbage med en bemærkning.

Eksport i realtid

I samme fane vælger du en Eksportmappe – f.eks. et USB-stik eller en cloudmappe (OneDrive, Dropbox). Hver færdig fil lander der med det samme, sorteret efter event og type (udskrifter, originaler, GIF'er, videoer – kan slås fra enkeltvis). Mangler stikket kortvarigt, kopierer boksen filerne bagefter. Sletter en gæst sin session ved automaten, forsvinder kopierne også.

Start med fjernbetjening

I samme fane indlærer du en tast under Start med fjernbetjening. Presentere, USB-knapper og fodkontakter sender oftest mellemrumstasten; den er forudindstillet. Under Starter vælger du, hvad tasten udløser på startskærmen: Som berøring (normalt forløb) eller direkte en tilstand, for eksempel 360° på platformen. I BoothDock Studio 1.4.0 og tidligere versioner findes tasten kun til 360°, se 360° / Slowmotion.

Fejlfinding

Der sker ingenting: Står der noget i loggen? Webhooks skriver til webhooks.log (til og med 1.4.0: ausloeser.log), API'en til lokale-api.log – begge i mappen %LocalAppData%\Boothdock Studio\logs. Afviste forespørgsler (forkert adgangskode, fremmed enhed) står der højst én gang i minuttet.
„Invalid password." – kopier adgangskoden igen; efter Ny adgangskode gælder den gamle ikke længere.
„The booth is not on the start screen …" – start virker kun fra startskærmen. Først cancel, så start.
„Too many failed attempts …" – enheden har sendt en forkert adgangskode for mange gange. Vent 15 minutter, og tjek adgangskoden.
Mobilen når ikke boksen, men på computeren virker alt: næsten altid Windows Firewall eller et Wi-Fi, der behandles som offentligt – se ovenfor. Statuslinjen melder begge tilfælde.