Inviare eventi Measurement Protocol a Google Analytics

Questa guida spiega come inviare eventi di Google Analytics Measurement Protocol per gli stream web e di app a un server di Google Analytics, in modo da poter visualizzare gli eventi di 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 dell'API SECRET generato nell'interfaccia utente di Google Analytics.

    Per creare un nuovo secret, vai ad Amministrazione > Stream di dati > scegli lo stream di tuo interesse > Measurement Protocol > Crea.

  • measurement_id: l'ID misurazione associato a uno stream, che si trova nell'interfaccia utente di Google Analytics in Amministrazione > Stream di dati > scegli lo stream di tuo interesse > ID misurazione.

    measurement_id non è il tuo ID stream.

Per il riferimento completo, consulta i parametri di query.

Nel corpo della richiesta devi fornire quanto segue:

  • client_id: un identificatore univoco per un client. È diverso da un app_instance_id Firebase. Utilizza gtag.js('get').

  • timestamp_micros: facoltativo. Il timestamp dell'epoca di Unix, in microsecondi, per gli eventi e le proprietà utente nella richiesta. Se non specificato, il valore predefinito è il momento della richiesta.

  • events: un array di elementi evento. Puoi includere più eventi in un'unica richiesta.

    Affinché l'attività utente venga visualizzata in report come In tempo reale, engagement_time_msec e session_id devono essere forniti come parte del params per un event. Il parametro engagement_time_msec deve riflettere la durata del coinvolgimento dell'evento in millisecondi.

    Ecco un esempio:

  {
   "client_id": "123456.7654321",
   "events": [
     {
        "name": "campaign_details",
        "params": {
          "campaign_id": "google_1234",
          "campaign": "Summer_fun",
          "source": "google",
          "medium": "cpc",
          "term": "summer+travel",
          "content": "logolink",
          "session_id": "123",
          "engagement_time_msec": 100
        }
     }
   ]
  }

Anche se 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

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 informazioni sul dispositivo utilizzando il campo device.

const measurement_id = `G-XXXXXXXXXX`;
const api_secret = `<secret_value>`;

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: "XXXXXXXXXX.YYYYYYYYYY",
    events: [
      {
        name: "tutorial_begin",
        params: {
          "session_id": "123",
          "engagement_time_msec": 100
        }
      },
      {
        name: "join_group",
        params: {
          "group_id": "G_12345",
          "session_id": "123",
          "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"
    }
  })
});

Timestamp dell'override

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

  1. Il timestamp_micros dell'evento.
  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 nella richiesta. Di conseguenza, Measurement Protocol assegna sia agli eventi tutorial_begin sia a quelli join_group un timestamp di requestUnixEpochTimeInMicros.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin"
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ]
}

L'esempio seguente invia sia un timestamp a livello di richiesta sia un timestamp a livello di evento. Di conseguenza, Measurement Protocol assegna all'evento tutorial_begin un timestamp di tutorialBeginUnixEpochTimeInMicros e all'evento join_group un timestamp di requestUnixEpochTimeInMicros.

{
  "timestamp_micros": requestUnixEpochTimeInMicros,
  "events": [
    {
      "name": "tutorial_begin",
      "timestamp_micros": tutorialBeginUnixEpochTimeInMicros
    },
    {
      "name": "join_group",
      "params": {
        "group_id": "G_12345",
      }
    }
  ]
}

Limitazioni

I seguenti limiti 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 elemento possono avere un massimo di 10 parametri personalizzati.
  • Il corpo del post deve avere dimensioni inferiori a 130 kB.
  • Gli eventi Measurement Protocol per le app inviati a Google Analytics non compilano i 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 i casi d'uso comuni.