# Integrazioni con il Sito Istituzionale

Widget generali:

* Login Box
* Satisfy

I servizi built-in implementati sono:

* Richiedi assistenza
* Segnala problema in città
* Prenota appuntamento
* Pagamenti dovuti

I servizi sono presenti in ogni tenant fin dalla sua creazione e non sono modificabili dagli amministratori. Inoltre possono generare pratiche del tutto simili a quelle dei servizi tradizionali, ma il modulo è standard e come amministratore non è possibile modificarlo.

Ogni tenant (ente) punta in automatico alla sua versione widget **compatibile** in modo automatico

Tutti i widget possono essere caricati con bootstrap-italia 2 se il sito che lo contiene non carica già una versione di bts2 oppure senza

Esempio

```
Versione con bootstrap-italia 2
"https://servizi.comune.bugliano.pi.it/widgets/bookings/bootstrap-italia@2/js/bookings.js"
"https://servizi.comune.bugliano.pi.it/widgets/bookings/bootstrap-italia@2/css/bookings.css"

Versione senza bootstrap-italia 2
"https://servizi.comune.bugliano.pi.it/widgets/bookings/js/bookings.js"
"https://servizi.comune.bugliano.pi.it/widgets/bookings/css/bookings.css"
```

Se in una pagina ci sono più widget lo script con le variabili si inserisce una volta

```
<script>
window.OC_BASE_URL = 'https://servizi.comune.bugliano.pi.it/lang';
window.OC_PRIVACY_URL = 'https://www.comune.bugliano.pi.it/Privacy';
window.OC_AUTH_URL = 'https://servizi.comune.bugliano.pi.it/lang/login';
</script>
```

### Pagamenti dovuti

Codice da inserire nella pagina per il caricamento del widget, sostituire \<domain> con il link dell'area personale dell’ente es: <https://servizi.comune.bugliano.pi.it>

```
<div id="oc-paymentsDue"></div>
<script>
   window.OC_BASE_URL = '<domain>/lang';
   window.OC_PRIVACY_URL = 'https://www.comune.bugliano.pi.it/Privacy';
   window.OC_AUTH_URL = '<domain>/lang/login';
   window.OC_CHECKOUT_URL = 'https://api.stanzadelcittadino.it/pagopa/checkout';
</script>
<link rel="stylesheet" href="<domain>/widgets/payments-due/css/paymentsDue.css" />
<script src="<domain>/widgets/payments-due/js/paymentsDue.js"></script>
```

### Prenota appuntamento

```
<div id="oc-bookings"></div>
<script>
window.OC_BASE_URL = 'https://servizi.comune.bugliano.pi.it/lang';
window.OC_PRIVACY_URL = 'https://www.comune.bugliano.pi.it/Privacy';
window.OC_AUTH_URL = 'https://servizi.comune.bugliano.pi.it/lang/login';
</script>
<link rel="stylesheet" href="https://servizi.comune.bugliano.pi.it/widgets/bookings/css/bookings.css" />
<script src="https://servizi.comune.bugliano.pi.it/widgets/bookings/js/bookings.js"></script>
```

### Segnalazioni

Il widget restituisce come pagina di default `/` oppure `/#` la pagina di invio nuova segnalazione

Sotto la path `/#/segnalazioni` restituisce la pagina della lista di segnalazioni Sotto la path `/#/segnalazioni/{id}` restituisce la pagine del dettaglio di una segnalazione

```
<div id="oc-inefficiencies"></div>
<link rel="stylesheet" type="text/css" href="https://servizi.comune.bugliano.pi.it/widgets/inefficiencies/css/inefficiencies.css" /> 

<script>
window.OC_BASE_URL = 'https://servizi.comune.bugliano.pi.it/lang';
window.OC_PRIVACY_URL = 'https://www.comune.bugliano.pi.it/Privacy';
window.OC_AUTH_URL = 'https://servizi.comune.bugliano.pi.it/lang/login';
</script>

<script src="https://servizi.comune.bugliano.pi.it/widgets/inefficiencies/js/inefficiencies.js"></script>
```

Dalla versione **1.5.0** è stata aggiunta una nuova variabile per limitare la ricerca degli indirizzi tramite zone, configurando un bounding\_box (x1,y1,x2,y2) x = longitudine, y = latitudine

```
 window.OC_BB = '8.66272,44.52197,9.09805,44.37590';
```

Dalla versione **1.6.0** sono state aggiunte due variabili d'ambiante per la configurazione del provider delle mappe basato su `nominatim` di default il provider è configurato su `nominatim.openstreetmap.org`.

`OC_MAP_SEARCH_PROVIDER` configura il provider di ricerca es. ricerca indirizzi da select

All'occorrenza può essere cambiato con un'altro provider custom basato su `nominatim`

`OC_MAP_REVERSE_PROVIDER` configura il provider di ricerca inversa, ovvero restituisce l'indirizzo da punto su mappa, es. quando sposto un marker da mappa mi restituisce un indirizzo testuale.

All'occorrenza può essere cambiato con un'altro provider custom basato su `nominatim`

```
window.OC_MAP_SEARCH_PROVIDER = 'nominatim.openstreetmap.org';
window.OC_MAP_REVERSE_PROVIDER = 'nominatim.openstreetmap.org';
```

Configurazione per mostrare il campo  **`Valuta l'importanza del problema`**  Dalla versione **1.14.3**

`OC_SHOW_SEVERITY_FIELD` gestisce l'abilitazione del campo  **`Valuta l'importanza del problema`**  nel form della segnalazione disservizio.  Di default il campo è nascosto.&#x20;

```
window.OC_SHOW_SEVERITY_FIELD=true;
```

**Personalizzazione campi obbligatori** per la segnalazione disservizio. \
Dalla versione `1.16.7` \
Per rendere obbligatori altri campi del form delle segnalazioni oltre a quelli già previsti di default è possibile popolare`window.OC_REQUIRED_FIELDS` con la lista dei campi che si vuole rendere obbligatori.

```
window.OC_REQUIRED_FIELDS=['address','type','fiscal_code','severity']
```

lista dei campi che è possibile rendere obbligatori

| nome         | descrizione                      |
| ------------ | -------------------------------- |
| type         | Tipo di disservizio (categoria)  |
| address      | Luogo (indirizzo)                |
| fiscal\_code | Codice fiscale                   |
| severity     | Valuta l'importanza del problema |

Dalla versione **1.11.0** è stata aggiunta la variabile per rendere modificabile la lista delle categorie

```
window.OC_CATEGORIES_URL = 'https://static.opencityitalia.it/widgets/inefficiencies/data/categories-multi.json';
```

**Categorie con canali esterni** (dalla versione **1.12.3**)

Per le categorie configurate con link esterni, il widget invita l'utente a proseguire tramite i canali esterni e impedisce la prosecuzione della compilazione e dell'invio della segnalazione.

I link esterni vanno configurati nel json richiamato tramite `window.OC_CATEGORIES_URL` popolando all'interno della categoria, il valore `external_ref` (opzionale) con i seguenti campi:

| nome     | descrizione |
| -------- | ----------- |
| title    | titolo      |
| text     | descrizione |
| channels | \[channel]  |

`channel`

| nome  | descrizione                      |
| ----- | -------------------------------- |
| type  | web, email, phone, ios o android |
| href  | link href                        |
| label | link label                       |

esempio:

```
...
{
 "label": "Manutenzione",
 "value": "8f06c823-e476-4ec1-a208-6fd4956e5a56",
 "external_ref": {
   "title": "Contatta questo contatto esterno",
   "text": "Per la manutenzione di:\n \u2022 Strade \n \u2022 Marciapiedi...",
   "channels": [
     {
       "type": "web",
       "label": "vai al sito www.google.it",
       "href": "https://www.google.it"
      },
      {
        "type": "email",
        "label": "Scrivi un'email a info@example.com",
        "href": "mailto:info@example.com"
      },
      {
        "type": "phone",
        "label": "Telefona al numero verde 12345789",
        "href": "tel://12345789"
      },
      {
        "type": "ios",
        "label": "Scarica l'app dedicata",
        "href": "https://apple-store.com/mia-app"
      },
      {
        "type": "android",
        "label": "Scarica l'app dedicata",
        "href": "https://play.google.com/mia-app"
      }
    ]
  }
},
```

**Configurazione apertura dettaglio segnalazione** (dalla versione **1.16.0**)

Al termine della compilazione e di invio di una segnalazione se l'utente si è autenticato è presente un link per andare al dettaglio della segnalazione.

Di default il link punta al dettaglio della segnalazione sull'area personale, in alternativa è possibile configurare l'apertura del dettaglio rimanendo nel widget tramite variabile `window.OC_SHOW_DETAIL_ON_WEBSITE=true`

<figure><img src="https://2402436129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNwAiDeLoMPCkkp1BdSbI%2Fuploads%2FAPJrl1MP4kL7yrPlT1r7%2Fimage%20(2).png?alt=media&#x26;token=695a9ef9-f58b-41b4-a1c3-7751fd79a5c6" alt="" width="375"><figcaption></figcaption></figure>

#### Dalla versione 1.17.1 è disponibile il routing senza l'uso dell'\#

Nelle versione precedenti alla 1.17.0 il routing del widget funzionava solo tramite # HashRouting&#x20;

Es. <https://www.comune-qa.bugliano.pi.it/segnala_disservizio#/segnala_disservizio>

Aggiungendo la nuova variabile d'ambiante `window.OC_BASENAME` è possibile trasformare il routing in versione BrowserRouting&#x20;

Es. <https://www.comune-qa.bugliano.pi.it/segnala_disservizio/segnala_disservizio>

Per configurare la variabile `window.OC_BASENAME` c'è bisogno del path dove è configurato il widget con eventuali sottodomini se il widget è configurato in path non di primo livello.

Es. <https://sito.it>   ->  `window.OC_BASENAME='/'`

Es. <https://sito.it/segnalazioni> -> `window.OC_BASENAME='/segnalazioni'`

Es. <https://sito.it/segnalazioni/123> -> `window.OC_BASENAME='/segnalazioni/123'`

### Richiesta assistenza

```
Versione con bootstrap-italia 2
<div id="oc-helpdesk"></div>
<link rel="stylesheet" href="https://servizi.comune.bugliano.pi.it/widgets/helpdesk/bootstrap-italia@2/css/helpdesk.css" />
<script>
window.OC_BASE_URL = 'https://servizi.comune.bugliano.pi.it/lang';
window.OC_PRIVACY_URL = 'https://www.comune.bugliano.pi.it/Privacy';
window.OC_AUTHURL = 'https://servizi.comune.bugliano.pi.it/lang/login';
</script>
<script src="https://servizi.comune.bugliano.pi.it/widgets/helpdesk/bootstrap-italia@2/js/helpdesk.js"></script>
```

```
Versione senza bootstrap-italia 2
<div id="oc-helpdesk"></div>
<link rel="stylesheet" href="https://servizi.comune.bugliano.pi.it/widgets/helpdesk/css/helpdesk.css" />
<script>
window.OC_BASE_URL = 'https://servizi.comune.bugliano.pi.it/lang';
window.OC_PRIVACY_URL = 'https://www.comune.bugliano.pi.it/Privacy';
window.OC_AUTHURL = 'https://servizi.comune.bugliano.pi.it/lang/login';
</script>
<script src="https://servizi.comune.bugliano.pi.it/widgets/helpdesk/js/helpdesk.js"></script>
```

Sui servizi built-in:

* Richiedi assistenza
* Segnala problema in città
* Prenota appuntamento

è stata aggiunta la possibilità di auto generasi un breadcrums semplice del tipo `Home / Segnalazioni` dove `Home` è la homepage del sito e `segnalzioni` è la route del widget, aggiungendo la variabile:

`window.OC_RENDER_BREADCRUMB=true`

se la variabile non è presente o ha valore `false` la breadcrums non verrà abilitata

### Pulsante accedi all'area personale

```html
<div id="oc-login-box"></div>

<script>
window.OC_BASE_URL = 'https://servizi.comune.bugliano.pi.it/lang';
window.OC_AUTH_URL = 'https://servizi.comune.bugliano.pi.it/lang/login';
window.OC_SPID_BUTTON = 'true' // da usare se si vuole utilizzare la versione senza popup login spid
window.OC_AUTH_LABEL = 'SPID/CNS/EIDAS/CIE'
</script>

<script src="https://servizi.comune.bugliano.pi.it/widgets/login-box/bootstrap-italia@2/js/login-box.js"></script>
```

Se si hanno altri tipi di autenticazione oltre a SPID è possibile personalizzare il titolo del popup.

<figure><img src="https://2402436129-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNwAiDeLoMPCkkp1BdSbI%2Fuploads%2FK45woeGZvgYxYJTolirf%2FScreenshot%202024-11-26%20alle%2015.58.40.png?alt=media&#x26;token=a71a66c3-1b56-4f29-814a-a3d3757c9208" alt="" width="375"><figcaption></figcaption></figure>

```
window.OC_AUTH_LABEL = 'Testo personalizzato'
```

Il pulsante Accedi dopo aver effettuato la login può mostrare un menù a tendina con vari voci che ti ridirigono all'area personale, per abilitarlo omettere o impostare come da variabile sotto a false

```
window.OC_USER_MENU_DISABLED = false
```

Per disabilitarlo e vedere solo al voce do logout impostare la variabile a true

```
window.OC_USER_MENU_DISABLED = true
```

### Satisfy Widget

Il widget **Satisfy** consente di raccogliere feedback da parte degli utenti. È disponibile in diverse versioni ed è consigliato utilizzare **sempre l’ultima versione aggiornata** per garantire compatibilità e funzionalità ottimali. Tutte le versioni che puntano alla **Stanza del Cittadino** si aggiornano automaticamente.

Tutte le versioni del widget sono disponibili sulla [pagina](https://gitlab.com/opencontent/satisfy/satisfy-widget/-/releases)

### Installazione

#### Versione con Bootstrap Italia 2

Se il sito **non utilizza** già Bootstrap Italia 2 (BI2), includere la versione del widget che lo incorpora:

```html
<script src="https://static.opencityitalia.it/widgets/satisfy/version/{version}/bootstrap-italia@2/js/satisfy.js"></script>
```

> Sostituire `{version}` con la versione desiderata (es. `1.6.0`).\
> Questa versione è auto-aggiornante.

***

#### Versione senza stili (se BI2 è già incluso nel sito)

Se il sito **utilizza già** Bootstrap Italia 2, includere solamente il componente e lo script del widget:

```html
<app-widget data-entrypoints="{UUID}"></app-widget>
<script src="https://servizi.comune.bugliano.pi.it/widgets/satisfy/js/satisfy.js"></script>
```

Oppure, utilizzando una versione **CDN**:

```html
<app-widget data-entrypoints="{UUID}"></app-widget>
<script src="https://static.opencityitalia.it/widgets/satisfy/version/{version}/js/satisfy.js"></script>
```

> `data-entrypoints` è un attributo **obbligatorio** e contiene l’UUID della configurazione globale del widget.

***

### Configurazioni avanzate

#### Endpoint personalizzati (dalla versione 1.5.8)

È possibile specificare endpoint alternativi per i salvataggi e per le chiamate API:

```html
<app-widget 
  data-entrypoints="{UUID}"
  data-api-ratings="https://satisfy.opencityitalia.it/api/v1/ratings"
  data-api-configs="https://satisfy.opencityitalia.it/v1/graphql"
></app-widget>

<script src="https://servizi.comune.bugliano.pi.it/widgets/satisfy/bootstrap-italia@2/js/satisfy.js"></script>
```

**Parametri disponibili**

| Attributo          | Descrizione                                                                                                                                                  |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data-entrypoints` | **Obbligatorio.** UUID della configurazione del widget.                                                                                                      |
| `data-api-ratings` | URL personalizzato per le richieste POST di salvataggio dei feedback. Se non specificato, usa il default `https://satisfy.opencityitalia.it/api/v1/ratings`. |
| `data-api-configs` | URL personalizzato per le chiamate API GraphQL. Se non specificato, usa `https://satisfy.opencityitalia.it/v1/graphql`.                                      |