Guida all'editor Event Flow

0. Orientamento rapido

Cos'è questo editor?

L'editor Event Flow è il livello di “automazione avanzata” di Social Stream Ninja. Si colloca sopra i semplici interruttori del popup e consente di programmare una propria logica di instradamento. Usalo quando devi:

• Inoltra la chat tra servizi con filtri (ad esempio replica Twitch su Discord ma blocca i comandi).
• Crea comandi basati sulla fedeltà, giochi con parole chiave o condizioni di accesso alle estrazioni con logica AND/OR/NOT.
• Attiva overlay personalizzati, audio, scene OBS o webhook in base ai dati che arricchisci nel flusso.
• Combina più piattaforme in una singola automazione (Kick + Twitch + YouTube instradati attraverso un solo flusso).

Considera il popup come una raccolta di preset rapidi ed Event Flow come l'insieme di strumenti per flussi personalizzati.

Ogni flusso inizia con un trigger

I nodi azione (verdi) non vengono mai eseguiti da soli: si attivano solo quando un nodo trigger (blu) sopra di loro restituisce true. Un flusso composto solo da azioni concatenate sembra valido, ma resta sempre inattivo perché nulla avvia la catena. I nomi dei nodi descrivono cosa il nodo fa, non quando avviene: Metti messaggio in evidenza (Feature Message) mette in evidenza un messaggio quando il flusso lo raggiunge; non si attiva quando metti un messaggio in evidenza altrove.

Overlay Flow Actions (uscita delle azioni)

Nodi come Riproduci clip audio, Mostra overlay multimediale, e i controlli OBS hanno bisogno di una superficie di visualizzazione. Questa superficie è la pagina overlay Flow Actions servita da actions.html. Mantienila in esecuzione nel software di trasmissione (dock browser OBS/Streamer.bot/ecc.) affinché le azioni Event Flow abbiano un posto dove apparire.

Una volta caricato, quell'overlay può:

• Mostrare URL GIPHY o multimediali diretti, testo e coriandoli attivati dai flussi.
• Riprodurre suoni (TTS, clip audio) localmente affinché gli spettatori li sentano.
• Comunica con OBS tramite le impostazioni WebSocket nella sezione Flow Actions del popup (cambio di scena, visibilità delle sorgenti, aggiornamenti di testo GDI+/FreeType, buffer replay ecc.).

1. Cosa passa attraverso un nodo?

Il runtime Event Flow passa due elementi attraverso ogni filo:

1. Payload – l'oggetto dati dell'evento o del messaggio.
2. Segnale della porta – un bit true/false che indica al nodo successivo se deve essere eseguito.

Requisiti degli ingressi

• Sorgenti degli eventi (messaggio Twitch, timer, trigger manuale ecc.) ignorano l'ingresso a monte: generano il proprio payload ed emettono sempre true a meno che il nodo stesso non produca un errore.
• Nodi di trasformazione e logica leggono il payload e possono riscrivere campi, impostare lo stato o cambiare il segnale della porta in false.
• Nodi azione si attivano solo quando la porta resta true. Possono comunque emettere un payload aggiornato se vuoi continuare a concatenare azioni.

Schemi di uscita

2. Riepilogo dei nodi logici

Questi blocchi rispondono alle domande più comuni su cosa significhino true/false.

3. Esempi di microflussi

A. Rispondi automaticamente, salvo quando il messaggio è un comando

Qui il nodo Regex emette true quando il messaggio è un comando. Instradiamo l’uscita false alla nostra risposta, così chi scrive normalmente riceve un riscontro mentre i comandi passano semplicemente oltre.

B. Richiedi più verifiche con AND

Il nodo AND assicura che solo i membri che usano la parola chiave corretta vengano inoltrati a Discord. Entrambi i rami inviano il risultato booleano al nodo AND; il payload del primo ramo prosegue a valle.

C. Nodo NOT per bloccare avvisi ripetuti

State Check restituisce il valore true quando l'avviso è silenziato. Invertendo quel risultato, il nodo NOT assicura che il festeggiamento venga riprodotto solo quando il flag è false.

D. Riproduci casualmente uno di due suoni

La porta AND non è facoltativa. Un NOT isolato emetterebbe true ogni volta che la porta RANDOM è inattiva, quindi il suono B verrebbe riprodotto per ogni messaggio chat che non corrisponde al trigger. Collegare il trigger ad AND come secondo ingresso limita il suono B ai soli messaggi corrispondenti. Lo stesso schema funziona con qualsiasi coppia alternativa di azioni, non solo con l’audio.

4. Prevenire echi, cicli e ritorni nell'inoltro

Inoltrare la chat tra interfacce è potente, ma può generare echi infiniti se ascolti il tuo stesso output. Segui queste precauzioni:

• Evita sistemi di inoltro duplicati. Disattiva Relay all globale quando usi percorsi Event Flow equivalenti e controlla se altri servizi collegano le stesse chat. Non è garantito che i metadati personalizzati sopravvivano al passaggio attraverso la chat di una piattaforma.
• Usa nodi Debounce o Cooldown per avvisi che devono attivarsi solo una volta ogni X secondi.
• Interrompi i cicli intenzionalmente. Se due rami si alimentano a vicenda, aggiungi un nodo logico che controlli una variabile di stato ("currentlyRelaying"), così il flusso esce subito quando il flag è impostato.

5. Ingressi, uscite e domande pratiche

Domande e risposte comuni

• Devo usare AND per ogni coppia di filtri? No. Molti nodi includono più controlli (ad esempio il filtro messaggi di base supporta parola chiave + ruolo). Usa AND solo per combinazioni avanzate o quando unisci segnali da nodi diversi.
• Come arrivano i valori true/false al nodo NOT? Ogni nodo con un'uscita verde emette true per impostazione predefinita. Quando una condizione fallisce, emette false. Collega quel filo a NOT per invertire il risultato.
• Un nodo può emettere un payload anche se restituisce false? Sì. Il payload passa comunque attraverso l'uscita false; spetta a te decidere dove deve andare quel ramo.
• Come riconosco i membri del team TikTok? Scegli Membro del team TikTok (TikTok Team Member) nel nodo User Role. Riconosce livelli e badge TikTok Fan Club/team nel messaggio in arrivo e non dipende dalle impostazioni del Main Chat Overlay.
• Ogni nodo Speak Text può usare una voce diversa? Sì. Inserisci un nome o ID voce supportato dal provider in Sostituzione voce (Voice Override), oppure lascialo vuoto per usare la voce TTS predefinita di Flow Actions.

6. Riferimento delle variabili di modello

Diversi nodi azione (Show Text, Set Text Source, Send Message, Relay Chat, TTS Speak, Call Webhook, Print Thermal Label) supportano variabili di modello che vengono sostituite con i dati dell'evento durante l'esecuzione. Racchiudi i nomi delle variabili tra parentesi graffe, come {username}.

Variabili di base (compatibili con le versioni precedenti)

Variabili estese

Modelli di esempio

• Show Text: {username} just cheered {hasDonation}!
• Imposta sorgente di testo OBS: {username}: now {counterValue}, need {counterTarget}
• Relay Chat: [{source}] {username}: {message}
• TTS: {username} says {message}
• Avviso di donazione: {username} donated {donation} - {subtitle}
• Etichetta termica: {username}, una nuova riga, poi {donation}. Vedi la Guida alle stampanti termiche per configurare la stampante, le etichette di dimensioni fisse e un flusso completo.
• Call Webhook Discord: {"content":"{message}","username":"{username}","avatar_url":"{chatimg}"}

7. Elenco delle buone pratiche

• Dai un nome e un colore ai nodi, così in futuro saprai riconoscere ogni ramo.
• Prova con il simulatore integrato (Send Test Event) prima di usare un flusso in diretta.
• Raggruppa la logica vicino alla sorgente. Filtra il prima possibile per evitare elaborazioni aggiuntive più avanti.
• Memorizza le ripetizioni nei nodi di stato. Usa contatori, interruttori e timestamp per evitare avvisi duplicati.
• Documenta i campi meta. Quando aggiungi chiavi meta personalizzate, documentale affinché overlay e client remoti restino coerenti.

8. Ulteriori approfondimenti

Esegui flussi personalizzati da Stream Deck o dall'API: trigger con nome, modello iniziale, rilevamento dei flussi, dati aggiuntivi, esempi HTTP/WebSocket/P2P e gesti delle manopole.

Vuoi approfondire?

• Usa Nodi di stato (contatori, interruttori, timer) per tenere traccia del contesto tra gli eventi.
• Combina Variabili e logica per creare sistemi di coda, estrazioni o motori di punteggio.
• Collegati al sistema Punti e ricompense affinché gli spettatori possano attivare intenzionalmente i flussi.
• Usi l’app desktop SSApp? Sblocca Nodi JavaScript personalizzati per logiche arbitrarie non coperte da nodi integrati.
• Controlla il Riferimento degli eventi per una documentazione dettagliata dei payload di tutte le piattaforme.

Questa guida è volutamente autonoma: copiala in locale, adattala al tuo team e continua a sperimentare nell'editor.

9. JavaScript personalizzato Solo SSApp / desktop

Due nodi nell'editor Event Flow consentono di scrivere JavaScript arbitrario eseguito nella sequenza del flusso: Codice personalizzato (Custom Code) (trigger) e Esegui codice personalizzato (Execute Custom Code) (azione). Sono la soluzione per tutto ciò che i nodi integrati non possono esprimere.

Custom Code — Nodo trigger

Trascina Codice personalizzato (Custom Code) dal gruppo Avanzate nel pannello Trigger nell'area di lavoro. Funziona da porta: il flusso prosegue solo quando il codice restituisce true.

Execute Custom Code — Nodo azione

Trascina Esegui codice personalizzato (Execute Custom Code) dal gruppo Integrazioni nel pannello Azioni . Può modificare il messaggio, bloccarlo o aggiungere metadati leggibili dai nodi successivi.

L’oggetto message

Entrambi i nodi ricevono il payload completo dell'evento come message. I campi qui sotto sono sempre disponibili; gli eventi specifici delle piattaforme possono includerne altri.

Cosa restituisce l'azione

Restituisci un oggetto semplice dal codice dell'azione. Tutti i campi inclusi vengono uniti all’oggetto result ; i campi omessi conservano i valori attuali.

Frammenti di esempio

Copia uno di questi esempi nel campo JavaScript Code del tipo di nodo corrispondente.

Frammenti di trigger — restituisci true per continuare il flusso

Frammenti di azione — restituisci { modified, message }

Esempio completo — bot di richieste di funzionalità per VIP

Questo flusso ascolta !feature <text> da abbonati, VIP o moderatori, lo riformatta come richiesta di funzionalità e lo inoltra a una seconda destinazione (ad esempio Discord).

Passaggio 1 — Trigger Custom Code (incolla nel campo JavaScript Code del trigger):

Passaggio 2 — Azione Execute Custom Code (incolla nel campo JavaScript Code dell'azione):

Passaggio 3 — Azione Relay Chat: aggiungi un normale nodo Relay Chat dopo l'azione e configuralo per la destinazione Discord (o un'altra). Qui non serve codice personalizzato: il campo riformattato message.chatmessage passa automaticamente.

Considerazioni sulla sicurezza

• Nessuna sandbox di rete. Il codice di un'azione può chiamare fetch(). Se accetti flussi condivisi da altri, esamina il JavaScript prima di attivarli.
• Gli errori vengono intercettati. Un errore di esecuzione nel codice restituisce false (trigger) oppure un'operazione nulla (azione) e scrive nella console DevTools: il flusso non si arresta in modo anomalo.
• Anche gli errori di sintassi. Un errore di tipo SyntaxError in fase di compilazione viene intercettato allo stesso modo. Controlla DevTools (F12) se un nodo sembra non fare nulla.