Riferimento a Measurement Protocol

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

Trasporto

Tutti i dati devono essere inviati in modo sicuro utilizzando 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 un esempio di richiesta POST:

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 la richiesta HTTP viene ricevuta. Measurement Protocol non restituisce un codice di errore se il payload non è corretto o se i dati non sono corretti o non vengono elaborati da Google Analytics.

Payload

Il payload è composto da due parti:

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

Parametri di query

Nome parametro Descrizione

api_secret

 Required. Il valore dell'API Secret dall'interfaccia utente di Google Analytics.

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

Privato per la tua organizzazione. Deve essere aggiornato regolarmente per evitare spam eccessivo.

firebase_app_id

 Required. ID app Firebase. L'identificatore di un'app Firebase.

Disponibile nella console Firebase in Impostazioni progetto > Generali > Le tue app > ID app.

Corpo POST JSON

Le dimensioni del corpo POST JSON devono essere inferiori a 130 kB.

Chiave Tipo Descrizione

app_instance_id

 string Required. Identificatore univoco di un'installazione specifica di un'app Firebase.

Non è lo stesso di un client_id web.

Deve essere recuperato utilizzando l'SDK Firebase:

user_id

 string

Facoltativo. un identificatore unico per un utente. Per saperne di più 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 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 72 ore.

user_properties

 object Facoltativo. Le proprietà utente per la misurazione. Per ogni richiesta è possibile inviare fino a 25 proprietà utente. I nomi delle proprietà utente non possono superare i 24 caratteri e i valori delle proprietà utente non possono superare i 36 caratteri.

user_data

 object Facoltativo. Dati forniti dagli utenti.
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 ricavare le informazioni geografiche per la richiesta.

device

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

validation_behavior

 string

Facoltativo. Imposta il comportamento di convalida per la richiesta.

RELAXED o ENFORCE_RECOMMENDATIONS. Se non specificato, il valore predefinito è RELAXED.

events[]

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

events[].name

 string Required. Il nome dell'evento. I nomi evento devono contenere al massimo 40 caratteri. Consulta la sezione Eventi per gli eventi consigliati.

events[].params

 object Facoltativo. Parametri per l'evento. Per ogni evento è possibile inviare fino a 25 parametri. Consulta la sezione Eventi per i parametri consigliati per ogni evento e Parametri evento comuni.

I nomi dei parametri devono contenere al massimo 40 caratteri. I valori parametro devono contenere al massimo 100 caratteri per una proprietà Google Analytics standard e al massimo 500 caratteri per una proprietà Google Analytics 360.

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. Obbligatorio per diversi casi d'uso comuni. Deve corrispondere all'espressione regolare ^\d+$.

Deve essere recuperato utilizzando l'SDK Firebase:

engagement_time_msec

 number La durata del coinvolgimento degli utenti, in millisecondi, per l'evento. Utilizza un valore che rifletta la durata del coinvolgimento degli utenti dall'evento precedente.

timestamp_micros

 number Il timestamp dell'epoca di Unix, in microsecondi, per l'evento. Utilizza questo parametro per eseguire l'override del timestamp dell'evento.

L'attributo consent configura i tipi e gli stati del consenso. Se non specifichi consent, Google Analytics utilizza le impostazioni del consenso delle interazioni online corrispondenti per il client o l'istanza di 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. 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 utilizzandoapp_instance_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 sul dispositivo, utilizza il campo device. Ecco la struttura del campo device. Fornisci il maggior numero possibile di attributi. Consigliamo almeno 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"
}
Se una richiesta non specifica device, Google Analytics ricava le informazioni sul dispositivo dagli eventi di tagging utilizzando app_instance_id.

Indipendentemente dal fatto che tu specifichi device, Google Analytics applica alla richiesta le impostazioni dei dati granulari del dispositivo della proprietà.

Comportamento di convalida

L'attributo validation_behavior controlla il modo in cui Measurement Protocol convalida i contenuti della richiesta.

  • La convalida di RELAXED rifiuta solo le richieste non in un formato corretto. Potrebbe comunque accettare eventi e parametri con nomi di campi non validi o con dati non del tipo corretto, ma ignora i parametri che superano i limiti. Per impostazione predefinita, il Measurement Protocol utilizza la convalida RELAXED.
  • La convalida di ENFORCE_RECOMMENDATIONS rifiuta i parametri evento e articolo che non sono del tipo corretto o che contengono parametri che superano i limiti. Inoltre, ENFORCE_RECOMMENDATIONS rifiuta qualsiasi evento o proprietà utente con un timestamp che non rientra nelle ultime 72 ore.

Ti consigliamo di procedere come segue:

  • Utilizza ENFORCE_RECOMMENDATIONS quando convalidi gli eventi per ricevere il maggior numero possibile di feedback sui potenziali problemi relativi alle tue richieste.

    Puoi anche convalidare le richieste utilizzando lo Strumento per la creazione di eventi, poiché specifica ENFORCE_RECOMMENDATIONS durante la convalida delle richieste.

  • Non specificare validation_behavior quando invii eventi per ridurre al minimo i dati rifiutati da Measurement Protocol.

    Se vuoi dare la priorità alla convalida rigorosa rispetto alla raccolta dei dati quando invii una richiesta specifica, aggiungi il campo validation_behavior e impostalo su ENFORCE_RECOMMENDATIONS.

Parametri personalizzati

Puoi includere parametri personalizzati con ambito utente, con ambito evento e con ambito articolo in un payload di 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
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

Inoltre, gli eventi ad_impression, in_app_purchase e screen_view sono consentiti solo per gli stream di app.

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_