Widget su misura in Zoho CRM: quando conviene, in breve
Un widget su misura in Zoho CRM conviene quando né la configurazione standard né un'estensione già pronta mostrano o raccolgono un dato nel punto esatto del processo in cui serve. Se bastano un campo, un layout, una regola workflow o un Blueprint, il widget diventa solo codice in più da mantenere.
Un widget di Zoho CRM è un componente personalizzato che si aggiunge al CRM per estenderne le funzioni, mostrare dati aggiuntivi o collegare servizi esterni. Questa è la definizione che Zoho stessa dà nella sua guida Kaizen #95 sui widget nei Blueprint. Si sviluppa con il widget SDK di Zoho, cioè il kit di sviluppo che permette di integrare applicazioni web direttamente nel CRM.
La regola pratica è semplice. Prima si esaurisce ciò che il CRM offre senza codice, poi si valuta un'estensione esistente, e solo alla fine si scrive un widget. Quando il widget serve davvero, va progettato fin dall'inizio per essere letto, aggiornato e sostituito da qualcuno che non l'ha scritto.
Questa guida spiega dove può comparire un widget, come scegliere tra le tre strade, come si sviluppa un caso concreto in un Blueprint e quali limiti tecnici rispettare.
Dove può comparire un widget in Zoho CRM
Un widget di Zoho CRM può comparire in molti punti dell'interfaccia, non solo in una scheda dedicata. La pagina di Zoho Kaizen #147 con le domande frequenti sui widget elenca questi punti di inserimento:
- come web tab, cioè una scheda propria nella barra dei moduli;
- al clic su un pulsante;
- come elenco correlato personalizzato nella pagina di un record;
- come elemento di una dashboard;
- nella pagina delle impostazioni;
- durante le transizioni di un Blueprint;
- nelle notifiche dei segnali di vendita;
- come componente di un wizard;
- come estensione di telefonia;
- dentro pop-up e call-out aperti da un Client Script.
La scelta del punto di inserimento è la prima decisione di progetto. Un widget in un elenco correlato viene visto da chiunque apra il record. Un widget in una transizione Blueprint compare solo a chi esegue quel passaggio, nel momento in cui lo esegue.
Il punto di inserimento determina anche quali dati il widget riceve dalla pagina. Per questo conviene deciderlo prima di scrivere una riga di codice, non dopo.
Configurazione standard, estensione del Marketplace o widget: come scegliere
La scelta tra configurazione standard, estensione del Marketplace e widget su misura dipende da quanto è specifico il bisogno e da chi si occuperà della manutenzione. La tabella confronta le tre strade sui criteri che contano per chi decide.
| Criterio | Configurazione standard | Estensione del Marketplace | Widget su misura |
|---|---|---|---|
| Quando usarla | Il bisogno si copre con campi, layout, regole, Blueprint | Un'estensione esistente copre il caso senza forzature | Il dato o l'interazione richiesti non esistono altrove |
| Chi la mantiene | L'amministratore del CRM | L'autore dell'estensione | Chi ha il codice sorgente, interno o esterno |
| Competenze necessarie | Configurazione, nessun codice | Installazione e impostazione | HTML, JavaScript, JS SDK di Zoho |
| Rischio dopo gli aggiornamenti | Basso, gestito da Zoho | Dipende dall'autore | A carico Suo, da verificare a ogni modifica |
| Adattamento al processo | Entro le opzioni disponibili | Entro le opzioni dell'estensione | Completo |
La configurazione standard copre più casi di quanto si pensi. Per esempio, Zoho CRM offre il mascheramento dei campi per nascondere i dati sensibili dei clienti ai team che non ne hanno bisogno, senza alcuno sviluppo. Prima di commissionare un widget, conviene rileggere una checklist di configurazione di Zoho CRM e verificare che l'opzione nativa non esista già.
Segnali che un widget su misura serve davvero
Un widget su misura serve davvero quando un utente deve vedere o decidere qualcosa che le opzioni native non sanno presentare. L'esempio della guida Kaizen #95 lo mostra bene. Le opzioni integrate del Blueprint non possono aprire un pop-up con lo storico dei prestiti precedenti di un cliente, quindi Zoho associa alla transizione un widget personalizzato.
Tre segnali ricorrono spesso:
- l'utente deve consultare dati di più moduli o di un sistema esterno prima di una decisione;
- l'interazione richiede un'interfaccia che i layout non offrono, come una mappa o un dial pad;
- il passaggio deve bloccarsi finché l'utente non ha verificato quei dati.
La telefonia è un caso tipico. Quando un'organizzazione Zoho CRM non dispone di un'estensione di telefonia nativa, i listener Dial e DialerActive permettono di caricare un'app di telefonia di terze parti dentro il widget. Un listener è una funzione che resta in ascolto di un evento della pagina. DialerActive, al clic sull'icona del telefono accanto al numero di un record, carica quel numero sul dial pad esterno.
Al contrario, un widget non serve se il bisogno è solo estetico o se una regola workflow ottiene lo stesso risultato. In quei casi il codice aggiunge rischio senza aggiungere valore.
Esempio pratico: un widget di verifica in una transizione Blueprint
Un widget in una transizione Blueprint è l'esempio più utile per capire il ciclo completo. Un Blueprint di Zoho CRM è uno strumento che definisce un processo a stati: un record passa allo stato successivo solo se soddisfa la condizione prevista, altrimenti resta dov'è. Il pulsante di transizione sta tra due stati, contiene la condizione e guida il flusso.
Il caso della guida Kaizen #95 riguarda la valutazione di una richiesta di prestito. Prima di approvare, l'operatore deve vedere lo storico del cliente. Il widget chiamato "Check Profile" mostra quei dati e, se l'operatore conferma, completa la transizione.
I passaggi in Zoho CRM sono questi:
- aprire Setup > Developer Space > Widgets e scegliere Create New Widget;
- caricare il pacchetto del widget e pubblicarlo;
- aprire il Blueprint e selezionare la transizione interessata;
- nella sezione During della transizione, scegliere Add > Widgets e selezionare "Check Profile";
- salvare e pubblicare il Blueprint, poi provarlo su un record di test.
Dentro il widget, la funzione ZOHO.CRM.BLUEPRINT.proceed() del JS SDK esegue la transizione. Per leggere altri record, il JS SDK offre helper per le API di Zoho CRM. Nell'esempio di Zoho la lettura dei record correlati usa page: 1, per_page: 200, cioè fino a 200 record per pagina.
Il codice minimo di un widget di verifica per il Blueprint
Il codice minimo di un widget di verifica carica il JS SDK, riceve i dati della pagina e completa la transizione al clic. Il file qui sotto va salvato come pagina HTML principale del pacchetto del widget, quello che si carica in Developer Space. Il JS SDK si include con l'URL CDN indicato da Zoho nella sezione head.
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<script src="https://live.zwidgets.com/js-sdk/1.2/ZohoEmbededAppSDK.min.js"></script>
</head>
<body>
<p>Verifica i dati prima di proseguire:</p>
<pre id="dati"></pre>
<button id="conferma">Conferma e prosegui</button>
<script>
// Riceve i dati della pagina, ad esempio modulo e ID del record
ZOHO.embeddedApp.on("PageLoad", function (data) {
document.getElementById("dati").textContent = JSON.stringify(data, null, 2);
});
// Completa la transizione del Blueprint quando l'operatore conferma
document.getElementById("conferma").addEventListener("click", function () {
ZOHO.CRM.BLUEPRINT.proceed();
});
// Avvia la comunicazione tra il widget e Zoho CRM
ZOHO.embeddedApp.init();
</script>
</body>
</html>Le righe da adattare sono poche. Il testo del paragrafo e del pulsante va scritto nella lingua degli operatori. Il blocco PageLoad oggi mostra i dati grezzi della pagina: in un progetto reale lo si sostituisce con la lettura dei record necessari tramite gli helper API del JS SDK. Il gestore del clic è il punto in cui aggiungere eventuali controlli prima di chiamare ZOHO.CRM.BLUEPRINT.proceed().
Widget e Client Script: passare dati e chiudere i pop-up
Un widget di Zoho CRM può essere aperto da un Client Script in un pop-up o in un call-out. Un Client Script è un codice JavaScript che Zoho CRM esegue nel browser in risposta a eventi della pagina, come l'apertura o il salvataggio di un record. La combinazione serve quando il widget deve comparire solo a certe condizioni.
La guida Kaizen #147 descrive tre meccanismi di comunicazione:
- dal Client Script al widget, registrando il listener
NotifyconZOHO.embeddedApp.on; - dal widget al Client Script, registrando il listener
NotifyAndWait, che attende una risposta; - la chiusura del widget al clic di un pulsante, con il metodo
ZOHO.CRM.UI.Popup.close().
Nei Client Script si può usare anche ZRC, cioè Zoho Request Client, un insieme di metodi per effettuare richieste dallo script. Conviene decidere con chiarezza quale dei due componenti esegue le chiamate e quale mostra soltanto l'interfaccia, così da non duplicare la logica.
Un dettaglio utile riguarda la visualizzazione. Zoho ha segnalato come risolto un problema di altezza dei widget nei pop-up e nei flyout aperti da Client Script, come riportato nel thread della community sui widget per dispositivi mobili. Se un widget appariva tagliato in passato, vale la pena ricontrollarlo prima di intervenire sul codice.
Limiti tecnici di un progetto widget: file, dimensioni e framework
Un progetto widget di Zoho CRM ha limiti precisi su numero e dimensione dei file. Secondo la guida Kaizen #147, i valori sono questi:
| Limite | Valore |
|---|---|
| File per progetto | 250 |
| Dimensione massima del progetto | 25 MB |
| Dimensione massima di un singolo file | 5 MB |
I widget di Zoho CRM si possono costruire con qualsiasi framework lato client, React JS compreso. La libertà ha un costo: un framework pesante consuma rapidamente il limite di 25 MB e aggiunge dipendenze da aggiornare. Per un widget di verifica come quello dell'esempio, HTML e JavaScript semplici bastano e restano leggibili.
L'accesso da dispositivi mobili richiede una valutazione a parte. Nel thread della community sui widget per mobile, un utente chiedeva come tenere fuori dal CRM un widget con Google Maps, pensato soprattutto per chi lavora in mobilità, usando comunque il JS SDK per collegarsi al CRM e gestire l'autenticazione. Se il Suo widget servirà agli agenti sul campo, lo provi su telefono fin dal primo prototipo.
Progettare un widget manutenibile: documentazione, interfaccia e responsabilità
Un widget manutenibile è un widget che una persona diversa dall'autore può capire, aggiornare e spegnere senza rischi. Il codice è la parte facile. La parte difficile è sapere, due anni dopo, dove compare il widget, quali dati legge e chi deve intervenire se smette di funzionare.
Per ogni widget, in Svennis prepariamo una breve scheda che indica il punto di inserimento, le API chiamate, i campi letti e scritti e il responsabile della manutenzione. Senza questa scheda vediamo spesso widget che nessuno osa toccare dopo una modifica al modulo da cui dipendono.
Tre scelte di progetto riducono il lavoro futuro:
- un widget con un solo scopo, invece di un pannello che fa tutto;
- un'interfaccia coerente con quella di Zoho, tema su cui gli sviluppatori chiedono indicazioni anche nel thread della community sullo stile dei componenti dei widget;
- il codice sorgente in un archivio dell'azienda, non solo nel pacchetto caricato nel CRM.
Anche lo sviluppo assistito dall'AI va governato. Zoho ha introdotto una skill zoho-crm, un file SKILL.md, che aiuta a lavorare con API, funzioni, widget, Client Script e query in strumenti come Claude Code, Codex, Cursor e VSCode. Il codice generato va comunque revisionato e documentato come quello scritto a mano.
Cosa significa un widget su misura per un'azienda italiana
Per un'azienda italiana, un widget su misura in Zoho CRM ha senso soprattutto quando il processo usa dati esterni al CRM. Il caso più comune è il gestionale. Prima di mostrare giacenze o condizioni commerciali in un widget, si chieda se quei dati debbano invece arrivare nel CRM. In quel caso serve un'integrazione, come l'integrazione tra SAP Business One e Zoho CRM.
La distinzione è importante. Un'integrazione copia i dati nel CRM, dove report e automazioni possono usarli. Un widget li mostra al momento, ma non li rende disponibili al resto del sistema. Se il dato serve a una regola o a un report, il widget da solo non basta.
Il secondo tema è la lingua. Un widget su misura non eredita le traduzioni dell'interfaccia di Zoho. Testi, messaggi di errore e pulsanti vanno scritti in italiano dal progetto stesso. Il terzo tema riguarda i dati personali. Se il widget mostra informazioni sensibili, valuti prima il mascheramento dei campi già disponibile in Zoho CRM. Così il widget non espone ciò che il profilo dell'utente non dovrebbe vedere.
Alcuni settori hanno processi molto specifici, come la gestione commerciale nella manifattura. Lì i widget compaiono più spesso nelle fasi di verifica tecnica che nella vendita vera e propria.
Prossimi passi per decidere e avviare un widget su misura
Il primo passo per decidere su un widget su misura in Zoho CRM è descrivere il bisogno senza parlare di tecnologia. Scriva in una frase quale utente deve vedere o fare cosa, in quale punto del processo e con quali dati.
Poi proceda in quest'ordine:
- verifichi se campi, layout, regole workflow o Blueprint coprono il bisogno;
- cerchi un'estensione esistente e ne valuti l'autore e gli aggiornamenti;
- se resta solo il widget, scelga il punto di inserimento tra quelli elencati da Zoho;
- prepari la scheda con dati letti, API chiamate e responsabile della manutenzione;
- sviluppi un prototipo minimo, come il widget di verifica di questa guida, e lo provi su un record di test.
Se il widget fa parte di un progetto più ampio, conviene inquadrarlo nell'implementazione complessiva di Zoho CRM, insieme a moduli, processi e integrazioni. Nella stessa pagina trova come avviare un confronto sul Suo caso concreto. Se usa anche altri prodotti della suite, la pagina su Zoho CRM Plus aiuta a capire quali funzioni sono già disponibili senza sviluppo.
