> For the complete documentation index, see [llms.txt](https://docs.opencityitalia.it/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opencityitalia.it/sviluppatori-e-partner-tecnologici/integrazioni/installazione-chatbot/integrazione-con-il-frontend.md).

# Integrazione con il frontend

Il componente di interfaccia (Frontend) è l'elemento che permette l'interazione diretta tra i cittadini e il motore di intelligenza artificiale configurato nel backend.

Il widget è stato sviluppato seguendo rigorosamente le linee guida ufficiali di Designers Italia. Questo garantisce:

* piena accessibilità e usabilità;
* coerenza grafica con gli standard dei siti della Pubblica Amministrazione;
* un'esperienza utente (UX) intuitiva.

## Parametri di configurazione

Il codice sorgente completo del widget è disponibile al seguente indirizzo: [integrazioni con il sito istituzionale](https://docs.opencityitalia.it/sviluppatori-e-partner-tecnologici/integrazioni/integrazioni-con-il-sito-istituzionale)

Per rendere operativo il widget e personalizzarlo secondo le specifiche dell'Ente, lo script di integrazione richiede la definizione obbligatoria di cinque parametri:

| **Parametro**     | **Funzione**                                              | **Esempio / Note**                |
| ----------------- | --------------------------------------------------------- | --------------------------------- |
| API URL           | Indirizzo HTTP per le chiamate REST al backend.           | `https://chat.ente.it/cat`        |
| WebSocket URL     | Indirizzo per la connessione in tempo reale (streaming).  | `wss://chat.ente.it/cat/ws`       |
| Nome Ente         | Etichetta testuale mostrata nell'intestazione della chat. | Es. "Comune di Trento"            |
| Colore Principale | Codice esadecimale per il branding (bottoni, header).     | Es. `#0066CC`                     |
| Link Privacy      | URL alla pagina dell'informativa sul trattamento dati.    | Obbligatorio per conformità GDPR. |

## Widget non visibile: AdBlock e anti-tracking

Il widget viene integrato tramite **Google Tag Manager** (GTM), uno strumento che consente di aggiungere componenti a runtime senza dover intervenire direttamente sul codice del sito.

In alcune configurazioni, il widget potrebbe non essere visibile al cittadino. La causa più comune è l'**attivazione di un ad blocker o di uno strumento anti-tracking**, come:

* estensioni browser tipo AdBlock, uBlock Origin o simili;
* funzionalità di protezione integrata in VPN (ad esempio NordVPN);
* modalità "Enhanced Tracking Protection" di alcuni browser.

Gli strumenti anti-tracking bloccano Google Tag Manager perché, nella grande maggioranza dei casi, i siti web lo utilizzano per finalità di profilazione e pubblicità. Nel caso del chatbot OpenCity, GTM è il metodo più comodo per iniettare il widget a runtime senza dover coinvolgere i developer del sito a ogni aggiornamento: non viene usato per raccogliere dati o tracciare il comportamento degli utenti. Il blocco è però automatico e indiscriminato.

{% hint style="warning" %}
Se il widget del chatbot non appare, verifica se il browser o la VPN in uso hanno un ad blocker attivo. Disabilitandolo per il sito istituzionale, il widget torna visibile.
{% endhint %}

Se il problema riguarda una quota rilevante degli utenti, la soluzione definitiva è integrare lo script del widget **direttamente nel codice del sito**, bypassando Google Tag Manager: lo script non sarà più soggetto ai filtri anti-tracking che si concentrano su GTM.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.opencityitalia.it/sviluppatori-e-partner-tecnologici/integrazioni/installazione-chatbot/integrazione-con-il-frontend.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.