Come integrare il widget per le segnalazioni di Comuni-Chiamo sul proprio sito

Ultimo aggiornamento: 12 Marzo 2024

Codice di inserimento del widget

Updated Inserisci questo codice nel <body> nel punto in cui vuoi che appaia il widget.


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

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

  <!-- JS -->
  <script type="text/javascript" src="URL-DELLA-CDN-DEL-WIDGET" async></script>
New Importante: se si utilizza la libreria JS di Bootstrap Italia bisogna importarla prima dello script del widget perchè in quest'ultimo abbiamo implementato un controllo interno che evita di importare due volte la libreria JS di Bootstrap Italia.

URL della CDN

New Sono disponibili due modi alternativi ed entrambi validi per integrare il widget, per quanto riguarda l'url di integrazione troviamo:

  • la CDN con versione esplicitata; in questo caso sarà vostro onere tenere aggiornato il widget all'ultima versione;
    • 
# CDN con versione esplicitata
https://cdn-embed.comuni-chiamo.com/prod/1.1.1/js/main.min.js
  • la CDN con il tag "latest" per avere sempre l'ultima versione disponibile; in questo modo tutti gli aggiornamenti minor e le patch saranno applicati automaticamente, mentre per gli aggiornamenti major si dovrà aggiornare la versione manualmente per evitare malfunzionamenti dovuti a breaking changes.
    • 
# 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

Nel codice di inserimento del widget ci sono solamente due parametri obbligatori, tutti gli altri sono opzionali e possono essere tralasciati.

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 → l’API Key necessaria per l’utilizzo di tutte le funzionalità legate al widget; questa API Key vi verrà fornita da Comuni-Chiamo.

Parametri opzionali

Oltre ai due obbligatori ne esistono anche diversi opzionali con cui è possibile personalizzare il widget, ovvero:

  • 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

Se il sito su cui viene inserito il codice del widget è configurata una CSP, è necessario aggiungere queste risorse alle direttive:


  <meta http-equiv="Content-Security-Policy" content="
    script-src [cdn-embed.comuni-chiamo.com](http://cdn-embed.comuni-chiamo.com/);
    style-src [cdn-embed.comuni-chiamo.com](http://cdn-embed.comuni-chiamo.com/);
    img-src [cdn-embed.comuni-chiamo.com](http://cdn-embed.comuni-chiamo.com/);
    font-src [cdn-embed.comuni-chiamo.com](http://cdn-embed.comuni-chiamo.com/);
    connect-src *.comuni-chiamo.com;
    frame-src [cdn-embed.comuni-chiamo.com](http://cdn-embed.comuni-chiamo.com/);
    ">

UI

L’unico parametro disponibile al momento è il primaryColor con cui è possibile specificare un valore esadecimale che sarà utilizzato appunto come colore principale di tutti i componenti che fanno parte del widget. Strumento utile ad esempio per adeguare il tema del widget al tema della pagina in cui viene embeddato. Una lista dei primaryColor consigliati è disponibile qui: Palette colori Widget.

LABELS

Al momento i valori testuali che possono essere configurati a piacimento riguardano il box in cui poter caricare allegati alla segnalazione, annidati sotto la chiave upload:

  • title: il titolo posto sopra il box (di default è "Immagini");
  • area: la label descrittiva che compare all’interno del box in cui allegare file (di default è "Trascina qui le tue immagini");
  • button: il testo del pulsante usato per allegare file (di default è "Carica immagine");
  • description: il testo mostrato sotto al box in cui allegare file come hint (di default è "Seleziona una o più immagini da allegare alla segnalazione").
  • loader: il testo mostrato durante il caricamento (di default è "Caricamento immagine in corso...");

Oppure la pagina iniziale in cui vengono chiesto i dati dell'utente, annidati sotto la chiave auth:

  • title: il titolo della pagina (di default è "Autenticazione");
  • subtitle: il sottotitolo (di default è "Compila i tuoi dati per la segnalazione");
  • formTitle: il titoletto sopra i form (di default è "Aiutaci a capire chi sei").

Esempi di codice con parametri opzionali

  1. Specifichiamo un prefisso univoco che verrà aggiunto a tutti gli ID degli elementi all’interno del widget e specifichiamo anche un colore personalizzato grazie alla chiave primaryColor 
    
  <div id="ID-DEL-CONTENITORE-DEL-WIDGET"></div>
  <script type="text/javascript">
    var ccWidgetReportingConf = {
      targetId: "ID-DEL-CONTENITORE-DEL-WIDGET",
      apiKey: "TUA-API-KEY",
      prefix: "MIO-PREFISSO-UNIVOCO",
      ui: {
        primaryColor: "FF33CB"
      }
    };
  </script>
  <script type="text/javascript" src="URL-DELLA-CDN-DEL-WIDGET" async></script>
  2. Specifichiamo anche dei testi personalizzati per la parte di gestione degli allegati grazie al dizionario upload. 
    
  <div id="ID-DEL-CONTENITORE-DEL-WIDGET"></div>
  <script type="text/javascript">
    var ccWidgetReportingConf = {
      targetId: "ID-DEL-CONTENITORE-DEL-WIDGET",
      apiKey: "TUA-API-KEY",
      prefix: "MIO-PREFISSO-UNIVOCO",
      ui: {
        primaryColor: "FF33CB"
      },
      labels: {
        upload: {
          title: "Files",
          area: "Trascina qui i files che vuoi allegare",
          button: "Carica file",
        }
      }
    };
  </script>
  <script type="text/javascript" src="URL-DELLA-CDN-DEL-WIDGET" async></script>
  3. Specifichiamo dei testi personalizzati per la parte di autenticazione grazie al dizionario auth. 
    
  <div id="ID-DEL-CONTENITORE-DEL-WIDGET"></div>
  <script type="text/javascript">
    var ccWidgetReportingConf = {
      targetId: "ID-DEL-CONTENITORE-DEL-WIDGET",
      apiKey: "TUA-API-KEY",
      prefix: "MIO-PREFISSO-UNIVOCO",
      ui: {
        primaryColor: "FF33CB"
      },
      labels: {
        auth: {
          title: "Autenticazione",
          subtitle: "Compila con i tuoi dati personali",
          formTitle: "Dati del segnalatore"
        }
      }
    };
  </script>
  <script type="text/javascript" src="URL-DELLA-CDN-DEL-WIDGET" async></script>
  4. Importiamo il widget con inizializzazione manuale usando il parametro autoInit.
    Importante: la CDN va importata in modalità sincrona. 
    
  <div id="ID-DEL-CONTENITORE-DEL-WIDGET"></div>
  <script type="text/javascript">
    var ccWidgetReportingConf = {
      targetId: "ID-DEL-CONTENITORE-DEL-WIDGET",
      apiKey: "TUA-API-KEY",
      prefix: "MIO-PREFISSO-UNIVOCO",
      autoInit: false
    };
  </script>
  <script type="text/javascript" src="URL-DELLA-CDN-DEL-WIDGET"></script>
  <script type="text/javascript">
    window.onload = function () {
      ccWidgetReporting.init()
    }
  </script>

File allegabili alla segnalazione

L'area in cui allegare file alla segnalazione possiede due limiti tecnici per migliorare la sicurezza dell'applicativo:

  • 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.
Vengono poi eseguiti anche controlli server-side sulla validità del file allegato, il quale viene scansionato da un nostro sistema antivirus e trattato poi di conseguenza.