Webhooks och API - BoothDock Wiki

BoothDock Studio kan informera andra program om varje steg i en session (webhooks) och låta sig styras av andra program (lokalt API). Båda hittar du i adminområdet under System → Automatisering.

I BoothDock Studio 1.4.0 och tidigare versioner heter webhooks där fortfarande ”Utlösare”.

Webhooks och realtidsexport finns bara under Windows. Det lokala API:t finns från version 1.4.0 även på iPad och iPhone.

Typiska användningar: ljus eller DMX i takt med nedräkningen, ett stream-overlay, en räknare vid entrén – eller ett Stream Deck som fjärrkontroll för boxen.

System → Automatisering: realtidsexport, webhooks och lokalt API

Ställa in webhooks

Fyll i fältet Program, fältet Adress (URL) eller båda. Vid varje händelse anropar boxen båda:

Program – en .exe, .bat eller .cmd. Anrop: program <händelse> <param1> <param2> …. Varje värde kommer fram som ett eget argument, även om det innehåller mellanslag. Programmet startar utan fönster, i sin egen mapp. Ett PowerShell-skript (.ps1) startar du via en liten .bat framför.
Adress (URL) – http eller https, anropad med GET: https://din-server/hook?event_type=<händelse>&param1=…&param2=…. Värdena är URL-kodade; parametrar som redan finns i din adress behålls.

Sessionen väntar aldrig på din webhook: program och anrop körs vid sidan av, och ett anrop får ta högst 5 sekunder. Skicka test skickar direkt ett session_start – så kontrollerar du anslutningen utan att starta en session.

Program och adress kan bara ställas in direkt på boxen, inte via Hub: en programsökväg är en rättighet att köra något på datorn.

Händelser

Händelse	När	Parametrar
`session_start`	En gäst startar en session, läget är bestämt	1: läge (`PrintOnly`, `PrintAndGIF`, `OnlyGIF`, `SlowMoOr360`, `Video`), 2: BoothDock-läge (`photo`, `gif`, `boomerang`, `video`, `slowmo`, `ai`)
`countdown_start`	Nedräkningen börjar	1: sekunder
`countdown`	Varje sekund av nedräkningen	1: förlopp i procent (från 0)
`capture_start`	Nedräkningen är klar, tagningen börjar	–
`file_download`	Kameran har sparat ett foto	1: filnamn, 2: fullständig sökväg
`processing_start`	Bearbetningen börjar	ett filnamn per kameraoriginal, som sista värde utskriftsfilen (för närvarande tom)
`sharing_screen`	Resultatskärmen visas (en gång per session)	–
`printing`	Ett ark skickas till en skrivare	1: fil (för närvarande tom), 2: kopior, 3: skrivare
`file_upload`	En fil har kommit fram till Hub (per fil)	1: sökväg på boxen, 2: gallerilänk, 3: typ (`print`, `photo`, `original`, `animation`, `boomerang`, `video`), 4: album (eventnamn)
`session_end`	Sessionen avslutas – klar, avbruten, utgången eller raderad	–

Exempel på en .bat som loggar varje händelse: echo %DATE% %TIME% %* >> "%~dp0handelser.log"

Lokalt API

Andra program styr boxen via HTTP – till exempel ett Stream Deck, ett eget skript eller en 360°-styrning på mobilen.

Slå på: System → Automatisering → Aktivera API. Från fabrik är API:t avstängt. Port 1500, kan ändras.
Adress: http://localhost:1500/api/<kommando> (eller 127.0.0.1). Från fabrik tar boxen bara emot förfrågningar från den här datorn.
Lösenord: 16 tecken, visas i samma avsnitt – kopiera det eller skapa ett nytt. Skicka med det som ?password=…, som rubrik X-Api-Password eller som Authorization: Bearer …. Bara ping fungerar utan.
Svar: alltid HTTP 200 med JSON, till exempel {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Om det lyckades står i IsSuccessful, orsaken vid fel i ErrorMessage. Vissa kommandon levererar dessutom Data.

Ett fullständigt anrop: http://localhost:1500/api/start?mode=print&password=DITT-LÖSENORD

Styra från nätverket (mobil, surfplatta, 360°)

Slå dessutom på Nås även från nätverket. Då tar boxen emot förfrågningar från enheter i samma Wi-Fi/LAN – aldrig från internet.

Adress för mobilen: står i statusraden, till exempel http://192.168.1.20:1500. Exemplet under visar då direkt rätt adress.
Utan att ange IP: boxen anmäler sig själv i nätverket (mDNS/Bonjour, tjänsttyp _boothdock._tcp, namn ”BoothDock” plus datornamnet). Appar som söker efter den hittar den automatiskt.
Spärr: skickar en enhet fel lösenord tio gånger på tio minuter spärras den i 15 minuter. Boxens egen dator spärras aldrig.
Bara i ditt eget nätverk: lösenordet skickas okrypterat över nätverket. Använd nätverksläget bara i ditt eget, skyddade Wi-Fi – inte i lokalens öppna gäst-Wi-Fi.
Brandvägg: installationen skapar regeln, bara för privata nätverk. Visar statusraden en brandväggsvarning, installera om BoothDock Studio eller tillåt det i Windows under ”Tillåt en app genom brandväggen”. Behandlar Windows ditt Wi-Fi som offentligt kommer enheter inte in – ändra profilen till Privat i nätverksegenskaperna.

Kommandon

Kommando	Verkan
`start?mode=print`	Startar en session. Lägen: `print` (foto), `gif`, `boomerang`, `slowmo` (360°; utan 360° boomerangen), `video`, `ai`. Fungerar bara från startskärmen, bara med ett aktiverat läge och inte när boxen är spärrad.
`cancel`	Avbryter den pågående sessionen och går tillbaka till startskärmen.
`status`	Levererar i `Data`: gästläge på/av, aktuell skärm, läge, spärrad ja/nej.
`print?count=1`	Skriver ut det senaste resultatet en gång till (1 till 10 ark). Videor kan inte skrivas ut.
`lockscreen/show`	Spärrar boxen med ”Ett ögonblick – strax fortsätter vi.” Adminhörnet förblir nåbart.
`lockscreen/exit`	Häver spärren.
`share/email?email=…`	Skickar det senaste resultatet via e-post – kräver kopplingen till Hub och resultatåtgärden ”Skicka via e-post” (System → Drift → Resultatåtgärder (gäst); till och med 1.4.0 reglaget ”Foto via e-post (gäst)” under Design → Skärmar).
`share/sms`	Finns inte; svaret säger det ärligt (`IsSuccessful: false`).
`createtestevent?name=…`	Skapar ett testevent och gör det aktivt. `Data` innehåller `eventId` och `eventName`. Utan namn får det ett namn med datum.
`deletetestevent?eventId=…`	Raderar ett testevent som skapats via API:t – aldrig andra event.
`ping`	Kontrollerar utan lösenord om API:t körs.

Svarar boxen inte inom 15 sekunder kommer IsSuccessful: false tillbaka med en hänvisning.

Realtidsexport

På samma flik väljer du en Exportmapp – till exempel ett USB-minne eller en molnmapp (OneDrive, Dropbox). Varje färdig fil hamnar där direkt, sorterad efter event och typ (Utskrifter, Original, GIF, Videor – kan stängas av var för sig). Saknas minnet en stund hämtar boxen in filerna i efterhand. Raderar en gäst sin session vid boxen försvinner även kopiorna.

Start med fjärrkontroll

På samma flik lär du in en tangent under Start med fjärrkontroll. Presentationsfjärrkontroller, USB-knappar och fotpedaler skickar oftast mellanslag; det är förinställt. Vid Startar väljer du vad tangenten gör på startskärmen: Som vid beröring (normalt flöde) eller direkt ett läge, till exempel 360° på plattformen. I BoothDock Studio 1.4.0 och tidigare versioner finns tangenten bara för 360°, se 360° / slowmotion.

Felsökning

Inget händer: står något i loggen? Webhooks skriver till webhooks.log (till och med 1.4.0: ausloeser.log), API:t till lokale-api.log – båda i mappen %LocalAppData%\Boothdock Studio\logs. Avvisade förfrågningar (fel lösenord, främmande enhet) står där högst en gång per minut.
”Invalid password.” – kopiera lösenordet på nytt; efter Nytt lösenord gäller det gamla inte längre.
”The booth is not on the start screen …” – start fungerar bara från startskärmen. Först cancel, sedan start.
”Too many failed attempts …” – enheten har skickat fel lösenord för många gånger. Vänta 15 minuter och kontrollera lösenordet.
Mobilen når inte boxen, men på datorn fungerar allt: nästan alltid Windows-brandväggen eller ett Wi-Fi som behandlas som offentligt – se ovan. Båda fallen visas i statusraden.