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:

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 HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

Nell'URL della richiesta devi fornire:

  • api_secret: il valore di 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 > API secret di Measurement Protocol > Crea.

  • 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. L'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 corpo POST JSON per il 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
        }
      }
   ]
  }

Anche se session_start è un nome 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",
  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. Vedi ID applicazione in File e oggetti di configurazione Firebase.

Override timestamp

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

  1. Il timestamp_micros dell'evento o della proprietà utente.
  2. Il 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 alle 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, il 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 passati e proprietà utente

Gli eventi e le proprietà utente possono essere retrodatati fino a 72 ore. Se il valore di timestamp_micros è precedente a 72 ore fa, Measurement Protocol accetta o rifiuta l'evento o la proprietà utente nel seguente modo:

  • Se validation_behavior non è impostato o è impostato su RELAXED, il Measurement Protocol accetta l'evento o la proprietà utente, ma sostituisce il timestamp con quello di 72 ore prima.
  • Se validation_behavior è impostato su ENFORCE_RECOMMENDATIONS, Measurement Protocol rifiuta l'evento o la proprietà utente.

Limitazioni

Le seguenti limitazioni si applicano all'invio di eventi Measurement Protocol a Google Analytics:

  • Le richieste possono avere un massimo di 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.
  • I parametri articolo possono avere un massimo di 10 parametri personalizzati.
  • Il corpo del post deve avere dimensioni inferiori a 130 kB.
  • Il timestamp deve rientrare nelle ultime 72 ore. Per maggiori dettagli, vedi Comportamento di convalida per gli eventi passati.
  • Gli eventi di Measurement Protocol per app inviati a Google Analytics non vengono utilizzati per creare segmenti di pubblico della rete di ricerca in Google Ads per gli utenti di app.

Per i requisiti aggiuntivi di ogni caso d'uso, consulta Casi d'uso comuni.