Inviare eventi Measurement Protocol a Google Analytics

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 report di Google Analytics.

Scegli la piattaforma che vuoi visualizzare in questa guida:

Firebase gtag.js

Formattazione della richiesta

Measurement Protocol di Google Analytics supporta solo le richieste HTTP POST.

Per inviare un evento, utilizza il formato seguente:

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

PAYLOAD_DATA

Suggerimento: se vuoi che i tuoi dati vengano raccolti nell'UE, modifica HOST nell' esempio in region1.google-analytics.com.

Nell'URL della richiesta devi fornire:

• api_secret: il valore dell'API SECRET generato nell'interfaccia utente di Google Analytics.

  Per creare un nuovo secret, vai ad Amministrazione > Raccolta e modifica dei dati > Stream di dati > scegli lo stream di tuo interesse > Secret API Measurement Protocol > Crea.

  Importante: api_secret è privato. Non esporlo nel codice lato client del tuo sito web o della tua app.

  • Rischio per la sicurezza: l'esposizione di api_secret consente a terze parti non autorizzate di inviare dati arbitrari o spam alla tua proprietà Google Analytics, il che può danneggiare i tuoi report.
  • Utilizzo corretto: Measurement Protocol è progettato principalmente per ambienti lato server o attendibili (come sistemi offline o comunicazione server-server).
  • Monitoraggio lato client: se devi inviare eventi direttamente da un browser web, utilizza il tag Google (gtag.js) o Google Tag Manager.

• firebase_app_id: l'ID app Firebase, che si trova nella console Firebase in Impostazioni progetto > Generale > Le tue app > ID app.

  firebase_app_id non è uguale a app_instance_id. firebase_app_id identifica la tua app, mentre app_instance_id identifica una singola installazione dell'app.

Devi fornire un corpo della richiesta nel formato del corpo POST JSON per Measurement Protocol. Ad esempio:

  {
   "app_instance_id": "APP_INSTANCE_ID",
   "events": [
      {
        "name": "login",
        "params": {
          "method": "Google",
          "session_id": "SESSION_ID",
          "engagement_time_msec": 100
        }
      }
   ]
  }

Mentre session_start è un nome evento riservato, la creazione di un nuovo session_id comporta la creazione di una nuova sessione senza dover inviare session_start. Scopri come vengono conteggiate le sessioni.

Prova

Nota: gli esempi seguenti utilizzano l'API fetch e sono destinati all'uso in ambienti lato server o attendibili (ad esempio Node.js o un server di backend). Non devono essere utilizzati nel codice lato client (browser) in quanto ciò esporrebbe il tuo api_secret.

Ecco un esempio che puoi utilizzare per inviare più eventi contemporaneamente. Questo esempio invia un evento tutorial_begin e un evento join_group al tuo 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 di Firebase.

Override del timestamp

Measurement Protocol utilizza il primo timestamp che trova nel seguente elenco per ogni evento e proprietà utente nella richiesta:

1. Il valore timestamp_micros dell'evento o della proprietà utente.
2. Il valore timestamp_micros della richiesta.
3. 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:

• tutorialBeginUnixEpochTimeInMicros per l'evento tutorial_begin
• customerTierUnixEpochTimeInMicros per la proprietà utente customer_tier
• requestUnixEpochTimeInMicros per l'evento join_group e la proprietà utente newsletter_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_behavior non è impostato o è impostato su RELAXED, Measurement Protocol accetta l'evento o la proprietà utente, ma sostituisce il timestamp con 72 ore fa.
• Se validation_behavior è impostato su ENFORCE_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:

Nota: per informazioni sui limiti delle funzionalità di 360, consulta Google Analytics 360.

• 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_id e session_number quando 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 dell'app inviati a Google Analytics non vengono utilizzati per popolare i segmenti di pubblico di ricerca in Google Ads per gli utenti dell'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 invece page_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.