30 Set
Articolo scritto con l’aiuto dell’intelligenza artificiale per descrivere il processo d’installazione di Google Tag Manager API .
La Google Tag Manager API permette di fare da riga di comando tutto ciò che normalmente si fa cliccando nell’interfaccia: creare un container, definire variabili e trigger, collegare i tag GA4, generare una versione. Per chi gestisce il tracciamento di più clienti, è la differenza tra ripetere lo stesso setup venti volte a mano e istanziarlo in un minuto.
In questa guida trovi il percorso completo: l’autorizzazione all’accesso (la parte che ferma quasi tutti, e i cui messaggi d’errore indicano quasi sempre la causa sbagliata) e poi la creazione vera e propria di un container funzionante. Tutti i passaggi sono testati su un container di prova.
Perché automatizzare i container GTM
Il valore non sta nel singolo container, ma nella ripetibilità. Un setup di tracciamento standard (consent mode, configurazione GA4, eventi di contatto, variabili dataLayer, trigger sui form) è sempre lo stesso nella struttura e cambia solo nei dettagli. Definirlo una volta in codice significa applicarlo a un cliente nuovo senza rifare venti clic uguali, e soprattutto senza le piccole divergenze che si accumulano quando lo stesso setup viene ricostruito a mano ogni volta.
C’è un secondo vantaggio, meno ovvio: quello che è scritto in codice è verificabile. Puoi rileggere esattamente cosa è stato configurato su ogni cliente, invece di aprire venti interfacce per controllare.
Cosa serve prima di iniziare
Tre cose, un progetto su Google Cloud, che è gratuito e serve solo come contenitore amministrativo, la gcloud CLI installata (disponibile per macOS, Windows e Linux) e il tuo account Google deve avere accesso ai container GTM su cui vuoi lavorare: l’autorizzazione tecnica non sostituisce il permesso dentro il prodotto, e se non sei stato invitato a un container non lo vedrai comunque.
Io lavoro da Claude Code nel terminale, ma niente in questa guida ne dipende: sono chiamate HTTP, funzionano allo stesso modo da qualsiasi ambiente sappia eseguire curl.
Vale la pena chiarire subito un punto che fa risparmiare tempo: non serve costruire alcuna integrazione. La Tag Manager API è una normale REST API, e per una sequenza di operazioni che decidi tu (crea container, aggiungi variabili, collega i tag) bastano chiamate dirette.
Come si autorizza l’accesso alle API Google
Qui sta il vero lavoro. L’API in sé è documentata e lineare; è ottenere il permesso di chiamarla che richiede attenzione. Anticipo le quattro difficoltà più comuni, in ordine: sono le stesse per qualsiasi API Google, quindi quello che segue vale anche se domani ti serve Search Console o YouTube Data.
Attivare l’API sul progetto
La prima chiamata a un’API mai usata prima risponde 403 con SERVICE_DISABLED. Non è un problema di scope: l’API va attivata sul progetto. Attenzione a un dettaglio che si confonde facilmente: attivarla richiede anche il permesso IAM serviceusage.services.enable sul progetto (se il progetto è tuo ce l’hai come Owner, su quello di un cliente può mancare). Si fa dalla console, oppure via riga di comando:
gcloud services enable tagmanager.googleapis.com --project=IL_TUO_PROJECT_ID
Un dettaglio che evita una caccia inutile: negli errori Google alterna il project ID (mio-progetto-123) e il project number (una lunga sequenza di cifre). Sono due nomi dello stesso progetto, non due progetti diversi.
Autorizzare gli scope giusti
Attivata l’API, la chiamata risponde ancora 403, stavolta con ACCESS_TOKEN_SCOPE_INSUFFICIENT. Le tue credenziali sono valide, ma non coprono Tag Manager: gli scope sono i permessi specifici che un token porta con sé.
La Tag Manager API ne definisce diversi, e vale la pena sceglierli con parsimonia:
Scope
tagmanager.manage.accounts
tagmanager.edit.containers
tagmanager.edit.containerversions
tagmanager.publish
tagmanager.delete.containers
Cosa consente
vedere e gestire gli account
gestire container, variabili, trigger, tag
creare e gestire le versioni
pubblicare un container
eliminare container
Il consiglio è di non richiedere tagmanager.publish finché non ti serve davvero. Senza quello scope, mandare per errore qualcosa in produzione sul sito di un cliente non è improbabile: è tecnicamente impossibile. Ci torno più avanti, perché è la scelta più importante di tutta la configurazione.
Qui una regola che vale la pena imparare prima di sbatterci: con questo comando gli scope non si sommano, si sostituiscono. Il comando di autorizzazione riscrive le credenziali con esattamente ciò che elenchi. Se stai già usando altre API Google — Google Ads, Analytics — e ne elenchi solo alcune, le altre smettono di funzionare, senza alcun avviso. Elenca sempre la lista completa: quelle che avevi più quelle nuove.
Una precisazione, perché la regola non va generalizzata: non è una legge di OAuth. Nei flussi web esiste l’autorizzazione incrementale, che somma i permessi già concessi; per le app installate — il caso di gcloud — Google non la prevede. Vale quindi per lo strumento che hai in mano, che è ciò che conta in pratica.
Dichiarare gli scope nella schermata di consenso
Prima di autorizzare, i nuovi scope vanno dichiarati nella schermata di consenso del progetto, in Google Auth Platform → Data Access. Il campo per aggiungerli a mano è in fondo al pannello, sotto l’elenco di quelli proposti.
Gli scope di Tag Manager compaiono tra gli “ambiti sensibili”, con un avviso di approvazione obbligatoria. Non blocca nulla: la verifica di Google riguarda la distribuzione di un’app ad altre persone. La documentazione ufficiale è esplicita nell’elencare i casi in cui la verifica non è necessaria, e il primo è l’uso personale sotto i 100 utenti. Vedrai una schermata che avvisa che l’app non è verificata: si prosegue da “Avanzate”.
Pubblicare l’app, per non rifare il login ogni settimana
Questo passaggio è quello che nessuno spiega, e che spiega un fastidio molto comune: credenziali che smettono di funzionare dopo circa una settimana, costringendo a rifare l’autorizzazione.
La causa è documentata. Un progetto con schermata di consenso di tipo esterno e stato di pubblicazione “Testing” riceve refresh token che scadono in 7 giorni. Non è un guasto: è il comportamento previsto per le app in fase di test.
La soluzione è portare l’app In produzione, da Google Auth Platform → Audience. E va fatto prima di autorizzare: un token emesso mentre l’app è in stato di test conserva la scadenza breve anche se pubblichi l’app subito dopo, costringendoti a un secondo login.
Il comando di autorizzazione
Con i passaggi precedenti a posto:
gcloud auth application-default login \
--client-id-file="PERCORSO_DEL_TUO_FILE_CLIENT.json" \
--scopes=https://www.googleapis.com/auth/cloud-platform,\
https://www.googleapis.com/auth/tagmanager.manage.accounts,\
https://www.googleapis.com/auth/tagmanager.edit.containers,\
https://www.googleapis.com/auth/tagmanager.edit.containerversions
Il flag –client-id-file non è opzionale, ed è la causa più frequente del messaggio “Questa app è bloccata” — che non nomina mai il motivo reale. La documentazione di gcloud lo dice chiaramente: per aggiungere scope di prodotti fuori da Google Cloud serve un OAuth Client ID proprio, fornito con quel flag. Senza, gcloud usa il proprio client generico, che per Tag Manager non è autorizzato.
L’ID client si crea in un minuto dalla console, in Credenziali → Crea credenziali → ID client OAuth, scegliendo il tipo App desktop, e si scarica come file JSON.
Un’ultima raccomandazione prima di lanciarlo: fai una copia del file delle credenziali esistenti. Su macOS e Linux si trova in ~/.config/gcloud/application_default_credentials.json, su Windows in %APPDATA%\gcloud\. Se qualcosa va storto, rimettere quel file al suo posto ripristina la situazione precedente, perché una nuova autorizzazione non revoca quella vecchia.
A questo punto la chiamata funziona:
TOKEN=$(gcloud auth application-default print-access-token)
curl -s -H "Authorization: Bearer $TOKEN" \
"https://tagmanager.googleapis.com/tagmanager/v2/accounts"
Creare il container e popolarlo
Da qui in avanti è meccanico. Si crea il container:
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Cliente - Web","usageContext":["web"]}' \
"https://tagmanager.googleapis.com/tagmanager/v2/accounts/IL_TUO_ACCOUNT_ID/containers"
La risposta contiene il containerId e il publicId, cioè il classico GTM-XXXXXXX da installare sul sito.
Ogni container nasce con un workspace di default. È lì dentro che si creano variabili, trigger e tag, con la stessa struttura di chiamata e tre tipi che coprono la maggior parte dei casi reali: una variabile dataLayer (tipo v) per leggere i valori che il sito espone, una costante (tipo c) per l’ID di misurazione GA4, un trigger customEvent per intercettare un evento, e un tag GA4 (tipo gaawe) che li collega.
Il tag si aggancia al trigger tramite il campo firingTriggerId, che contiene l’ID restituito quando il trigger è stato creato. È l’equivalente esatto del menu “Attivazione” nell’interfaccia.
Chiusa la configurazione, si crea una versione:
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
"https://tagmanager.googleapis.com/tagmanager/v2/accounts/IL_TUO_ACCOUNT_ID/containers/IL_TUO_CONTAINER_ID/workspaces/IL_WORKSPACE_ID:create_version"
Cosa fai tu, cosa fa l’API
Lo fai tu, una volta sola
Creare il progetto e l’ID client OAuth
Dichiarare gli scope nella schermata di consenso
Pubblicare l’app e autorizzare
Farti invitare ai container dei clienti
Pubblicare in produzione
Lo fa l’API, ogni volta
Attivare l’API sul progetto
Creare container
Creare variabili, trigger, tag
Creare le versionieliminare
—
La colonna di sinistra è lavoro di configurazione iniziale. Quella di destra è ciò che si ripete su ogni cliente e che quindi conviene automatizzare.
Le due reti di sicurezza
Automatizzare la configurazione del tracciamento di un cliente fa venire il dubbio legittimo: e se sbaglio qualcosa in produzione? Ci sono due protezioni, e vale la pena usarle entrambe.
La prima è il modello di Tag Manager stesso. Come descrive la documentazione dell’API, le modifiche vivono in un workspace, da cui si crea una versione, che diventa attiva solo con una pubblicazione esplicita. Finché non pubblichi, il sito del cliente non vede assolutamente nulla. È lo stesso meccanismo dell’interfaccia, e vale identico via API.
La seconda è il perimetro dei permessi, ed è più forte. Omettendo lo scope tagmanager.publish, un tentativo di pubblicazione riceve un 403 e la versione live resta quella di prima.
Su tagmanager.delete.containers serve però una precisazione che ho verificato nella documentazione del metodo: ometterlo impedisce di cancellare il container, non il suo contenuto. Il metodo che elimina un tag richiede tagmanager.edit.containers, cioè il permesso di modifica: chi può modificare può cancellare tag, trigger e variabili.
La garanzia del perimetro minimo è quindi precisa, e vale comunque: le modifiche e le cancellazioni restano nel workspace, e senza publish non arrivano al sito del cliente. È una protezione su ciò che il visitatore vede, non sull’integrità della configurazione. Su due sole operazioni davvero irreversibili verso l’esterno, trenta secondi di lavoro manuale sono un ottimo scambio.
Serve davvero un MCP?
Domanda legittima per chi lavora con assistenti AI: conviene costruire un server MCP per Tag Manager?
Nella maggior parte dei casi no. Tutto quello che hai visto qui è stato fatto con curl, senza alcuna integrazione. Un MCP si giustifica quando vuoi che il modello scelga da solo tra molte operazioni possibili, in sessioni diverse, senza rispiegargli ogni volta il contesto. Se invece la sequenza la conosci (crea container, popola, versiona) le chiamate dirette sono più semplici da scrivere, più facili da verificare e non richiedono manutenzione.
La parte che vale la pena risolvere bene è l’accesso, non l’integrazione. Una volta autorizzato, ci costruisci sopra quello che ti serve.
In sintesi
La parte difficile della Google Tag Manager API non è l’API: è arrivare ad avere il permesso di chiamarla. Attivare il servizio, autorizzare gli scope giusti senza cancellare quelli esistenti, dichiararli nella schermata di consenso e portare l’app in produzione. Fatto una volta, resta fatto — e da lì la creazione di container diventa una sequenza di chiamate che puoi ripetere su ogni cliente.
Il consiglio che vale più di tutti: richiedi il permesso minimo. Lasciare fuori publish e delete costa trenta secondi di lavoro manuale sulle due operazioni irreversibili, ed elimina alla radice la categoria di errori che davvero preoccupa.
Il passo successivo naturale è costruire il proprio setup standard — consent mode, GA4, eventi di contatto, conversioni Google Ads — come sequenza replicabile: è lì che l’automazione smette di essere un esercizio e inizia a restituire tempo.
La procedura, pronta da usare
Tutto quello che hai letto — l’attivazione dell’API, i permessi da dichiarare, la scadenza a sette giorni, il ripristino delle credenziali — l’ho raccolto in un repo pubblico su GitHub: [collega-api-google](https://github.com/SalvatoreSalernods/collega-api-google).
Dentro ci sono due cose, a seconda di cosa ti serve.
Se devi collegare un’API e basta, apri la [guida per collegare un’API Google](https://github.com/SalvatoreSalernods/collega-api-google/blob/main/guida-collega-api-google.md): è la procedura completa in un unico file, comandi compresi, senza niente da installare. Puoi anche incollarla a ChatGPT o Claude e farti accompagnare mentre la esegui.
Se lavori in Claude Code e sai che lo rifarai — e lo rifarai, perché ogni servizio Google nuovo è un giro completo — c’è la skill che automatizza i tre passaggi in cui si fanno i danni: la copia delle credenziali verificata prima di procedere, il comando di autorizzazione generato leggendo i permessi che hai in quel momento invece di quelli che ricordi, e il controllo che confronta i permessi prima e dopo, fermandoti se qualcosa è sparito.
C’è anche la risposta a una domanda che questo articolo non affronta: [cosa tenere insieme e cosa isolare](https://github.com/SalvatoreSalernods/collega-api-google#cosa-tenere-insieme-e-cosa-isolare). Se le credenziali sono condivise fra più strumenti, ogni strumento eredita i permessi di tutti gli altri — e ci sono casi, come Merchant Center, in cui questo è un problema da evitare in partenza.
È rilasciato con licenza MIT: scaricalo, modificalo, usalo sui tuoi clienti. Se ci trovi un errore o ti serve un servizio che non ho coperto, apri una issue.
