Riferimento a Measurement Protocol

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

Trasporto

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

Invia richieste al seguente endpoint:

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

Se vuoi che i tuoi dati vengano raccolti 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 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. Il valore di API Secret dall'interfaccia utente di Google Analytics.

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

Privato per la tua organizzazione. Deve essere aggiornato regolarmente per evitare un eccessivo 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 in passato. Può essere sostituito da user_property o dai timestamp degli eventi. Gli eventi possono essere retrodatati fino a tre 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 saperne di più, consulta la sezione relativa al consenso.

non_personalized_ads

 boolean Facoltativo. Imposta 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 derivare le 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 il riferimento agli eventi per tutti gli eventi validi.

events[].name

 string Required. Il nome dell'evento. Consulta la sezione Eventi per tutte le opzioni.

events[].params

 object Facoltativo. Parametri dell'evento. Consulta Eventi per i parametri suggeriti per ogni evento e Parametri evento comuni.

Parametri evento comuni

Measurement Protocol ha i seguenti parametri evento comuni:

Chiave Tipo Descrizione

session_id

 number Un numero positivo che identifica la sessione utente. Necessario per diversi casi d'uso comuni. Deve corrispondere all'espressione regolare ^\d+$.

engagement_time_msec

 number La durata del coinvolgimento degli utenti, in millisecondi, per l'evento. Utilizza un valore che rifletta la quantità di tempo di coinvolgimento dell'utente dall'evento precedente.

timestamp_micros

 number Il timestamp dell'epoca di Unix, in microsecondi, per l'evento. Utilizza questo parametro per ignorare il timestamp dell'evento.

L'attributo consent configura i tipi e gli stati di consenso. Se non specifichi consent, Google Analytics utilizza le impostazioni del consenso delle 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 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 nel formato ISO 3166-1 alpha-2. Ad esempio, US, AU, ES, FR.

subcontinent_id

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

continent_id

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

Ecco un esempio di user_location:

"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 invece invii ip_override, 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 le impostazioni dei dati sulla posizione granulari della proprietà alla richiesta, 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 un minimo di category.

Chiave Tipo Descrizione

category

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

language

 string (Facoltativo) La lingua nel 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.

Il seguente snippet 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 tu 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.

  • I parametri personalizzati con ambito utente possono essere inclusi in user_properties.
  • I parametri personalizzati con ambito evento possono essere inclusi in events[].params.
  • I parametri personalizzati con ambito articolo possono essere inclusi in items.

Alcuni eventi hanno parametri consigliati. Consulta la sezione Eventi 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:

  • _ (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_