Integrazione del widget di segnalazione Comuni-Chiamo

Ultimo aggiornamento: 06 Novembre 2025

Codice di inserimento del widget

Per integrare il widget, è necessario inserire il seguente codice HTML all'interno del tag <body> della pagina web, nel punto esatto in cui si desidera visualizzarlo.

Updated Si raccomanda di importare il widget come modulo JavaScript (type="module") anziché come script tradizionale (type="text/javascript") per garantire una migliore gestione delle dipendenze e dello scope, oltre a un caricamento più performante. 

  <!-- Contenitore del widget -->
  <div id="ID-DEL-CONTENITORE-DEL-WIDGET"></div>

  <!-- Configurazione -->
  <script type="text/javascript">
    window.ccWidgetReportingConf = {
      targetId: "ID-DEL-CONTENITORE-DEL-WIDGET",
      apiKey: "TUA-API-KEY"
    };
  </script>

  <!-- JS -->
  <script type="module" src="URL-DELLA-CDN-DEL-WIDGET" async></script>
Nota importante: qualora nel sito sia già in uso la libreria JavaScript di Bootstrap Italia, è fondamentale che il suo tag <script> sia posizionato prima di quello del widget. Il widget rileva la presenza della libreria per evitare di importarla una seconda volta, prevenendo così potenziali conflitti.

URL della CDN

Sono disponibili due approcci alternativi per l'URL di integrazione del widget tramite CDN:

  • URL con versione specifica: questo approccio garantisce che la versione del widget non cambi inaspettatamente. Sarà responsabilità dell'integratore aggiornare manualmente l'URL per passare a versioni future.
    • 
# CDN con versione esplicitata
https://cdn-embed.comuni-chiamo.com/prod/1.4.3/js/main.min.js
  • URL con tag "latest": questo approccio garantisce l'utilizzo automatico dell'ultima versione stabile (aggiornamenti di tipo minor e patch). Gli aggiornamenti major, che potrebbero includere modifiche sostanziali (breaking changes), richiederanno un aggiornamento manuale dell'URL.
    • 
# CDN latest (versioni >= 1.0.0 e < 2.0.0)
https://cdn-embed.comuni-chiamo.com/prod/v1/latest/js/main.min.js

Configurazione del widget

L'oggetto di configurazione window.ccWidgetReportingConf prevede due parametri obbligatori e diversi parametri opzionali per personalizzare il comportamento e l'aspetto del widget.

Parametri obbligatori

Gli unici parametri obbligatori sono:

  • targetId → l’ID del <div> in cui il widget verrà mostrato; questo ID potete sceglierlo voi senza nessuna restrizione.
  • apiKey → la chiave API fornita da Comuni-Chiamo, necessaria per autorizzare le chiamate e utilizzare le funzionalità del widget.

Parametri opzionali

Oltre ai parametri obbligatori, è possibile utilizzare i seguenti campi opzionali per personalizzare il widget:

  • ui → un dizionario che contiene diversi parametri legati alla resa grafica del widget (come ad esempio il colore principale);
  • labels → un dizionario in cui è possibile sovrascrivere alcuni dei testi configurati dal widget (come ad esempio i testi relativi al caricamento degli allegati);
  • prefix → valore testuale che, se inizializzato, viene aggiunto come prefisso a tutti gli ID degli elementi HTML all’interno del widget; questo parametro è pensato per darvi la possibilità di specificare un prefisso univoco per il widget ed evitare che ci siano sovrapposizioni di ID tra gli elementi all’interno del widget e tutti gli elementi della pagina in cui esso viene inserito;
  • autoInit → valore booleano che attivare/disattivare l’inizializzazione automatica del widget nel momento in cui si importa la CDN; di default è true.

CSP (Content Security Policy) del sito

ATTENZIONE: questa parte non è necessaria per il funzionamento del widget.

Se il sito in cui si integra il widget utilizza una Content Security Policy (CSP), è necessario estendere le direttive per autorizzare il caricamento delle risorse esterne richieste dal widget. In caso contrario, il browser potrebbe bloccarne il funzionamento.


  <!-- Esempio di CSP da integrare alla propria CSP già esistente -->
  <meta http-equiv="Content-Security-Policy" content="
    ...altre direttive già presenti...
    script-src ...altre direttive già presenti... cdn-embed.comuni-chiamo.com 'unsafe-inline';
    style-src ...altre direttive già presenti... cdn-embed.comuni-chiamo.com 'unsafe-inline';
    img-src ...altre direttive già presenti... cdn-embed.comuni-chiamo.com data:;
    font-src ...altre direttive già presenti... cdn-embed.comuni-chiamo.com data:;
    connect-src ...altre direttive già presenti... *.comuni-chiamo.com;
    frame-src ...altre direttive già presenti... cdn-embed.comuni-chiamo.com;
    ">

UI

I parametri di personalizzazione dell'interfaccia utente (UI) disponibili sono:

  • primaryColor: permette di specificare un colore (in formato esadecimale, es. "#FF33CB") che verrà utilizzato come colore principale per i componenti del widget, al fine di allineare il suo aspetto grafico a quello del sito ospitante. Una lista dei colori consigliati è disponibile qui: Palette colori Widget.
  • fullWidth: un parametro booleano che, se impostato a true, permette al widget di occupare il 100% della larghezza del suo contenitore.

Etichette (Labels)

È possibile personalizzare alcuni testi (etichette) mostrati dal widget. Le chiavi disponibili sono:

Form disservizio (chiave report):

  • category: etichetta per la selezione della categoria (valore predefinito: "Categoria:").
  • subcategory: etichetta per la selezione della tipologia (valore predefinito: "Tipologia:").
  • title: etichetta per l'oggetto del disservizio (valore predefinito: "Titolo:").
  • description: etichetta per la descrizione del disservizio (valore predefinito: "Dettagli:").

Area per allegare immagini e file (chiave upload):

  • title: titolo del box di caricamento (valore predefinito: "Immagini / Files").
  • area: testo descrittivo all'interno del box (valore predefinito: "Trascina qui le tue immagini o i tuoi file oppure clicca su questa area per caricarli").
  • button: testo del pulsante di caricamento (valore predefinito: "Carica immagine o file").
  • description: testo di aiuto mostrato sotto il box (valore predefinito: "Seleziona una o più immagini o files da allegare alla segnalazione").
  • loader: testo mostrato durante il caricamento (valore predefinito: "Caricamento in corso...").

Form segnalatore (chiave auth):

  • title: titolo della pagina di autenticazione (valore predefinito: "Autenticazione").
  • subtitle: sottotitolo della pagina (valore predefinito: "Informazioni su di te").

Precompilazione dati utente (User)

Se i dati del segnalatore sono già noti (ad esempio, perché l'utente è autenticato sul sito), è possibile precompilare i campi del widget utilizzando l'oggetto user. I campi disponibili sono:

  • firstname: Nome del segnalatore.
  • lastname: Cognome del segnalatore.
  • email: Indirizzo email del segnalatore.
  • phone: Numero di telefono del segnalatore.
  • fiscalcode: Codice Fiscale del segnalatore.

Esempi di codice con parametri opzionali

  1. Personalizzazione del colore e del prefisso ID

    In questo esempio, si imposta un colore primario personalizzato e un prefisso per gli ID degli elementi HTML per evitare conflitti.

    
  <div id="ID-DEL-CONTENITORE-DEL-WIDGET"></div>
  <script type="text/javascript">
    window.ccWidgetReportingConf = {
      targetId: "ID-DEL-CONTENITORE-DEL-WIDGET",
      apiKey: "TUA-API-KEY",
      prefix: "mio-prefisso-univoco",
      ui: {
        primaryColor: "#FF33CB"
      }
    };
  </script>
  <script type="module" src="URL-DELLA-CDN-DEL-WIDGET" async></script>
  2. Widget a larghezza piena

    Oltre al colore, si imposta il widget perché occupi il 100% della larghezza del suo contenitore tramite il parametro fullWidth.

    
  <div id="ID-DEL-CONTENITORE-DEL-WIDGET"></div>
  <script type="text/javascript">
    window.ccWidgetReportingConf = {
      targetId: "ID-DEL-CONTENITORE-DEL-WIDGET",
      apiKey: "TUA-API-KEY",
      ui: {
        primaryColor: "#FF33CB",
        fullWidth: true
      }
    };
  </script>
  <script type="module" src="URL-DELLA-CDN-DEL-WIDGET" async></script>
  3. Personalizzazione dei testi

    In questo esempio vengono personalizzati i testi dell'area di caricamento file e del modulo di autenticazione.

    
  <div id="ID-DEL-CONTENITORE-DEL-WIDGET"></div>
  <script type="text/javascript">
    window.ccWidgetReportingConf = {
      targetId: "ID-DEL-CONTENITORE-DEL-WIDGET",
      apiKey: "TUA-API-KEY",
      labels: {
        upload: {
          title: "Allega documenti",
          area: "Trascina qui i tuoi file",
          button: "Carica file"
        },
        auth: {
          title: "Identificazione",
          subtitle: "Compila con i tuoi dati"
        }
      }
    };
  </script>
  <script type="module" src="URL-DELLA-CDN-DEL-WIDGET" async></script>
  4. Precompilazione parziale dei dati utente

    Se l'utente è già autenticato nel sito, è possibile passare i suoi dati al widget per precompilare i campi.

    
  <div id="ID-DEL-CONTENITORE-DEL-WIDGET"></div>
  <script type="text/javascript">
    window.ccWidgetReportingConf = {
      targetId: "ID-DEL-CONTENITORE-DEL-WIDGET",
      apiKey: "TUA-API-KEY",
      user: {
        firstname: "Mario",
        lastname: "Rossi",
        email: "mario.rossi@example.com"
      }
    };
  </script>
  <script type="module" src="URL-DELLA-CDN-DEL-WIDGET" async></script>
  5. Inizializzazione manuale

    Il widget viene inizializzato manualmente dopo il caricamento completo della pagina impostando autoInit: false. Importante: in questo caso, la CDN deve essere importata in modo sincrono (rimuovendo l'attributo async).

    
  <div id="ID-DEL-CONTENITORE-DEL-WIDGET"></div>
  <script type="text/javascript">
    window.ccWidgetReportingConf = {
      targetId: "ID-DEL-CONTENITORE-DEL-WIDGET",
      apiKey: "TUA-API-KEY",
      autoInit: false
    };
  </script>
  <script type="module" src="URL-DELLA-CDN-DEL-WIDGET"></script>
  <script type="text/javascript">
    window.onload = function () {
      window.ccWidgetReporting.init();
    }
  </script>

File allegabili alla segnalazione

Per garantire la sicurezza e l'efficienza del servizio, l'area di caricamento degli allegati presenta le seguenti limitazioni tecniche:

  • limite sul tipo di file: possono essere allegate immagini o PDF, nello specifico tutti quei file che rispettano uno dei seguenti MIME types: "image/*,application/pdf";
  • limite sulla dimensione: vengono accettati soltanto file la cui dimensione è pari o inferiore a 50 MB.

Inoltre, tutti i file caricati vengono sottoposti a una scansione antivirus lato server prima di essere processati.