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