Riferimento a Measurement Protocol

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

Panoramica

La procedura per inviare i dati a Google Analytics utilizzando Measurement Protocol si compone di due parti:

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

In questo documento viene descritto come formattare entrambi.

Trasporto

Endpoint URL

I dati vengono inviati utilizzando Measurement Protocol inoltrando richieste HTTP al seguente punto di arrivo:

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 user agent formattata 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 BODY della richiesta di post. Il corpo deve includere esattamente un payload con codifica URI e non deve superare gli 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 puoi 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 escape 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 possono 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 restituirà un codice di stato 2xx se è stata ricevuta la richiesta HTTP. Measurement Protocol non restituisce un codice di errore se il formato dei dati del payload è errato 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 presenti 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 include regole che regolano: valori obbligatori, codifica URI, parametri che possono essere inviati insieme e lunghezza dei parametri. Inoltre, ogni parametro ha un tipo specifico che richiede un determinato formato. 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

I seguenti parametri devono essere inclusi in ogni payload:

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 vengono mappati direttamente al modello dei dati di Google Analytics. Se vuoi 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

Nota che / è stato codificato in %2F.

Valori di codifica URL

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

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

Se la codifica non è corretta, alcuni caratteri 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 venga impostato anche il parametro Percorso pagina (dp). La sezione Riferimento parametri descrive i parametri richiesti per i 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 nel 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, il parametro specifico in questione 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 potrebbero avere le proprie restrizioni. Consulta Riferimento campi per un elenco completo di tutti i campi di dati e dei tipi accettati.

Testo

Utilizzato per rappresentare le stringhe. Viene eseguita un'ulteriore elaborazione dei campi di testo. Tutti gli spazi vuoti iniziali e finali vengono rimossi. Le esecuzioni interne di due o più caratteri di spazio vuoto (inclusi spazio, tabulazione, a capo e così via) vengono ridotte a un singolo carattere di spazio. Questa trasformazione viene applicata al testo non elaborato prima che avvenga qualsiasi 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 il campo della 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 file int64 connesso

Numero

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