Questa guida spiega come inviare eventi di stream web e di app Measurement Protocol di Google Analytics a un server Google Analytics, in modo da poter visualizzare gli eventi Measurement Protocol nei tuoi report di Google Analytics.
Gli identificatori e i parametri richiesti per le richieste Measurement Protocol dipendono dal fatto che tu stia inviando eventi a uno stream web o a uno stream di app.
- Per gli stream web (in genere strumentati con gtag.js o Google Tag Manager), utilizzi
measurement_idnell'URL della richiesta eclient_idnel corpo JSON per identificare l'istanza utente.client_iddeve corrispondere all'ID generato dal tag Google Analytics sul tuo sito web. - Per gli stream di app (strumentati con l'SDK Firebase), utilizzi
firebase_app_idnell'URL della richiesta eapp_instance_idnel corpo JSON, forniti dall'SDK Google Analytics for Firebase.
Questa guida fornisce esempi per entrambi gli scenari.
Componenti chiave della richiesta per tipo di stream
| Componente | Stream web (gtag.js/GTM) | Stream di app (Firebase) |
|---|---|---|
| Parametro URL dello stream di dati | measurement_id |
firebase_app_id |
| Parametro URL API secret | Obbligatorio | Obbligatorio |
| Campo del corpo JSON ID dispositivo | client_id |
app_instance_id |
Scegli la piattaforma che vuoi visualizzare in questa guida:
Questa scheda mostra le istruzioni per l'invio di eventi dal server che sono correlati all'attività dell'utente in uno stream di app utilizzando l'SDK Google Analytics for Firebase. Tieni presente che queste richieste utilizzano firebase_app_id e app_instance_id.
Prerequisiti
Per inviare eventi utilizzando Measurement Protocol, hai bisogno di identificatori specifici della proprietà Google Analytics o del progetto Firebase.
API secret
api_secret viene utilizzato per autenticare le richieste. È fondamentale mantenere riservato questo secret.
Per creare un nuovo secret:
- Vai a Google Analytics e naviga a il tuo account e alla tua proprietà.
- Fai clic su Amministrazione in basso a sinistra.
- In Raccolta e modifica dei dati, fai clic su Stream di dati.
- Seleziona lo stream di dati web o di app.
- Fai clic su API secret di Measurement Protocol.
- Fai clic su Crea.
- Inserisci un nickname per il secret e fai clic su Crea.
Copia il valore del secret.
ID app Firebase
firebase_app_id identifica la tua app Firebase. È diverso da app_instance_id.
Per trovare l'ID app Firebase:
- Apri il progetto nella console Firebase.
- Fai clic sull'icona a forma di ingranaggio delle impostazioni accanto a Panoramica del progetto e seleziona Impostazioni progetto.
- Nella scheda Generali, vai alla sezione Le tue app.
- Seleziona l'app iOS o Android specifica.
- Copia il valore ID app.
Formattazione della richiesta
Measurement Protocol di Google Analytics supporta solo le richieste HTTP POST.
Per inviare un evento, utilizza il seguente formato:
POST /mp/collect?firebase_app_id=<var>FIREBASE_APP_ID</var>&api_secret=<var>API_SECRET</var> HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
PAYLOAD_DATA
Devi fornire quanto segue nei parametri di query dell'URL della richiesta (consulta Prerequisiti per i dettagli su come trovare o creare questi valori):
api_secret: l'API secret per autenticare la richiesta.firebase_app_id: l'ID app Firebase della tua applicazione.
Devi fornire un corpo della richiesta nel formato del corpo JSON POST per Measurement Protocol. Ecco un esempio:
{
"app_instance_id": "APP_INSTANCE_ID",
"events": [
{
"name": "login",
"params": {
"method": "Google",
"session_id": "SESSION_ID",
"engagement_time_msec": 100
}
}
]
}
Devi fornire app_instance_id nel corpo della richiesta per identificare un'installazione univoca della tua app mobile. Tieni presente che è diverso da firebase_app_id, che identifica l'app stessa. Per saperne di più su
app_instance_id e su come recuperarlo utilizzando l'SDK Firebase, consulta la
documentazione di riferimento di app_instance_id.
Anche se session_start è un nome di evento riservato, la creazione di un nuovo session_id crea una nuova sessione senza la necessità di inviare session_start. Scopri come vengono conteggiate le sessioni.
Prova
Ecco un esempio che puoi utilizzare per inviare più eventi contemporaneamente. Questo esempio
invia un evento tutorial_begin e un evento
join_group al server Google Analytics, include informazioni geografiche utilizzando il campo user_location e include informazioni sul dispositivo
utilizzando il campo device.
const firebaseAppId = "FIREBASE_APP_ID";
const apiSecret = "API_SECRET";
fetch(`https://www.google-analytics.com/mp/collect?firebase_app_id=${firebaseAppId}&api_secret=${apiSecret}`, {
method: "POST",
headers: {
"Content-Type": "application/json"
},
body: JSON.stringify({
app_instance_id: "APP_INSTANCE_ID",
events: [
{
name: "tutorial_begin",
params: {
"session_id": "SESSION_ID",
"engagement_time_msec": 100
}
},
{
name: "join_group",
params: {
"group_id": "G_12345",
"session_id": "SESSION_ID",
"engagement_time_msec": 150
}
}
],
user_location: {
city: "Mountain View",
region_id: "US-CA",
country_id: "US",
subcontinent_id: "021",
continent_id: "019"
},
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"
}
})
});
Il formato di firebase_app_id è specifico della piattaforma. Consulta ID applicazione
in File e oggetti di configurazione Firebase.
Override del timestamp
Measurement Protocol utilizza il primo timestamp che trova nel seguente elenco per ogni evento e proprietà utente nella richiesta:
timestamp_microsdell'evento o della proprietà utente.timestamp_microsdella richiesta.- L'ora in cui Measurement Protocol riceve la richiesta.
L'esempio seguente invia un timestamp a livello di richiesta che si applica a tutti gli
eventi e proprietà
utente nella
richiesta. Di conseguenza, Measurement Protocol assegna un timestamp di requestUnixEpochTimeInMicros agli eventi tutorial_begin e join_group e alla proprietà utente customer_tier.
{
"timestamp_micros": requestUnixEpochTimeInMicros,
"events": [
{
"name": "tutorial_begin"
},
{
"name": "join_group",
"params": {
"group_id": "G_12345",
}
}
],
"user_properties": {
"customer_tier": {
"value": "PREMIUM"
}
}
}
L'esempio seguente invia un timestamp a livello di richiesta, un timestamp a livello di evento e un timestamp a livello di proprietà utente. Di conseguenza, Measurement Protocol assegna i seguenti timestamp:
tutorialBeginUnixEpochTimeInMicrosper l'eventotutorial_begincustomerTierUnixEpochTimeInMicrosper la proprietà utentecustomer_tierrequestUnixEpochTimeInMicrosper l'eventojoin_groupe la proprietà utentenewsletter_reader.
{
"timestamp_micros": requestUnixEpochTimeInMicros,
"events": [
{
"name": "tutorial_begin",
"timestamp_micros": tutorialBeginUnixEpochTimeInMicros
},
{
"name": "join_group",
"params": {
"group_id": "G_12345",
}
}
],
"user_properties": {
"customer_tier": {
"value": "PREMIUM",
"timestamp_micros": customerTierUnixEpochTimeInMicros
},
"newsletter_reader": {
"value": "true"
}
}
}
Comportamento di convalida per eventi e proprietà utente passati
Gli eventi e le proprietà utente possono essere retrodatati fino a 72 ore. Se il valore timestamp_micros è precedente a 72 ore fa, Measurement Protocol accetta o rifiuta l'evento o la proprietà utente come segue:
- Se
validation_behaviornon è impostato o è impostato suRELAXED, Measurement Protocol accetta l'evento o la proprietà utente, ma sostituisce il timestamp con 72 ore fa. - Se
validation_behaviorè impostato suENFORCE_RECOMMENDATIONS, Measurement Protocol rifiuta l'evento o la proprietà utente.
Gli eventi inviati utilizzando Measurement Protocol che devono essere uniti o elaborati insieme agli eventi raccolti dall'SDK Google Analytics for Firebase o da gtag.js devono essere ricevuti da Google Analytics entro 48 ore dal timestamp dell'evento lato client originale. Gli eventi ricevuti in un secondo momento potrebbero non essere elaborati come previsto, in particolare per scopi come l'attribuzione delle conversioni.
Limitazioni
Le seguenti limitazioni si applicano all'invio di eventi Measurement Protocol a Google Analytics:
Puoi inviare al massimo 100 milioni di richieste non di conversione all'ora per ogni proprietà. Una richiesta è una richiesta non di conversione se nessuno degli eventi nella richiesta è un evento chiave per il quale esiste una conversione in Google Ads. Se superi questo limite, Measurement Protocol ignora silenziosamente tutte le richieste non di conversione per la proprietà per il resto dell'ora.
Le richieste possono avere al massimo 25 eventi.
Gli eventi possono avere al massimo 25 parametri.
Gli eventi possono avere al massimo 25 proprietà utente.
I nomi delle proprietà utente non possono superare i 24 caratteri.
I valori delle proprietà utente non possono superare i 36 caratteri.
I nomi degli eventi devono avere una lunghezza massima di 40 caratteri, possono contenere solo caratteri alfanumerici e trattini bassi e devono iniziare con un carattere alfabetico.
I nomi dei parametri, inclusi i parametri articolo, non devono superare i 40 caratteri, possono contenere solo caratteri alfanumerici e trattini bassi e devono iniziare con un carattere alfabetico.
I valori dei parametri, inclusi i valori parametro articolo, non devono superare i 100 caratteri per una proprietà Google Analytics standard e i 500 caratteri per una proprietà Google Analytics 360.
Questo limite non si applica ai parametri
session_idesession_numberquando i relativi valori vengono forniti dalle variabili integrate ID sessione di Analytics e Numero sessione di Analytics corrispondenti in Google Tag Manager.I parametri articolo possono avere un massimo di 10 parametri personalizzati.
Il corpo del post deve essere inferiore a 130 kB.
Gli eventi Measurement Protocol di app inviati a Google Analytics non compilano i segmenti di pubblico di ricerca in Google Ads per gli utenti delle app.
Alcuni nomi di eventi, parametri e proprietà utente sono riservati e non possono essere utilizzati. Per maggiori dettagli, consulta Nomi riservati per dettagli.
Nomi riservati
Measurement Protocol ha diversi nomi riservati che non possono essere utilizzati per eventi, parametri o proprietà utente.
I seguenti nomi di eventi sono punti di confusione comuni:
screen_view: questo evento è consentito solo per gli stream di app. Per gli stream web, utilizza invecepage_view.ad_impression: questo evento è consentito solo per gli stream di app.in_app_purchase: questo evento è consentito solo per gli stream di app. Per gli stream web, utilizza invece l'purchase.
Per ulteriori requisiti di ogni caso d'uso, consulta Casi d'uso comuni.