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

Ultimo aggiornamento: 30 Settembre 2024

Codice di inserimento del widget

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.2.0/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

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

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


  <!-- 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 *.sentry.io;
    frame-src ...altre direttive già presenti... cdn-embed.comuni-chiamo.com;
    ">

UI

I parametri disponibili al momento sono 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, ed il fullWidth, con cui è invece possibile modificare la grandezza del widget per fargli occupare tutto lo spazio disponibile.

Il primaryColor è uno strumento utile per adeguare il tema del widget al tema della pagina in cui viene embeddato. Una lista dei primaryColor consigliati è disponibile qui: Palette colori Widget.

Il fullWidth e invece un parametro booleano a cui diamo un valore true se vogliamo che il widget occupi sempre il 100% dello spazio disponibile.

LABELS

Al momento i valori testuali che possono essere configurati a piacimento riguardano: il form del disservizio, l'area per allegare immagini ed il form del segnalatore.

Form disservizio, personalizzabile usando la chiave report:

  • category: label dell'input in cui selezionare la categoria del disservizio (default "Categoria:");
  • subcategory: label dell'input in cui selezionare la tipologia del disservizio (default "Tipologia:"); la tipologia dipende dalla categoria scelta e permette di specificare ulteriormente che tipo di disservizio si sta segnalando;
  • title: label dell'input in cui inserire l'oggetto del disservizio (default "Titolo:");
  • description: label dell'input in cui inserire la descrizione del disservizio (default "Dettagli:");

Area per allegare immagini e files, personalizzabile usando la chiave upload:

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

Form segnalatore, personalizzabile usando la chiave auth:

  • title: il titolo della pagina (di default è "Autenticazione");
  • subtitle: il sottotitolo (di default è "Informazioni su di te");

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. Oltre a voler modificare il tema del widget, vogliamo anche che occupi sempre il 100% dello spazio disponibile tramite il parametro fullWidth 
    
  <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",
        fullWidth: true
      }
    };
  </script>
  <script type="text/javascript" src="URL-DELLA-CDN-DEL-WIDGET" async></script>
  3. 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>
  4. 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",
        }
      }
    };
  </script>
  <script type="text/javascript" src="URL-DELLA-CDN-DEL-WIDGET" async></script>
  5. Specifichiamo dei testi personalizzati per la parte di disservizio grazie al dizionario report. 
    
  <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: {
        report: {
          category: "Categoria del disservizio:",
          subcategory: "Tipologia del disservizio:",
          title: "Oggetto del disservizio:",
          description: "Dettagli:"
        }
      }
    };
  </script>
  <script type="text/javascript" src="URL-DELLA-CDN-DEL-WIDGET" async></script>
  6. 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.