Riferimento a Measurement Protocol

Questa pagina descrive il meccanismo di trasporto e i parametri di dati per Measurement Protocol.

Trasporto

Tutti i dati devono essere inviati in modo sicuro utilizzando richieste POST HTTPS.

Invia richieste al seguente endpoint:

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

Se vuoi che i tuoi dati vengano trattati nell'UE, utilizza invece il seguente endpoint:

https://region1.google-analytics.com/mp/collect

Ecco una richiesta POST di esempio:

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
PAYLOAD_DATA

Sostituisci PAYLOAD_DATA con il payload della richiesta.

Measurement Protocol restituisce un codice di stato 2xx se viene ricevuta la richiesta HTTP. Measurement Protocol non restituisce un codice di errore se il payload è formattato in modo errato o se i dati sono errati o non vengono elaborati da Google Analytics.

Payload

Il payload è composto da due parti:

  1. Parametri di query.
  2. Un corpo POST JSON.

Parametri di query

Nome parametro Descrizione

api_secret

Required. L'API Secret dall'interfaccia utente di Google Analytics.

Si trova in Amministrazione > Stream di dati > Scegli lo stream di tuo interesse > Measurement Protocol > Crea.

Privata per la tua organizzazione. Deve essere aggiornato regolarmente per evitare un volume eccessivo di spam.

Corpo POST JSON

Chiave Tipo Descrizione

user_id

string

Facoltativo. un identificatore unico per un utente. Per ulteriori informazioni su questo identificatore, consulta User-ID per l'analisi multipiattaforma. Può includere solo caratteri UTF-8.

timestamp_micros

number

Facoltativo. Un timestamp Unix, microsecondi, non millisecondi. Rappresenta l'ora dell'evento. Deve essere impostato solo per registrare gli eventi che si sono verificati nel passato. Può essere ignorato da user_property o dai timestamp degli eventi. Gli eventi possono essere retrodatati fino a 3 giorni di calendario in base al fuso orario della proprietà.

user_properties

object Facoltativo. Le proprietà utente per la misurazione.

user_data

object Facoltativo. Dati forniti dall'utente.
object Facoltativo. Impostazioni relative al consenso per la richiesta. Per ulteriori informazioni, consulta la sezione sul consenso.

non_personalized_ads

boolean Facoltativo. Impostato su true per indicare che i dati dell'utente non devono essere utilizzati per gli annunci personalizzati.

user_location

object Facoltativo. Imposta le informazioni geografiche per la richiesta in un formato strutturato.

ip_override

string Facoltativo. Indirizzo IP utilizzato da Google Analytics per ricavare informazioni geografiche per la richiesta.

device

object Facoltativo. Imposta le informazioni sul dispositivo per la richiesta in un formato strutturato.

events[]

array Required. Un array di event elementi. È possibile inviare fino a 25 eventi per richiesta. Consulta la documentazione di riferimento sugli eventi per tutti gli eventi validi.

events[].name

string Required. Nome dell'evento. Per tutte le opzioni, consulta la sezione Eventi.

events[].params

object Facoltativo. Parametri per l'evento. Consulta Eventi per i parametri suggeriti per ogni evento.

L'attributo consent configura i tipi e gli stati del consenso. Se non specifichi consent, Google Analytics utilizza le impostazioni del consenso dalle interazioni online corrispondenti per il client o l'istanza dell'app.

Chiave Tipo Descrizione

ad_user_data

string

Facoltativo. Consenso per l'invio a Google dei dati utente provenienti dagli eventi e dalle proprietà utente della richiesta per scopi pubblicitari.

GRANTED o DENIED.

ad_personalization

string

Facoltativo. Consenso per la pubblicità personalizzata per l'utente.

GRANTED o DENIED.

Informazioni geografiche

Gli attributi user_location e ip_override forniscono informazioni geografiche. user_location ha la precedenza su ip_override.

Ecco la struttura del campo user_location. Fornisci il maggior numero possibile di attributi. Ti consigliamo di scegliere almeno country_id e region_id.

Chiave Tipo Descrizione

city

string Facoltativo. Il nome della città. Se la città si trova negli Stati Uniti, imposta anche country_id e region_id in modo che Google Analytics possa mappare correttamente il nome della città a un ID città.

region_id

string Facoltativo. Il paese e la suddivisione ISO 3166. Ad esempio, US-CA, US-AR, CA-BC, GB-LND, CN-HK.

country_id

string Facoltativo. Il paese in formato ISO 3166-1 alpha-2. Ad esempio, US, AU, ES, FR.

subcontinent_id

string Facoltativo. Il subcontinente in formato UN M49. Ad esempio, 011, 021, 030, 039.

continent_id

string Facoltativo. Il continente in formato UN M49. Ad esempio, 002, 019, 142, 150.

Ecco un user_location di esempio:

"user_location": {
  "city": "Mountain View",
  "region_id": "US-CA",
  "country_id": "US",
  "subcontinent_id": "021",
  "continent_id": "019"
}

ip_override è un'alternativa a user_location. Se invii ip_override invece, Google Analytics ricava le informazioni geografiche dall'indirizzo IP. Se invii user_location, Google Analytics ignora ip_override.

Se non invii user_location o ip_override, Google Analytics ricava le informazioni geografiche dagli eventi di tagging utilizzando client_id.

Google Analytics applica alla richiesta le impostazioni dei dati sulla posizione granulari della proprietà, indipendentemente dalle informazioni geografiche inviate.

Informazioni del dispositivo

Per inviare le informazioni del dispositivo, utilizza il campo device. Ecco la struttura del campo device. Fornisci il maggior numero possibile di attributi. Consigliamo di utilizzare almeno category.

Chiave Tipo Descrizione

category

string Facoltativo. La categoria del dispositivo. Ad esempio, desktop, tablet, mobile, smart TV.

language

string Facoltativo. La lingua in formato ISO 639-1. Ad esempio, en, en-US.

screen_resolution

string Facoltativo. La risoluzione del dispositivo, formattata come WIDTHxHEIGHT. Ad esempio, 1280x2856, 1080x2340.

operating_system

string Facoltativo. Il sistema operativo o la piattaforma. Ad esempio, MacOS.

operating_system_version

string Facoltativo. La versione del sistema operativo o della piattaforma. Ad esempio 13.5.

model

string Facoltativo. Il modello del dispositivo. Ad esempio, Pixel 9 Pro, Samsung Galaxy S24.

brand

string Facoltativo. Il brand del dispositivo. Ad esempio, Google, Samsung.

browser

string Facoltativo. Il brand o il tipo di browser. Ad esempio, Chrome, Firefox.

browser_version

string Facoltativo. La versione del browser. Ad esempio, 136.0.7103.60, 5.0.

Lo snippet seguente mostra un esempio di impostazioni device:

"device": {
  "category": "mobile",
  "language": "en",
  "screen_resolution": "1280x2856",
  "operating_system": "Android",
  "operating_system_version": "14",
  "model": "Pixel 9 Pro",
  "brand": "Google",
  "browser": "Chrome",
  "browser_version": "136.0.7103.60"
}

Indipendentemente dal fatto che specifichi Google Analytics applica alla richiesta le impostazioni dei dati granulari dei dispositivi della proprietà.

Parametri personalizzati

Puoi includere parametri personalizzati basati sugli utenti, sugli eventi e sugli articoli in un payload Measurement Protocol.

  • In user_properties è possibile includere parametri personalizzati basati sugli utenti.
  • I parametri personalizzati basati sugli eventi possono essere inclusi in events[].params.
  • I parametri personalizzati basati sugli articoli possono essere inclusi in items.

Alcuni eventi hanno parametri consigliati. Consulta events per i parametri consigliati per tutti gli eventi supportati.

Nomi riservati

Alcuni nomi di eventi, parametri e proprietà utente sono riservati e non possono essere utilizzati:

Nomi di eventi riservati

I seguenti nomi di eventi sono riservati e non possono essere utilizzati:

  • ad_activeview
  • ad_click
  • ad_exposure
  • ad_query
  • ad_reward
  • adunit_exposure
  • app_clear_data
  • app_exception
  • app_install
  • app_remove
  • app_store_refund
  • app_update
  • app_upgrade
  • dynamic_link_app_open
  • dynamic_link_app_update
  • dynamic_link_first_open
  • error
  • firebase_campaign
  • firebase_in_app_message_action
  • firebase_in_app_message_dismiss
  • firebase_in_app_message_impression
  • first_open
  • first_visit
  • in_app_purchase
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

Nomi riservati dei parametri

I seguenti nomi di parametri sono riservati e non possono essere utilizzati:

  • firebase_conversion

I nomi dei parametri non possono iniziare con quanto segue:

  • _ (underscore)
  • firebase_
  • ga_
  • google_
  • gtag.

Nomi di proprietà utente riservati

I seguenti nomi di proprietà utente sono riservati e non possono essere utilizzati:

  • first_open_time
  • first_visit_time
  • last_deep_link_referrer
  • user_id
  • first_open_after_install

Inoltre, i nomi delle proprietà utente non possono iniziare con:

  • _ (underscore)
  • firebase_
  • ga_
  • google_