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».
I webhook esistono su Windows e, dalla versione 1.5.10, anche su iPad, iPhone e Mac. L'API locale è disponibile dalla versione 1.4.0 anche su iPad, iPhone e Mac, l'esportazione in tempo reale dalla versione 1.5.2.
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.

Configurare i webhook
Inserisci un Indirizzo (URL), su Windows anche un Programma – o entrambi. A ogni evento la Box richiama tutto ciò che hai inserito:
- Programma (solo Windows) – un
.exe,.bato.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.batmesso davanti. - Indirizzo (URL) –
httpohttps, richiamato via GET:https://tuo-server/hook?event_type=<evento>¶m1=…¶m2=…. I valori sono codificati per URL; i parametri già presenti nel tuo indirizzo vengono mantenuti.
Su iPad, iPhone e Mac c'è solo l'indirizzo. Lì http:// funziona solo nella rete locale (indirizzo IP o .local) – quindi Shelly, WLED e Tasmota sul Wi-Fi funzionano. Gli indirizzi su Internet richiedono https://.
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.
Indirizzo proprio per evento
Dalla versione 1.5.10, in Indirizzo proprio per evento (facoltativo) puoi dare in più a ogni evento un indirizzo proprio – ad esempio per una presa Shelly, WLED o Tasmota sul Wi-Fi che si attiva al conto alla rovescia o allo scatto. Esempio per countdown_start: http://192.168.1.50/relay/0?turn=on.
La Box richiama questo indirizzo in aggiunta al programma e all'indirizzo sopra, come semplice GET senza valori aggiunti. L'indirizzo precedente e gli script esistenti continuano a funzionare senza modifiche. countdown arriva ogni secondo; per file_upload la Box richiama l'indirizzo proprio una volta per sessione (l'indirizzo generale sempre una volta per file).
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) |
lead_submitted | Un ospite ha inviato il modulo Dati degli ospiti (modulo) (dalla 1.5.0) | – (le risposte stesse sono solo nell'esportazione CSV) |
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>(oppure127.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 intestazioneX-Api-Passwordoppure comeAuthorization: Bearer …. Solopingfunziona senza. - Risposta: sempre HTTP 200 con JSON, ad esempio
{"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Se ha funzionato lo indicaIsSuccessful, il motivo in caso di errore si trova inErrorMessage. Alcuni comandi restituiscono ancheData.
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. Con modello, stile e sfondo: vedi sotto. |
auswahl?mode=print | Restituisce in Data cosa c'è da scegliere per questa modalità: vorlagen (Id e nome; vuoto se è abilitato un solo modello – che si trova allora in vorgabeVorlage), hintergruende per modello e, nella modalità ai, gli stile (dalla 1.5.13). |
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 – dalla 1.5.13 anche sperrgrund (manuell o zeitfenster) e oeffnetUm. |
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." oppure con il tuo testo e la tua immagine (vedi „Schermata di blocco“ sotto). L'angolo admin resta raggiungibile. Dalla 1.5.13 il blocco resta attivo anche dopo un riavvio dell'app. |
lockscreen/exit | Rimuove il blocco – dalla 1.5.13 anche il blocco dovuto alla fascia oraria, fino al cambio successivo. |
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. Solo fuori dalla modalità ospite (dalla 1.5.4). |
deletetestevent?eventId=… | Elimina un evento di prova creato tramite l'API – mai altri eventi. Solo fuori dalla modalità ospite (dalla 1.5.4). |
ping | Verifica senza password se l'API è in funzione. |
Se la Box non risponde entro 15 secondi, viene restituito IsSuccessful: false con un'indicazione.
Avviare una sessione con modello, stile e sfondo
Dalla versione 1.5.13 start accetta subito la scelta – la Box salta allora proprio queste schermate di selezione:
vorlage=<Id>(otemplate=) – il modello, solo nella modalitàprint(foto). Gli Id li fornisceauswahl?mode=print.stil=<Id>(ostyle=) – lo stile IA, solo nella modalitàai.hintergrund=<Id>(obackground=) – lo sfondo per lo scontorno, adatto al modello.
Esempio: http://localhost:1500/api/start?mode=print&vorlage=hochzeit-gold&hintergrund=strand&password=TUA-PASSWORD
Un Id sconosciuto o non adatto non avvia alcuna sessione: IsSuccessful è false, ErrorMessage indica il motivo. Il consenso privacy e il modulo dati ospiti continuano a essere mostrati dalla Box stessa – riguardano l'ospite davanti alla Box e non si possono anticipare tramite l'API.
Schermata di blocco
In Eventi → Schermata di blocco (dalla 1.5.13) stabilisci cosa mostra una Box bloccata: il tuo testo, la tua immagine e – con la fascia oraria – un grande conto alla rovescia fino all'apertura.
- Fascia oraria per evento: Con Apre alle e Chiude alle la Box è bloccata prima dell'inizio e dopo la fine.
- Sbloccare sul dispositivo: Se è impostato un PIN operatore (Sistema → Protezione), la schermata di blocco mostra un piccolo lucchetto. Chi conosce il PIN sblocca la Box. Se sbloccata prima dell'inizio, resta aperta fino alla fine.
- Da remoto: Nell'Hub, sotto Cabine, blocchi e sblocchi ogni Box che lo supporta (Studio dalla 1.5.13). Lo stesso funziona tramite BoothDock Station e con
lockscreen/show/lockscreen/exit.
Né il blocco dall'Hub né la fascia oraria interrompono una sessione in corso – la Box si blocca non appena l'ospite ha finito.
Esportazione in tempo reale
Nella stessa scheda: ogni file finito viene salvato subito sulla Box stessa (Copia locale) – anche senza Hub, ordinato per evento e tipo (stampe, originali, GIF, video – disattivabili singolarmente). Questa copia non viene mai cancellata automaticamente. In Chiavetta USB / seconda cartella aggiungi una seconda destinazione: Scrivi automaticamente sulla chiavetta USB scrive su ogni chiavetta inserita, Recupera i file mancati recupera ciò che è nato senza chiavetta. In alternativa indichi una Seconda cartella fissa (ha la precedenza), ad esempio una cartella cloud (OneDrive, Dropbox). Se un ospite elimina la propria sessione sulla Box, spariscono anche le copie. Su iPad e iPhone: Nell’app File in «Sul mio iPad › BoothDock Studio › Export». In BoothDock Studio 1.5.3 e precedenti c'è invece solo la Cartella di esportazione.
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 inlokale-api.log– entrambi nella cartella%LocalAppData%\Boothdock Studio\logs(Windows). 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 …" –
startfunziona solo dalla schermata iniziale. Primacancel, poistart. - „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.