Il documento descrive come un'applicazione può ottenere l'autorizzazione per effettuare richieste all'API Tag Manager.
Autorizzazione delle richieste
Prima che gli utenti possano visualizzare i dati del proprio account su qualsiasi sito Google, devono accedere con un Account Google. Allo stesso modo, la prima volta che gli utenti accedono all'applicazione, devono autorizzarla ad accedere ai propri dati.
Ogni richiesta che la tua applicazione invia all'API Tag Manager deve includere un token di autorizzazione. Il token, inoltre, identifica l'applicazione per Google.
Informazioni sui protocolli di autorizzazione
La tua applicazione deve utilizzare il protocollo OAuth 2.0 per autorizzare le richieste. Non sono supportati altri protocolli di autorizzazione. Se la tua applicazione utilizza la funzionalità Accedi con Google, alcuni aspetti dell'autorizzazione vengono gestiti per te.
Autorizzazione delle richieste con OAuth 2.0
Tutte le richieste all'API Tag Manager devono essere autorizzate da un utente autenticato.
I dettagli della procedura di autorizzazione, o "flusso", per il protocollo OAuth 2.0 variano a seconda del tipo di applicazione che stai scrivendo. La seguente procedura generale si applica a tutti i tipi di applicazione:
- Quando crei la tua applicazione, la registri utilizzando la console API di Google. Quindi, Google fornisce informazioni che ti saranno necessarie in un secondo momento, ad esempio un ID client e un client secret.
- Attiva l'API Tag Manager nella console API di Google. (Se l'API non è elencata nella console API, salta questo passaggio.)
- Quando la tua applicazione vuole accedere ai dati dell'utente, chiede a Google un particolare ambito di accesso.
- Google mostra una schermata di consenso all'utente, chiedendo di autorizzare l'applicazione a richiedere dei dati.
- Se l'utente approva, Google fornisce alla tua applicazione un token di accesso di breve durata.
- L'applicazione richiede i dati utente, allegando il token di accesso alla richiesta.
- Se Google ritiene validi la richiesta e il token, restituisce i dati richiesti.
Alcuni flussi includono passaggi aggiuntivi, come l'uso di token di aggiornamento per acquisire nuovi token di accesso. Per informazioni dettagliate sui flussi per vari tipi di applicazioni, consulta la documentazione relativa al protocollo OAuth 2.0 di Google.
Ecco le informazioni sull'ambito OAuth 2.0 per l'API Tag Manager:
Ambito | Significato |
---|---|
https://www.googleapis.com/auth/tagmanager.readonly |
Visualizzare i contenitori di Google Tag Manager. |
https://www.googleapis.com/auth/tagmanager.edit.containers |
Gestire i contenitori di Google Tag Manager. |
https://www.googleapis.com/auth/tagmanager.delete.containers |
Eliminare i contenitori di Google Tag Manager. |
https://www.googleapis.com/auth/tagmanager.edit.containerversions |
Gestisci le versioni dei contenitori di Google Tag Manager. |
https://www.googleapis.com/auth/tagmanager.publish |
Pubblicare i contenitori di Google Tag Manager. |
https://www.googleapis.com/auth/tagmanager.manage.users |
Gestisci le autorizzazioni utente per i dati di Google Tag Manager. |
https://www.googleapis.com/auth/tagmanager.manage.accounts |
Gestisci gli account Google Tag Manager. |
Per richiedere l'accesso utilizzando il protocollo OAuth 2.0, l'applicazione richiede le informazioni relative all'ambito e le informazioni che Google fornisce quando registri la tua applicazione (ad esempio l'ID client e il client secret).
Per iniziare
Per iniziare a utilizzare l'API Tag Manager, devi prima utilizzare lo strumento di configurazione, che ti guida nella creazione di un progetto nella console API di Google, nell'abilitazione dell'API e nella creazione delle credenziali.
Per configurare un nuovo account di servizio:
- Fai clic su Crea credenziali > Chiave account di servizio.
- Scegli se scaricare la chiave pubblica/privata dell'account di servizio come file P12 standard o come file JSON che può essere caricato da una libreria client API di Google.
Viene generata e scaricata sul tuo computer una nuova coppia di chiave pubblica/privata, che sarà l'unica copia esistente. Sei responsabile di conservarli in sicurezza.
Flussi OAuth 2.0 comuni
Le seguenti linee guida descrivono i casi d'uso comuni per flussi OAuth 2.0 specifici:
Server web
Questo flusso è adatto per l'accesso automatico/offline/pianificato all'account Google Tag Manager di un utente.
- Aggiornamento automatico delle informazioni di Tag Manager da un server.
Lato client
Ideale per quando gli utenti interagiscono direttamente con l'applicazione per accedere al proprio account Google Tag Manager all'interno di un browser. Questo flusso elimina la necessità di funzionalità lato server, ma rende anche inattuabile la generazione di report automatici/offline/pianificati.
- Uno strumento di configurazione personalizzato basato su browser.
App installate
Per le applicazioni distribuite come pacchetto e installate dall'utente. Richiede che l'applicazione o l'utente abbia accesso a un browser per completare il flusso di autenticazione.
- Un widget desktop su PC o Mac.
- Plug-in per un sistema di gestione dei contenuti. Il vantaggio di questo flusso rispetto al server web o al lato client è che può essere utilizzato un singolo progetto della console API per la tua applicazione. Ciò consente un'installazione più semplice per gli utenti.
Account di servizio
Utile per l'accesso automatico/offline/pianificato al tuo account Google Tag Manager. Ad esempio, per creare uno strumento personalizzato per monitorare il tuo account Google Tag Manager e condividerlo con altri utenti.
Risolvere i problemi
Se il access_token
è scaduto o se utilizzi l'ambito errato per una determinata chiamata API, riceverai un codice di stato 401
nella risposta.
Se l'utente autorizzato non ha accesso all'account o al contenitore Google Tag Manager, riceverai un codice di stato 403
nella risposta. Assicurati di disporre dell'autorizzazione dell'utente corretto e di avere le autorizzazioni per accedere all'account o al contenitore Tag Manager.
OAuth 2.0 Playground
OAuth 2.0 Playground ti consente di esaminare l'intero flusso di autorizzazione attraverso un'interfaccia web. Lo strumento visualizza anche tutte le intestazioni delle richieste HTTP necessarie per eseguire una query autorizzata. Se non riesci a ottenere l'autorizzazione per utilizzare la tua applicazione, dovresti provare a farla funzionare tramite OAuth 2.0 Playground. Poi puoi confrontare le intestazioni HTTP e le richieste provenienti dal parco giochi con ciò che la tua applicazione sta inviando. Questo controllo è un modo semplice per garantire che le richieste vengano formattate correttamente.
Concessione non valida
Se ricevi una risposta di errore invalid_grant
quando cerchi di utilizzare un token di aggiornamento, l'errore potrebbe essere causato da una o entrambe le seguenti cause:
- L'orologio del server non è sincronizzato con il protocollo NTP.
- Hai superato il limite di token di aggiornamento.
Le applicazioni possono richiedere più token di aggiornamento per accedere a un singolo account Google Tag Manager. Ad esempio, questa opzione è utile nei casi in cui un utente voglia installare un'applicazione su più macchine e accedere allo stesso account Google Tag Manager. In questo caso, sono richiesti due token di aggiornamento, uno per ogni installazione. Quando il numero di token di aggiornamento supera il limite, quelli meno recenti non saranno più validi. Se l'applicazione tenta di utilizzare un token di aggiornamento invalidato, viene restituita una risposta di erroreinvalid_grant
. Ogni combinazione univoca di ID client/account può avere fino a 25 token di aggiornamento. Tieni presente che questo limite è soggetto a modifiche. Se l'applicazione continua a richiedere token di aggiornamento per la stessa combinazione di ID client/account, dopo l'emissione del 26° token, il primo token di aggiornamento emesso non è più valido. Il 27° token di aggiornamento richiesto rende non valido il secondo token emesso e così via.