← Alle artikler

BoothDock · Wiki

Webhooks og API

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 findes under Windows og fra version 1.5.10 også på iPad, iPhone og Mac. Den lokale API findes fra version 1.4.0 også på iPad, iPhone og Mac, eksport i realtid fra version 1.5.2.

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
System → Automatisering: eksport i realtid, webhooks og lokal API

Opsætning af webhooks

Angiv en Adresse (URL), under Windows også et Program – eller begge dele. Ved hver hændelse kalder boksen alt, hvad der er angivet:

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

På iPad, iPhone og Mac er der kun adressen. Her virker http:// kun i det lokale netværk (IP-adresse eller .local) – Shelly, WLED og Tasmota på wifi virker altså. Adresser på internettet kræver https://.

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.

Egen adresse pr. hændelse

Fra version 1.5.10 kan du under Egen adresse pr. hændelse (valgfri) give hver hændelse sin egen adresse oveni – fx til en Shelly-stikkontakt, WLED eller Tasmota på wifi, der skifter ved nedtællingen eller optagelsen. Eksempel for countdown_start: http://192.168.1.50/relay/0?turn=on.

Boksen kalder denne adresse ud over programmet og adressen ovenfor, som et enkelt GET uden tilføjede værdier. Den hidtidige adresse og eksisterende scripts virker uændret. countdown kommer hvert sekund; ved file_upload kalder boksen den egne adresse én gang pr. session (den generelle adresse fortsat pr. fil).

Hændelser

HændelseHvornårParametre
session_startEn gæst starter en session, tilstanden ligger fast1: tilstand (PrintOnly, PrintAndGIF, OnlyGIF, SlowMoOr360, Video), 2: BoothDock-tilstand (photo, gif, boomerang, video, slowmo, ai)
countdown_startNedtællingen begynder1: sekunder
countdownHvert sekund af nedtællingen1: fremskridt i procent (fra 0)
capture_startNedtællingen er slut, optagelsen begynder–
file_downloadKameraet har gemt et foto1: filnavn, 2: fuld sti
processing_startBehandlingen begynderét filnavn pr. kameraoriginal, som sidste værdi printfilen (i øjeblikket tom)
sharing_screenResultatskærmen vises (én gang pr. session)–
printingEt ark sendes til en printer1: fil (i øjeblikket tom), 2: kopier, 3: printer
file_uploadEn 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)
lead_submittedEn gæst har sendt formularen Gæstedata (formular) (fra 1.5.0)– (selve svarene står kun i CSV-eksporten)
session_endSessionen 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

KommandoVirkning
start?mode=printStarter 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. Med skabelon, stil og baggrund: se nedenfor.
auswahl?mode=printReturnerer i Data, hvad der kan vælges i denne tilstand: vorlagen (Id og navn; tom, hvis kun én skabelon er frigivet – den står så i vorgabeVorlage), hintergruende pr. skabelon og i tilstanden ai stile (fra 1.5.13).
cancelAfbryder den igangværende session og går tilbage til startskærmen.
statusReturnerer i Data: gæstetilstand til/fra, aktuel skærm, tilstand, spærret ja/nej – fra 1.5.13 også sperrgrund (manuell eller zeitfenster) og oeffnetUm.
print?count=1Udskriver det seneste resultat igen (1 til 10 ark). Videoer kan ikke udskrives.
lockscreen/showSpærrer boksen med „Lige et øjeblik – vi fortsætter straks." eller din egen tekst og dit eget billede (se „Låseskærm“ nedenfor). Admin-hjørnet forbliver tilgængeligt. Fra 1.5.13 bevares spærringen også ved en genstart af appen.
lockscreen/exitOphæver spærringen – fra 1.5.13 også spærringen via tidsvinduet, indtil næste skift.
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/smsFindes 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. Kun uden for gæstetilstand (fra 1.5.4).
deletetestevent?eventId=…Sletter et testevent, der er oprettet via API'en – aldrig andre events. Kun uden for gæstetilstand (fra 1.5.4).
pingTjekker uden adgangskode, om API'en kører.

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

Start en session med skabelon, stil og baggrund

Fra version 1.5.13 tager start valget med med det samme – boksen springer så netop disse valgskærme over:

  • vorlage=<Id> (eller template=) – skabelonen, kun i tilstanden print (foto). Id'erne får du med auswahl?mode=print.
  • stil=<Id> (eller style=) – AI-stilen, kun i tilstanden ai.
  • hintergrund=<Id> (eller background=) – baggrunden til fritlægningen, der passer til skabelonen.

Eksempel: http://localhost:1500/api/start?mode=print&vorlage=hochzeit-gold&hintergrund=strand&password=DIN-ADGANGSKODE

Et ukendt eller ikke-passende Id starter ingen session: IsSuccessful er false, ErrorMessage angiver årsagen. Samtykke til databeskyttelse og formularen til gæstedata viser boksen stadig selv – de gælder for gæsten foran boksen og kan ikke klares på forhånd via API'et.

Låseskærm

Under Arrangementer → Låseskærm (fra 1.5.13) bestemmer du, hvad en spærret boks viser: egen tekst, eget billede og – ved tidsvindue – en stor nedtælling til åbningen.

  • Tidsvindue pr. arrangement: Med Åbner kl. og Lukker kl. er boksen spærret før start og efter slut.
  • Lås op på enheden: Er der oprettet en operatør-PIN (System → Beskyttelse), viser spærreskærmen en lille hængelås. Den, der kender PIN'en, låser boksen op. Låses den op før start, forbliver den åben til slut.
  • På afstand: I Hub'en under Bokse spærrer og ophæver du spærringen af hver boks, der kan det (Studio fra 1.5.13). Det samme kan gøres via BoothDock Station og med lockscreen/show / lockscreen/exit.

En igangværende session afbrydes hverken af spærringen fra Hub'en eller af tidsvinduet – boksen spærres, så snart gæsten er færdig.

Eksport i realtid

I samme fane: Hver færdig fil lander straks på selve boksen (Lokal kopi) – også uden Hub, sorteret efter event og type (udskrifter, originaler, GIF'er, videoer – kan slås fra enkeltvis). Denne kopi slettes aldrig automatisk. Under USB-nøgle / anden mappe tilføjer du et ekstra mål: Skriv automatisk til USB-nøgle skriver til ethvert isat stik, Indhent mistede filer skriver bagefter det, der blev lavet uden stik. Alternativt angiver du en Fast anden mappe (har forrang), f.eks. en cloudmappe (OneDrive, Dropbox). Sletter en gæst sin session ved automaten, forsvinder kopierne også. På iPad og iPhone: I appen Filer under “På min iPad › BoothDock Studio › Export”. I BoothDock Studio 1.5.3 og ældre findes i stedet kun Eksportmappe.

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

Næste skridt