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
- Vero0
- 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.