Panoramica del Sistema
PROMIUM FORM AI è un sistema di enhancement intelligente che sostituisce dinamicamente i form di contatto esistenti con un’interfaccia conversazionale alimentata da AI. Il sistema opera attraverso un’architettura modulare che rileva automaticamente i form specificati e li sostituisce con un’interfaccia textarea avanzata, supportando input personalizzati, feedback interattivo e gestione avanzata delle risposte con citazioni. Il sistema mantiene la compatibilità con l’ecosistema web esistente e include funzionalità di fallback automatico.
Requisiti di Sistema
Il sistema richiede un browser moderno con supporto per JavaScript ES6+, incluse le API Fetch e Crypto SubtleCrypto per l’autenticazione sicura. È necessario che il DOM sia completamente caricato prima dell’inizializzazione del sistema. Il sistema è compatibile con tutti i principali framework CSS e non interferisce con le librerie JavaScript esistenti. Supporta il rilevamento automatico dell’indirizzo IP per funzionalità di logging avanzato.
Parametrizzazione dello Script
Per implementare PROMIUM FORM AI nel tuo sito web, devi configurare lo script con i parametri appropriati attraverso gli attributi data del tag script. Il sistema supporta ora parametri avanzati per la personalizzazione completa dell’interfaccia, inclusa la personalizzazione delle etichette dei pulsanti e l’integrazione avanzata con i form esistenti.
Parametro data-company (Obbligatorio) Questo parametro identifica la tua organizzazione nel sistema PROMIUM. Il valore deve essere una stringa alfanumerica senza spazi, tipicamente il nome della tua azienda in formato slug (es: “mia-azienda”, “tech-solutions”, “consulting-firm”). Questo parametro influenza il comportamento dell’AI e le risposte contestuali fornite agli utenti.
Parametro data-form-id (Obbligatorio) Specifica l’ID HTML del form che deve essere sostituito dall’interfaccia AI. Il valore deve corrispondere esattamente all’attributo id del form esistente nel tuo HTML. Il sistema utilizzerà questo identificatore per localizzare e sostituire il form target.
Parametro data-label (Opzionale) Permette di personalizzare il testo dell’etichetta della textarea principale. Se non specificato, il sistema utilizzerà il testo predefinito “Richiesta al nostro Team AI”. Questo parametro consente di adattare l’interfaccia al contesto specifico del tuo sito web.
Personalizzazione Pulsanti di Feedback
Parametro data-btn-satisfied (Opzionale) Personalizza il testo del pulsante di soddisfazione che appare dopo la risposta dell’AI. Il valore predefinito è “Sono soddisfatto”. Questo parametro permette di adattare il linguaggio ai tuoi utenti specifici (es: “Perfetto!”, “Ottima risposta”, “Risolto”).
Parametro data-btn-not-satisfied (Opzionale) Personalizza il testo del pulsante di insoddisfazione che permette di tornare al form con i valori salvati. Il valore predefinito è “Non sono soddisfatto”. Puoi personalizzarlo con testi come “Prova ancora”, “Modifica richiesta”, “Riprova”.
Parametro data-btn-back (Opzionale) Personalizza il testo del pulsante che riporta all’interfaccia di input iniziale. Il valore predefinito è “Torna alla richiesta iniziale”. Esempi di personalizzazione: “Nuova richiesta”, “Ricomincia”, “Reset”.
Integrazione Avanzata con Form Esistenti
Parametro data-inputmessagename (Opzionale) Specifica il nome (attributo “name”) di un campo nel form originale dove iniettare automaticamente il contenuto della textarea principale quando l’utente clicca “Non sono soddisfatto”. Questa funzionalità permette di trasferire il messaggio principale dell’utente in un campo specifico del form originale, facilitando la modifica e il reinvio della richiesta attraverso il sistema tradizionale del sito web.
Input Personalizzati Avanzati
Il sistema supporta la creazione di input personalizzati che vengono visualizzati sopra la textarea principale. Questi input permettono di raccogliere informazioni specifiche prima della richiesta AI.
Configurazione Input Personalizzati Per aggiungere input personalizzati, utilizza i parametri data-addinput[numero] per il testo dell’etichetta e data-addinput[numero]_name per il nome del campo. Il sistema supporta input multipli numerati sequenzialmente (data-addinput1, data-addinput2, etc.).
Gestione Valori Input I valori degli input personalizzati vengono automaticamente memorizzati e mantenuti durante l’interazione con l’AI. In caso di insoddisfazione dell’utente, i valori vengono ripristinati per facilitare la modifica della richiesta.
Implementazione nel Codice HTML
La configurazione richiede l’inserimento di un singolo tag script con i parametri specificati. Ecco esempi di implementazione base e avanzata:
Sicurezza e Protezione del Codice
Nonostante l’implementazione sia basata su JavaScript, PROMIUM FORM AI rispetta i più alti standard qualitativi di protezione del codice. Il sistema include offuscamento avanzato del codice sorgente, minificazione ottimizzata per ridurre la superficie di attacco, e sistemi di protezione interni di livello enterprise come il domain-lock per prevenire utilizzi non autorizzati. Queste misure garantiscono che il codice rimanga protetto anche in ambienti client-side, mantenendo l’integrità e la sicurezza del sistema.
Implementazione Base:
<script
src="https://promium-embed.s3.amazonaws.com/promium_contact_form/contactformexternal.min.js"
data-company="tua-azienda"
data-form-id="contact-form-original">
</script>
Implementazione Avanzata con Input Personalizzati:
<script
src="https://promium-embed.s3.amazonaws.com/promium_contact_form/contactformexternal.min.js"
data-company="tech-solutions"
data-form-id="contact-form"
data-label="Descrivi il tuo progetto"
data-addinput1="Nome Azienda"
data-addinput1_name="company_name"
data-addinput2="Budget Previsto"
data-addinput2_name="budget">
</script>
Implementazione Completa con Personalizzazione Avanzata:
<script
src="https://promium-embed.s3.amazonaws.com/promium_contact_form/contactformexternal.min.js"
data-company="consulting-firm"
data-form-id="contact-form"
data-label="Descrivi la tua esigenza di consulenza"
data-addinput1="Settore di Attività"
data-addinput1_name="business_sector"
data-addinput2="Urgenza del Progetto"
data-addinput2_name="urgency"
data-btn-satisfied="Perfetto!"
data-btn-not-satisfied="Modifica richiesta"
data-btn-back="Nuova richiesta"
data-inputmessagename="message">
</script>
Posizionamento del Script Il tag script deve essere posizionato dopo la dichiarazione del form HTML che si intende sostituire. Si consiglia di inserirlo prima del tag di chiusura </body> per garantire che il DOM sia completamente caricato al momento dell’esecuzione.
Struttura del Form Originale Il form originale deve essere presente nel DOM con l’ID specificato nel parametro data-form-id. La struttura interna del form non è rilevante per il funzionamento del sistema, in quanto l’intero contenuto verrà sostituito dinamicamente.
Processo di Inizializzazione
Il sistema implementa un pattern di inizializzazione differita che attende il completo caricamento del DOM. Durante questa fase, vengono eseguiti diversi controlli di validazione per verificare la presenza e la correttezza dei parametri di configurazione, inclusa la rilevazione automatica degli input personalizzati.
Il sistema localizza automaticamente il form target utilizzando l’ID specificato, rileva gli input personalizzati dai data-attributes e procede con la sostituzione dell’interfaccia. Viene mantenuto un riferimento al contenuto HTML originale per consentire il ripristino in caso di necessità o insoddisfazione dell’utente.
Architettura dell’Interfaccia
L’interfaccia sostituita include diversi componenti modulari: un’area per input personalizzati, un’area di input testuale principale con etichetta personalizzabile, un sistema di indicatori di caricamento con spinner animato, un contenitore per le risposte dell’AI con supporto per citazioni e link, e controlli avanzati per il feedback dell’utente. Ogni componente è gestito attraverso un sistema di stati che controlla la visibilità e l’interattività degli elementi.
Sistema di Feedback Interattivo
Il sistema include un meccanismo di feedback avanzato che permette agli utenti di esprimere la loro soddisfazione riguardo alla risposta ricevuta. Dopo ogni risposta dell’AI, vengono presentati tre pulsanti completamente personalizzabili: il pulsante di soddisfazione (predefinito “Sono soddisfatto”), il pulsante di insoddisfazione (predefinito “Non sono soddisfatto”) e il pulsante di ritorno (predefinito “Torna alla richiesta iniziale”).
In caso di soddisfazione, viene mostrato un messaggio di ringraziamento personalizzabile. In caso di insoddisfazione, il sistema ripristina l’interfaccia di input mantenendo i valori degli input personalizzati per facilitare la modifica della richiesta. Se configurato il parametro data-inputmessagename, il contenuto della textarea principale viene automaticamente iniettato nel campo specificato del form originale, permettendo una transizione fluida tra l’interfaccia AI e il form tradizionale. Il pulsante di ritorno permette di tornare all’interfaccia di input in qualsiasi momento con un reset completo.
Gestione Avanzata dei Valori del Form
Il sistema implementa una gestione intelligente dei valori che distingue tra due scenari di utilizzo: quando l’utente seleziona “Non sono soddisfatto”, il sistema mantiene tutti i valori degli input personalizzati e, se configurato, inietta il messaggio principale nel campo specificato del form originale attraverso l’attributo “name”. Questo permette agli utenti di modificare la loro richiesta mantenendo il contesto già inserito. Quando l’utente seleziona “Torna alla richiesta iniziale”, il sistema esegue un reset completo dell’interfaccia, cancellando tutti i valori e ripartendo da zero.
La funzionalità di iniezione del messaggio principale è particolarmente utile per siti web che vogliono offrire un’esperienza ibrida, permettendo agli utenti di iniziare con l’AI e poi passare al form tradizionale mantenendo il contenuto già elaborato. Il sistema gestisce automaticamente diversi tipi di input, inclusi campi di testo, textarea, checkbox e radio button, garantendo compatibilità con la maggior parte delle implementazioni di form esistenti.
Gestione delle Citazioni e Fonti
Il sistema supporta la visualizzazione automatica di citazioni e fonti nelle risposte dell’AI. Quando l’AI fornisce una risposta che include riferimenti a fonti esterne, il sistema aggiunge automaticamente una sezione “Fonti” con link cliccabili alle risorse referenziate.
Le citazioni vengono formattate con numerazione progressiva e i link si aprono in una nuova finestra con attributi di sicurezza appropriati (target=”_blank” rel=”noopener noreferrer”) per garantire la sicurezza della navigazione.
Gestione degli Stili
Il sistema inietta dinamicamente fogli di stile CSS ottimizzati per garantire un’esperienza utente coerente e moderna. Gli stili includono animazioni per lo spinner di caricamento, transizioni fluide per i pulsanti, e un design responsive che si adatta a diverse dimensioni di schermo. Gli stili sono progettati per integrarsi armoniosamente con la maggior parte dei framework CSS esistenti, utilizzando selettori specifici per evitare conflitti.
Comunicazione con l’API
Il sistema implementa un protocollo di comunicazione sicuro con l’infrastruttura PROMIUM. Una parte significativa della protezione di PROMIUM si basa su sofisticati algoritmi SHA-256 e password auto-generate basate sul tempo, garantendo un livello di sicurezza enterprise senza richiedere configurazioni complesse da parte dell’utente.
La comunicazione include il rilevamento automatico dell’indirizzo IP dell’utente per scopi di logging e sicurezza, utilizzando il servizio https://api.ipify.org. Il sistema supporta risposte multilingua con il parametro contactformreplylang impostato su ‘italian’ per default.
Gestione degli Errori e Fallback
Il sistema include meccanismi robusti di gestione degli errori che intercettano condizioni anomale e forniscono fallback appropriati. Gestisce specificamente errori 500 del server con messaggi informativi per l’utente, timeout dell’agente AI con suggerimenti per riformulare la richiesta, e errori di rete generici con messaggi di errore chiari.
In caso di indisponibilità del servizio AI o errori critici, il sistema può automaticamente ripristinare il form originale per garantire continuità operativa. Gli errori vengono visualizzati con styling appropriato per distinguere tra errori, avvisi e messaggi informativi.
Logging e Debugging
Per facilitare il debugging e il monitoraggio, il sistema implementa un sistema di logging avanzato che fornisce informazioni dettagliate sui processi interni. I log sono strutturati e colorati per facilitare l’identificazione rapida di problemi o anomalie, includendo log specifici per la risposta completa dell’AI, i documenti sorgente, le citazioni e la gestione degli errori.
Il sistema include anche funzionalità di test per richieste cross-origin e monitoraggio delle prestazioni di rete. Tutti i log sono accessibili attraverso la console del browser per sviluppatori e amministratori di sistema.
Considerazioni sulla Sicurezza
Il sistema implementa diverse misure di sicurezza avanzate, inclusa la validazione dei parametri di input, la sanitizzazione dei dati utente e l’utilizzo di protocolli di comunicazione crittografati. L’autenticazione utilizza un sistema di password temporali basato su hash SHA-256 che si rinnova quotidianamente, garantendo sicurezza senza richiedere configurazioni complesse da parte dell’utente.
I link esterni nelle citazioni vengono aperti con attributi di sicurezza appropriati per prevenire attacchi di tipo tabnabbing. Tutti i dati sensibili vengono gestiti secondo le best practice di sicurezza web e non vengono mai esposti nei log del browser.
Compatibilità e Limitazioni
Il sistema è progettato per funzionare con la maggior parte delle configurazioni web moderne e supporta tutti i principali browser che implementano le API ES6+, Fetch e Crypto SubtleCrypto. Tuttavia, potrebbero esistere limitazioni in ambienti con restrizioni JavaScript severe o in presenza di Content Security Policy particolarmente restrittive che bloccano le richieste verso domini esterni.
Il sistema richiede connettività internet per il funzionamento dell’AI e per il rilevamento dell’indirizzo IP. In caso di connettività limitata, il sistema fornisce messaggi di errore appropriati e fallback al form originale quando possibile.
Ottimizzazione delle Prestazioni
Il sistema è ottimizzato per minimizzare l’impatto sulle prestazioni del sito web. Utilizza tecniche di lazy loading per l’inizializzazione, gestione efficiente della memoria per gli input personalizzati, e caricamento asincrono delle risorse esterne. Il sistema include indicatori di caricamento visivi per migliorare l’esperienza utente durante le operazioni di rete.
Le animazioni CSS sono ottimizzate per prestazioni fluide anche su dispositivi con risorse limitate, e il sistema implementa debouncing per le interazioni utente per evitare richieste eccessive al server. La gestione degli stati è ottimizzata per ridurre al minimo i reflow e repaint del DOM.
Funzionalità Avanzate e Personalizzazione
Il sistema supporta personalizzazione avanzata attraverso i data-attributes, permettendo di adattare completamente l’interfaccia alle esigenze specifiche del sito web. Gli input personalizzati possono essere utilizzati per raccogliere informazioni specifiche del dominio che verranno incluse nel contesto della richiesta AI. Inoltre, il sistema ora supporta la personalizzazione completa delle etichette dei pulsanti di feedback, permettendo di adattare il linguaggio e il tono dell’interfaccia al brand e al target di utenti specifico.
Il sistema mantiene lo stato degli input durante l’intera sessione di interazione, permettendo agli utenti di modificare e rifinire le loro richieste senza perdere le informazioni già inserite. Questa funzionalità è particolarmente utile per form complessi che richiedono multiple iterazioni per ottenere la risposta desiderata. La nuova funzionalità di integrazione avanzata con i form esistenti permette di creare un ponte seamless tra l’esperienza AI e i sistemi di form tradizionali, offrendo agli utenti la flessibilità di scegliere il metodo di interazione più adatto alle loro esigenze.
Personalizzazione Completa dell’Interfaccia
Attraverso i nuovi parametri di personalizzazione, è possibile creare esperienze utente completamente personalizzate che riflettono l’identità del brand. I parametri data-btn-satisfied, data-btn-not-satisfied e data-btn-back permettono di definire etichette personalizzate per i pulsanti di feedback, mentre il parametro data-inputmessagename abilita l’integrazione bidirezionale con i form esistenti.
Questa architettura modulare permette implementazioni che vanno dalla semplice sostituzione del form fino a complessi workflow ibridi dove l’AI funge da assistente intelligente per la compilazione di form tradizionali. Il sistema è progettato per essere retrocompatibile, garantendo che le implementazioni esistenti continuino a funzionare senza modifiche mentre offrono la possibilità di sfruttare le nuove funzionalità avanzate.
