Riferimento Measurement Protocol

Questo documento descrive come inviare i dati a Google Analytics utilizzando il Measurement Protocol.

Panoramica

Per inviare i dati a Google Analytics utilizzando il Measurement Protocol, devi procedere in due parti:

  • Il trasporto: dove e come invii i dati
  • Payload, ovvero i dati che invii

Questo documento descrive come formattare entrambi.

Trasporto

Endpoint URL

Puoi inviare i dati utilizzando Measurement Protocol effettuando richieste HTTP al seguente endpoint:

https://www.google-analytics.com/collect

Tutti i dati devono essere inviati in modo sicuro con il protocollo HTTPS.

Puoi inviare dati utilizzando richieste POST o GET.

Utilizzo di POST

Consigliamo di inviare i dati tramite POST perché consente un payload più grande. Quando utilizzi POST, invia la seguente richiesta HTTP:

User-Agent: user_agent_string
POST https://www.google-analytics.com/collect
payload_data

Dove:

  • user_agent_string: è una stringa di user agent formattata che viene utilizzata per calcolare le seguenti dimensioni: funzionalità browser, piattaforma e dispositivi mobili.

    Se questo valore non è impostato, i dati precedenti non verranno calcolati.

  • payload_data – Il valore BODY della richiesta di post. Il corpo deve includere esattamente 1 payload codificato con URI e non deve superare i 8192 byte.
  • Indirizzo IP: viene inviato implicitamente nella richiesta HTTP e viene utilizzato per calcolare tutte le dimensioni geografiche / di rete in Google Analytics.

GET

Per gli ambienti in cui non è possibile inviare dati POST, puoi anche inviare richieste HTTP GET allo stesso punto di arrivo:

GET /collect?payload_data HTTP/1.1
Host: https://www.google-analytics.com
User-Agent: user_agent_string

Dove i dati del payload vengono inviati come parametri di query con caratteri di escape dell'URI. La lunghezza dell'intero URL codificato non deve essere superiore a 8000 byte.

Busting della cache

In alcuni ambienti, come i browser, le richieste HTTP GET potrebbero essere memorizzate nella cache. Quando una richiesta viene memorizzata nella cache, le richieste successive potrebbero essere recuperate dalla cache e non inviate a Google Analytics. Per eseguire il busting della cache, Measurement Protocol fornisce un parametro speciale (z) che può essere impostato con un numero casuale. Ciò garantisce che tutte le richieste di Measurement Protocol siano univoche e che le richieste successive non vengano recuperate dalla cache.

Quando utilizzi il busting della cache, ti consigliamo vivamente di aggiungere questo parametro come ultimo parametro nel payload.

https://www.google-analytics.com/collect?payload_data&z=123456

Codici di risposta

Measurement Protocol restituisce un codice di stato 2xx se la richiesta HTTP è stata ricevuta. Measurement Protocol non restituisce un codice di errore se i dati del payload erano in formato non corretto o se i dati nel payload erano errati o non sono stati elaborati da Google Analytics.

Se non ricevi un codice di stato 2xx, NON riprovare a effettuare la richiesta. Devi invece interrompere e correggere eventuali errori nella richiesta HTTP.

Dati payload

Tutti i dati raccolti da Google Analytics utilizzando il Measurement Protocol vengono inviati come payload. Il payload è simile a una stringa di query dell'URL in cui ogni parametro ha una chiave e un valore, è separato da un carattere = e ogni coppia è delimitata da un carattere &. Ad esempio:

key1=val1&key2=val2

Ogni payload ha regole che regolano: i valori obbligatori, la codifica URI, i parametri che possono essere inviati insieme e la lunghezza dei parametri. Inoltre, ogni parametro ha un tipo specifico che richiede un formato particolare. Le sezioni seguenti illustrano queste regole.

Leggi la pagina Riferimento parametri per un elenco completo di tutti i parametri che puoi inviare utilizzando Measurement Protocol.

Valori obbligatori per tutti gli hit

In ogni payload devono essere presenti i seguenti parametri:

Nome Parametro Esempio Descrizione
Versione protocollo v v=1 La versione del protocollo. Il valore deve essere 1.
ID monitoraggio tid tid=UA-123456-1 L'ID che distingue a quale proprietà Google Analytics inviare i dati.
ID client cid cid=xxxxx L'ID univoco di un determinato utente.
Tipo di hit t t=pageview Il tipo di interazione raccolta per un determinato utente.

I dati Client ID e Hit Type sono valori che corrispondono direttamente al modello dei dati di Google Analytics. Se volessi monitorare l'utente 5555 che ha visitato /pageA, /pageB e /pageC, dovresti inviare i seguenti 3 payload:

v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageA
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageB
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageC

Tieni presente che / è stato codificato in %2F.

Valori di codifica URL

Tutti i valori inviati a Google Analytics devono essere sia UTF-8 sia con codifica URL. Per inviare la chiave dp con il valore /my page €, devi prima assicurarti che la chiave sia UTF-8 e poi URL codificata, ottenendo la stringa finale:

dp=%2Fmy%20page%20%E2%82%AC

Se alcuni caratteri non sono stati codificati in modo corretto, verranno sostituiti con il carattere sostitutivo Unicode xFFFD.

Valori obbligatori per determinati tipi di hit

Alcuni parametri possono essere inviati solo con tipi di hit specifici. Ad esempio, il tipo di hit pageview richiede che sia impostato anche il parametro Percorso pagina (dp). La sezione Riferimento parametri descrive quali parametri sono necessari per determinati tipi di hit.

Lunghezza massima

Alcuni valori di testo in Measurement Protocol hanno lunghezze massime specifiche in byte. Ad esempio, il campo del referrer del documento dr ha una lunghezza massima di 2048 byte. I valori che superano le lunghezze massime verranno troncati automaticamente. Se un carattere multibyte supera la lunghezza massima, l'intero carattere verrà troncato.

Tipi di dati supportati

Ogni campo di dati in Measurement Protocol appartiene a un tipo specifico, ciascuno con le proprie regole di convalida. Se uno o più valori dei parametri non sono conformi alle regole di convalida, quel parametro specifico verrà ignorato e non elaborato da Google Analytics. Tutti gli altri parametri verranno elaborati normalmente.

Measurement Protocol supporta i seguenti tipi di dati:

Tieni presente che i singoli campi di dati possono avere le proprie restrizioni. Consulta la documentazione di riferimento sui campi per un elenco completo di tutti i campi di dati e dei tipi accettati.

Testo

Utilizzato per rappresentare le stringhe. Vengono eseguite ulteriori elaborazioni sui campi di testo. Vengono rimossi tutti gli spazi vuoti iniziali e finali. Le esecuzioni interne di due o più caratteri di spaziatura (inclusi spazio, tabulazione, ritorni a capo e così via) vengono ridotte a un singolo carattere di spazio. Questa trasformazione viene applicata al testo non elaborato prima del troncamento. Ad esempio:

   Hello      World

diventerà:

Hello World

Valuta

Utilizzato per rappresentare il valore totale di una valuta. Un punto decimale viene utilizzato come delimitatore tra la parte intera e la parte frazionaria della valuta. La precisione arriva a un massimo di 6 punti decimali. Per un campo valuta è valido quanto segue:

1000.000001

Una volta inviato il valore a Google Analytics, tutto il testo viene rimosso fino alla prima cifra, al carattere - o al carattere . (decimale). Pertanto:

$-55.00

diventerà:

-55.00

Booleano

Utilizzato per determinare se un valore è vero o falso. I valori validi sono:

  • 1 - Vero
  • 0 - Falso

Numero intero

Utilizzato per rappresentare un numero intero. Il valore viene memorizzato come int64 con accesso

Numero

Utilizzato per rappresentare un numero intero o con rappresentazione in virgola mobile.