Autorizzazione dell'API Tag Manager

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:

  1. 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.
  2. Attiva l'API Tag Manager nella console API di Google. (Se l'API non è elencata nella console API, salta questo passaggio.)
  3. Quando la tua applicazione vuole accedere ai dati dell'utente, chiede a Google un particolare ambito di accesso.
  4. Google mostra una schermata di consenso all'utente, chiedendo di autorizzare l'applicazione a richiedere dei dati.
  5. Se l'utente approva, Google fornisce alla tua applicazione un token di accesso di breve durata.
  6. L'applicazione richiede i dati utente, allegando il token di accesso alla richiesta.
  7. 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:

  1. Fai clic su Crea credenziali > Chiave account di servizio.
  2. 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.

Esempio:
  • 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.

Esempio:
  • 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.

Esempi:
  • 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:

  1. L'orologio del server non è sincronizzato con il protocollo NTP.
  2. 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 errore invalid_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.