Skip to main content

Notifiche Template

🚧 BOZZA

Le notifiche template rappresentano notifiche generiche riutilizzabili utilizzate per inviare notifiche effettive.

🤔 Dubbi/Cose nuove da considerare​

  • Capire come gestire le versioni del template di notifica.
  • Valutare l'implementazione di A/B testing per i contenuti.

🧠 Concetti chiave​

Le notifiche template rappresentano notifiche generiche riutilizzabili che definiscono la struttura e il contenuto delle notifiche da inviare. Sono configurabili e memorizzate nel database, permettendo di modificare i contenuti senza dover cambiare il codice.

Ogni notifica template è composta da codice, titolo, tipo, canali, variabili e URL di redirect:

  • Il codice è un identificatore univoco del template (es. user_registered, contract_signed). Viene usato per caricare il template dal database.
  • Il titolo è il titolo generale della notifica, visibile all'utente.
  • Il tipo definisce la natura della notifica:
    • ToDo: Notifiche che richiedono un'azione da parte dell'utente
    • Info: Notifiche informative che non richiedono azioni
  • I canali definiscono attraverso quali mezzi viene inviata la notifica (Email, Push). Ogni canale può essere abilitato/disabilitato indipendentemente.
  • Le variabili sono campi dinamici che possono essere utilizzati nei contenuti. Le variabili sono associate al template e possono essere di diverse categorie (es. core, project, customer, company, user, contract, ecc.) e tipi di input (es. text, email, date, currency, boolean, ecc.).
  • L'URL di redirect è l'indirizzo a cui viene reindirizzato l'utente quando clicca sulla notifica. Può contenere variabili dinamiche (es. https://app.com/contracts/{{contract_id}}).

Canali di notifica​

Ogni template può avere uno o più canali configurati. Ogni canale definisce:

  • Il tipo di canale (Email o Push)
  • Il titolo specifico per quel canale (può essere diverso dal titolo generale)
  • Il corpo del messaggio, che può contenere HTML e placeholder per variabili (formato: <span>@nome_variabile</span>)
  • I destinatari, specificati come ruoli (es. admin, customer, supplier). Il sistema risolve automaticamente tutti gli utenti con quei ruoli usando Spatie Permission.
  • Lo stato (abilitato/disabilitato) che determina se il canale è attivo
  • Per il canale Email:
    • Subject: L'oggetto dell'email
    • CTA Name: Il nome del pulsante call-to-action (es. "Visualizza contratto", "Conferma")
  • Per il canale Push:
    • La notifica può essere salvata nel database (database)
    • Inviata in real-time via Pusher (pusher)
    • Entrambi (both)

In piattaforma è possibile creare e modificare le notifiche template:

  • In fase di creazione e modifica è possibile definire il codice, il tipo, configurare i canali desiderati, associare le variabili e definire l'URL di redirect.
  • All'interno dei contenuti dei canali è possibile utilizzare formattazione HTML e richiamare le variabili associate usando il formato <span>@nome_variabile</span>.

In piattaforma è possibile visualizzare le variabili disponibili per i template. Le variabili sono organizzate per categoria e hanno un tipo di input specifico che determina come verranno valorizzate.

Logiche rilevanti
  • Le variabili disponibili per il template sono quelle presenti nel database, create precedentemente lato codice.
  • Le variabili possono avere diverse categorie che ne determinano la provenienza dei dati (es. core per dati di sistema, customer per dati cliente, project per dati commessa, ecc.).
  • Ogni variabile associata al template può essere utilizzata nei contenuti dei canali usando la sintassi <span>@nome_variabile</span>.
  • I destinatari sono definiti come ruoli. Il sistema risolve automaticamente tutti gli utenti con quei ruoli al momento dell'invio.
  • Il campo channels della tabella nt_notification_templates viene sincronizzato automaticamente quando si modificano i canali associati. Contiene un array JSON con i tipi dei canali abilitati.
  • DA APPROVARE: Ad ogni modifica del template, potrebbe essere necessario salvare una nuova versione. Le versioni precedenti sarebbero visibili e ripristinabili.

⚙️ Logiche sotto il cofano​

Entità coinvolte​

Le entità strettamente coinvolte nelle notifiche template sono:

  • nt_notification_templates: in questa entità vengono salvati i template di notifica. Campi principali:

    • code: codice univoco per identificare il template (es. user_registered)
    • title: titolo generale della notifica
    • type: tipo di notifica (to_do, info)
    • channels: array JSON dei canali abilitati (sincronizzato automaticamente)
    • redirect_url: URL di redirect con eventuale placeholder variabili

  • nt_notification_template_channels: in questa entità vengono salvati i canali di ogni template. Campi principali:

    • nt_notification_template_id: riferimento al template
    • type: tipo di canale (email, push)
    • title: titolo specifico per il canale
    • body: corpo del messaggio in formato HTML con placeholder variabili
    • recipients: array JSON di ruoli destinatari (es. ["admin", "customer"])
    • subject: oggetto dell'email (solo per tipo Email)
    • cta_name: nome del pulsante CTA
    • status: boolean che indica se il canale è abilitato

  • nt_variable_templates: in questa entità vengono salvate le variabili disponibili per tutta la piattaforma. Campi principali:

    • name: nome della variabile
    • slug: slug identificativo usato nei placeholder
    • category: categoria della variabile (core, project, customer, company, user, contract, ecc.)
    • type: tipo di input della variabile (text, email, date, currency, boolean, ecc.)
    • description: descrizione della variabile
    • placeholder: testo di esempio

  • nt_notification_variable_template: in questa entità viene salvata la relazione tra template di notifica e variabili, definendo quali variabili sono disponibili per ogni template.

Sincronizzazione automatica dei canali​

Quando si modificano i canali associati a un template (abilitazione/disabilitazione, aggiunta/rimozione), il campo channels della tabella nt_notification_templates viene sincronizzato automaticamente:

  1. L'evento saving del model viene triggerato
  2. Il metodo syncChannels() recupera tutti i canali abilitati (con status = true)
  3. Estrae i tipi dei canali (email, push)
  4. Aggiorna il campo channels con l'array JSON
  5. Usa updateQuietly() per evitare loop infiniti

Questo meccanismo garantisce che il campo channels sia sempre allineato con i canali effettivamente configurati e attivi.

Convenzione nome classe → code template​

Quando si usa NtNotificationService::send() con una classe di notifica, il sistema carica automaticamente il template usando una convenzione:

Classe: UserRegisteredNotification
Code:   user_registered

Classe: ContractSignedNotification
Code:   contract_signed

Classe: ProjectCompletedNotification
Code:   project_completed

La conversione avviene così:

  1. Estrae il nome della classe senza namespace
  2. Rimuove "Notification" dalla fine
  3. Converte da PascalCase a snake_case

Questo permette di non dover specificare esplicitamente il template ogni volta che si invia una notifica.