Webhook e API - BoothDock Wiki

BoothDock Studio può informare altri programmi su ogni fase di una sessione (Webhook) e lasciarsi comandare da altri programmi (API locale). Trovi entrambe le funzioni nell'area di amministrazione sotto Sistema → Automazione.

In BoothDock Studio 1.4.0 e nelle versioni precedenti i webhook lì si chiamano ancora «Trigger».

Webhook ed esportazione in tempo reale esistono solo su Windows. L'API locale è disponibile dalla versione 1.4.0 anche su iPad e iPhone.

Usi tipici: luci o DMX in sincronia con il conto alla rovescia, un overlay per lo streaming, un contatore all'ingresso – oppure uno Stream Deck come telecomando per la Box.

Sistema → Automazione: esportazione in tempo reale, webhook e API locale

Configurare i webhook

Inserisci un Programma, un Indirizzo (URL) o entrambi. A ogni evento la Box li richiama entrambi:

Programma – un .exe, .bat o .cmd. Chiamata: programma <evento> <param1> <param2> …. Ogni valore arriva come argomento separato, anche se contiene spazi. Il programma si avvia senza finestra, nella propria cartella. Uno script PowerShell (.ps1) lo avvii tramite un piccolo .bat messo davanti.
Indirizzo (URL) – http o https, richiamato via GET: https://tuo-server/hook?event_type=<evento>&param1=…&param2=…. I valori sono codificati per URL; i parametri già presenti nel tuo indirizzo vengono mantenuti.

La sessione non aspetta mai il tuo webhook: programma e chiamata girano in parallelo, una chiamata può durare al massimo 5 secondi. Invia test manda subito un session_start – così verifichi il collegamento senza avviare una sessione.

Programma e indirizzo si impostano solo direttamente sulla Box, non tramite l'Hub: un percorso di programma equivale al diritto di eseguire qualcosa sul computer.

Eventi

Evento	Quando	Parametri
`session_start`	Un ospite avvia una sessione, la modalità è definita	1: modalità (`PrintOnly`, `PrintAndGIF`, `OnlyGIF`, `SlowMoOr360`, `Video`), 2: modalità BoothDock (`photo`, `gif`, `boomerang`, `video`, `slowmo`, `ai`)
`countdown_start`	Inizia il conto alla rovescia	1: secondi
`countdown`	Ogni secondo del conto alla rovescia	1: avanzamento in percentuale (da 0)
`capture_start`	Il conto alla rovescia è terminato, inizia lo scatto	–
`file_download`	La fotocamera ha salvato una foto	1: nome del file, 2: percorso completo
`processing_start`	Inizia l'elaborazione	un nome file per ogni originale della fotocamera, come ultimo valore il file di stampa (al momento vuoto)
`sharing_screen`	Compare la schermata del risultato (una volta per sessione)	–
`printing`	Un foglio viene inviato a una stampante	1: file (al momento vuoto), 2: copie, 3: stampante
`file_upload`	Un file è arrivato nell'Hub (per ogni file)	1: percorso sulla Box, 2: link della galleria, 3: tipo (`print`, `photo`, `original`, `animation`, `boomerang`, `video`), 4: album (nome dell'evento)
`session_end`	La sessione termina – completata, annullata, scaduta o eliminata	–

Esempio di un .bat che registra ogni evento: echo %DATE% %TIME% %* >> "%~dp0eventi.log"

API locale

Altri programmi comandano la Box via HTTP – ad esempio uno Stream Deck, uno script tuo o un comando 360° sullo smartphone.

Attivazione: Sistema → Automazione → Attiva API. Di fabbrica l'API è disattivata. Porta 1500, modificabile.
Indirizzo: http://localhost:1500/api/<comando> (oppure 127.0.0.1). Di fabbrica la Box accetta solo richieste da questo computer.
Password: 16 caratteri, mostrata nella stessa sezione – copiala o generane una nuova. Va passata come ?password=…, come intestazione X-Api-Password oppure come Authorization: Bearer …. Solo ping funziona senza.
Risposta: sempre HTTP 200 con JSON, ad esempio {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Se ha funzionato lo indica IsSuccessful, il motivo in caso di errore si trova in ErrorMessage. Alcuni comandi restituiscono anche Data.

Una chiamata completa: http://localhost:1500/api/start?mode=print&password=TUA-PASSWORD

Comandare dalla rete (smartphone, tablet, 360°)

Attiva inoltre Raggiungibile anche dalla rete. A quel punto la Box accetta richieste dai dispositivi nella stessa Wi-Fi/LAN – mai da Internet.

Indirizzo per lo smartphone: è indicato nella riga di stato, ad esempio http://192.168.1.20:1500. L'esempio sottostante mostra subito l'indirizzo giusto.
Senza digitare l'IP: la Box si annuncia da sola in rete (mDNS/Bonjour, tipo di servizio _boothdock._tcp, nome „BoothDock" più il nome del computer). Le app che la cercano la trovano automaticamente.
Blocco: se un dispositivo invia dieci volte in dieci minuti una password errata, viene bloccato per 15 minuti. Questo computer non viene mai bloccato.
Solo nella tua rete: la password viaggia in rete senza cifratura. Usa il funzionamento in rete solo nella tua Wi-Fi protetta – non nella Wi-Fi aperta per gli ospiti della location.
Firewall: l'installazione crea l'autorizzazione, solo per le reti private. Se la riga di stato mostra un avviso del firewall, reinstalla BoothDock Studio oppure consentilo in Windows in „Consenti app attraverso il firewall". Se Windows considera la Wi-Fi pubblica, i dispositivi non riescono a entrare – nelle proprietà di rete imposta il profilo su Privata.

Comandi

Comando	Effetto
`start?mode=print`	Avvia una sessione. Modalità: `print` (foto), `gif`, `boomerang`, `slowmo` (360°; senza 360° il boomerang), `video`, `ai`. Funziona solo dalla schermata iniziale, solo con una modalità attivata e non con la Box bloccata.
`cancel`	Annulla la sessione in corso e torna alla schermata iniziale.
`status`	Restituisce in `Data`: modalità ospite attiva/disattiva, schermata attuale, modalità, bloccata sì/no.
`print?count=1`	Stampa di nuovo l'ultimo risultato (da 1 a 10 fogli). I video non si possono stampare.
`lockscreen/show`	Blocca la Box con „Un attimo – torniamo subito." L'angolo admin resta raggiungibile.
`lockscreen/exit`	Rimuove il blocco.
`share/email?email=…`	Invia l'ultimo risultato via e-mail – richiede l'accoppiamento con l'Hub e l'azione sul risultato «Ricevi via e-mail» (Sistema → Funzionamento → Azioni sul risultato (ospite); fino alla 1.4.0 l'interruttore «Foto via e-mail (ospite)» sotto Design → Schermate).
`share/sms`	Non esiste; la risposta lo dice onestamente (`IsSuccessful: false`).
`createtestevent?name=…`	Crea un evento di prova e lo rende attivo. `Data` contiene `eventId` e `eventName`. Senza nome ne riceve uno con la data.
`deletetestevent?eventId=…`	Elimina un evento di prova creato tramite l'API – mai altri eventi.
`ping`	Verifica senza password se l'API è in funzione.

Se la Box non risponde entro 15 secondi, viene restituito IsSuccessful: false con un'indicazione.

Esportazione in tempo reale

Nella stessa scheda scegli una Cartella di esportazione – ad esempio una chiavetta USB o una cartella cloud (OneDrive, Dropbox). Ogni file finito vi arriva subito, ordinato per evento e tipo (stampe, originali, GIF, video – disattivabili singolarmente). Se la chiavetta manca per un momento, la Box recupera i file in seguito. Se un ospite elimina la propria sessione sulla Box, spariscono anche le copie.

Avvio da telecomando

Nella stessa scheda memorizzi un tasto in Avvio da telecomando. Telecomandi per presentazioni, pulsanti USB e pedali inviano di solito la barra spaziatrice; è quella preimpostata. In Avvia scegli che cosa fa il tasto nella schermata iniziale: Come un tocco (flusso normale) oppure direttamente una modalità, ad esempio il 360° sulla piattaforma. In BoothDock Studio 1.4.0 e nelle versioni precedenti il tasto esiste solo per il 360°, vedi 360° / Rallentatore.

Risoluzione dei problemi

Non succede nulla: c'è qualcosa nel registro? I webhook scrivono in webhooks.log (fino alla 1.4.0: ausloeser.log), l'API in lokale-api.log – entrambi nella cartella %LocalAppData%\Boothdock Studio\logs. Le richieste rifiutate (password errata, dispositivo estraneo) vi compaiono al massimo una volta al minuto.
„Invalid password." – copia di nuovo la password; dopo Nuova password quella vecchia non vale più.
„The booth is not on the start screen …" – start funziona solo dalla schermata iniziale. Prima cancel, poi start.
„Too many failed attempts …" – il dispositivo ha inviato troppe volte una password errata. Attendi 15 minuti e controlla la password.
Lo smartphone non raggiunge la Box, sul computer funziona tutto: quasi sempre è colpa del firewall di Windows o di una Wi-Fi considerata pubblica – vedi sopra. La riga di stato segnala entrambi i casi.