Questa documentazione è per Universal Analytics. Se utilizzi Google Analytics 4, consulta Measurement Protocol (Google Analytics 4).

Riferimento a Measurement Protocol

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

Panoramica

Sono disponibili due passaggi per inviare dati a Google Analytics tramite Measurement Protocol:

  • Il trasporto, a dove e come inviare i dati
  • Il payload: i dati che invii

Questo documento descrive come formattare entrambi.

Trasporto

Endpoint URL

Invia i dati utilizzando Measurement Protocol effettuando 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 le richieste POST o GET.

Utilizzo di POST

Ti consigliamo di inviare i dati tramite POST perché consente un payload più elevato. Quando utilizzi POST, esegui 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: browser, piattaforma e funzionalità per dispositivi mobili.

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

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

RICEVI

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 ricerca con escape. 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 scorrere la cache, Measurement Protocol fornisce un parametro speciale (z) che può essere impostato con un numero casuale. In questo modo tutte le richieste di Measurement Protocol sono univoche e le richieste successive non vengono recuperate dalla cache.

Quando utilizzi il cachebuster, ti consigliamo vivamente di aggiungere questo parametro come ultimo parametro del payload.

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

Codici di risposta

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

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

Dati payload

Tutti i dati raccolti da Google Analytics tramite Measurement Protocol vengono inviati come payload. Il payload è simile a una stringa di query 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: valori richiesti, codifica URI, parametri che possono essere inviati insieme e lunghezza dei parametri. Inoltre, ogni parametro ha un tipo specifico che richiede un determinato formato. Queste regole sono soggette alle regole descritte di seguito.

Consulta il riferimento sui parametri per un elenco completo di tutti i parametri che puoi inviare utilizzando Measurement Protocol.

Valori obbligatori per tutti gli hit

Per ogni payload è necessario inserire 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 la proprietà Google Analytics a cui inviare i dati.
Client-ID cid cid=xxxxx Un ID univoco per 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 mappati direttamente al modello di dati di Google Analytics. Se vuoi monitorare l'utente 5555 che è andato a /pageA, /pageB e /pageC, devi 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 il codice / è stato codificato in %2F.

Valori di codifica URL

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

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

Se uno dei caratteri viene codificato in modo errato, verrà sostituito dal carattere di sostituzione Unicode xFFFD.

Valori obbligatori per alcuni tipi di hit

Alcuni parametri possono essere inviati solo con tipi di hit specifici. Ad esempio, il tipo di hit pageview richiede l'impostazione del parametro Percorso pagina (dp). Il Riferimento ai parametri descrive quali parametri sono richiesti per quali tipi di hit.

Lunghezza massima

Alcuni valori di testo in Measurement Protocol hanno lunghezze massime specifiche in byte. Ad esempio, la lunghezza massima del campo referrer documento dr è di 2048 byte. Se uno qualsiasi dei valori supera le lunghezze massime, verrà automaticamente troncato. 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 dei valori del parametro non è conforme 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 potrebbero avere restrizioni proprie. Consulta la documentazione sul campo per un elenco completo di tutti i campi di dati e i tipi accettati.

Testo

Utilizzato per rappresentare le stringhe. L'elaborazione aggiuntiva viene eseguita sui campi di testo. Tutti i caratteri iniziali e finali vengono rimossi. Le esecuzioni interne di due o più caratteri di spazio vuoto (inclusi spazio, tabulazione, nuove righe e così via) sono ridotte a un singolo carattere di spazio. Questa trasformazione viene applicata al testo non elaborato prima di qualsiasi troncamento. Ad esempio:

   Hello      World

diventerà:

Hello World

Valuta

Utilizzato per rappresentare il valore totale di una valuta. Viene utilizzato un punto decimale come delimitatore tra la parte intera e quella frazionata della valuta. La precisione arriva a un massimo di 6 punti decimali. Quanto segue è valido per un campo di valuta:

1000.000001

Una volta che il valore viene inviato 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 un int64 firmato

Numero

Utilizzato per rappresentare un numero intero o con virgola mobile.