Configurazione del modulo Web Analytics
Il modulo Web Analytics importa i dati di GA4 e Google Search Console in una dashboard in linguaggio semplice dentro Flo (Amministrazione → Analytics). Legge le API di Google tramite un unico service account a livello di flotta, configurato una sola volta dall'operatore.
La connessione ha due lati:
- Operatore (una volta per flotta) — provisiona il service account Google Cloud e inserisce la sua chiave nel segreto
GOOGLE_ANALYTICS_SA_JSONsu ogni istanza. - Per cliente — concede a quel service account l'accesso in lettura alla proprietà GA4 e a Search Console del cliente, quindi inserisce gli ID nella pagina di configurazione e verifica.
Il JSON del service account risiede solo nella variabile d'ambiente GOOGLE_ANALYTICS_SA_JSON. È un segreto a livello di flotta e non è mai memorizzato in alcun database tenant — la riga di configurazione per tenant contiene solo l'id della proprietà GA4, il sito GSC, il verticale e il flag di abilitazione.
L'avviso "non ancora connesso su questo server"
Se la pagina di configurazione mostra un avviso ambra tipo "Analytics non è ancora connesso su questo server. Chiedi all'operatore Flo di configurarlo prima di collegare", significa che GOOGLE_ANALYTICS_SA_JSON non è impostata su quell'istanza. È normale su un'istanza nuova — completa prima i passi operatore qui sotto. La riga di log del backend lo conferma:
Web analytics: GOOGLE_ANALYTICS_SA_JSON not set — ETL disabled.
Parte A — Operatore: provisiona il service account (una volta)
Serve la CLI gcloud autenticata verso un progetto Google Cloud sotto il tuo controllo.
1. Seleziona (o crea) il progetto
gcloud config set project <PROJECT_ID>
2. Abilita le due API di lettura
gcloud services enable analyticsdata.googleapis.com searchconsole.googleapis.com
analyticsdata.googleapis.com— reportistica GA4 (Data API).searchconsole.googleapis.com— search-analytics di Search Console.
3. Crea il service account
gcloud iam service-accounts create flo-web-analytics \
--display-name="Flo Web Analytics (read-only)"
Questo produce l'indirizzo flo-web-analytics@<PROJECT_ID>.iam.gserviceaccount.com — è l'indirizzo a cui i clienti concedono l'accesso. Non è sensibile; Flo lo mostra nella pagina di configurazione così il cliente può copiarlo.
4. Scarica una chiave
gcloud iam service-accounts keys create flo-web-analytics-key.json \
--iam-account="flo-web-analytics@<PROJECT_ID>.iam.gserviceaccount.com"
Conserva flo-web-analytics-key.json al sicuro — trattalo come una password. La stessa chiave può servire ogni tenant; non serve un account separato per cliente.
5. Imposta il segreto sull'istanza
Il backend legge la variabile come JSON grezzo (GoogleCredential.FromJson). Poiché il file .env è basato su righe, passa la chiave minificata su una sola riga:
flo --vps production config env set <instance-id> \
GOOGLE_ANALYTICS_SA_JSON "$(jq -c . flo-web-analytics-key.json)" --restart
Il valore deve essere il JSON stesso, non un nome file. --restart è obbligatorio: la credenziale è costruita una sola volta all'avvio, quindi un container in esecuzione non recepisce una nuova chiave finché non viene riavviato.
Ripeti per ogni istanza che deve avere analytics. Gli scope sono fissi in sola lettura: analytics.readonly + webmasters.readonly.
6. Verifica che sia caricato
flo --vps production config web-analytics status <instance-id>
Il log del backend dovrebbe ora mostrare l'abilitazione dell'ETL invece della riga "not set". La pagina di configurazione nell'app mostrerà l'email del service account al posto dell'avviso ambra.
Parte B — Per cliente: collega GA4 + Search Console
Questi passi si dividono tra le console di Google e la pagina di configurazione Amministrazione → Analytics di Flo.
1. Concedi al service account l'accesso in Google
- GA4 — vai su Amministrazione → Gestione dell'accesso alla proprietà (Property Access Management), aggiungi l'email del service account con il ruolo Viewer (Visualizzatore). La sola lettura basta.
- Search Console — vai su Impostazioni → Utenti e autorizzazioni (Settings → Users and permissions), aggiungi la stessa email con accesso Full.
Questo è separato dall'aggiungere team.ledges@gmail.com come Editor (vedi Configurazione GA4 per un cliente). L'account umano di Ledges gestisce la proprietà; il service account legge solo i dati per la dashboard.
2. Inserisci gli ID in Flo e verifica
Nella pagina di configurazione Amministrazione → Analytics:
- Copia l'email del service account mostrata in alto (usa il pulsante Copy) se ti serve ancora per il passo 1.
- Inserisci l'id della proprietà GA4 (l'id numerico, es.
542344364). - Inserisci il sito Search Console esattamente come lo mostra Google (
sc-domain:example.comper una proprietà di dominio, oppure l'URL completohttps://…/per una proprietà con prefisso URL). - Salva, quindi fai clic su Verify access.
Un esito verde conferma che GA4 e Search Console sono raggiungibili. Il successivo tick dell'ETL storicizza i dati pregressi (backfill) e la dashboard si popola.
Risoluzione degli errori di verifica
Il risultato di Verify access corrisponde a un codice di errore stabile:
| Risultato | Significato | Soluzione |
|---|---|---|
not_configured | GOOGLE_ANALYTICS_SA_JSON non impostata su questa istanza | Esegui la Parte A. |
permission_denied | Accesso non concesso al service account | Aggiungi l'email come Viewer in GA4 e Full in Search Console (Parte B passo 1). |
invalid_config | Proprietà / sito non trovati | Controlla che l'id proprietà GA4 e la stringa del sito GSC corrispondano esattamente a Google. |
quota_exceeded | Troppe richieste | Attendi un minuto e verifica di nuovo. |
unknown | Verifica non completata | Ricontrolla gli ID e che il service account abbia accesso, quindi riprova. |
Checklist
| Passo | Lato | Risultato |
|---|---|---|
| Abilita GA4 Data API + Search Console API | Operatore | API Google raggiungibili |
Crea il service account flo-web-analytics + chiave | Operatore | Un unico account riusabile in sola lettura |
Imposta GOOGLE_ANALYTICS_SA_JSON (minificata) + riavvio | Operatore | L'istanza può chiamare Google |
| Aggiungi l'email SA come Viewer in GA4 | Per cliente | Dati GA4 leggibili |
| Aggiungi l'email SA come Full in Search Console | Per cliente | Dati di ricerca leggibili |
| Inserisci id GA4 + sito GSC, Salva, Verify access | Per cliente | La dashboard storicizza e si popola |