Measurement Protocol-Ereignisse an Google Analytics senden

In dieser Anleitung wird beschrieben, wie Sie Measurement Protocol-Ereignisse für Web- und App-Streams an einen Google Analytics-Server senden, damit Sie sie in Ihren Google Analytics-Berichten sehen können.

Wählen Sie die Plattform aus, die in dieser Anleitung angezeigt werden soll:

Anfrage formatieren

Das Google Analytics Measurement Protocol unterstützt nur HTTP-POST-Anfragen.

Verwenden Sie das folgende Format, um ein Ereignis zu senden:

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

PAYLOAD_DATA

Sie müssen in der Anfrage-URL Folgendes angeben:

  • api_secret: Das API-Secret, das auf der Google Analytics-Benutzeroberfläche erstellt wurde.

    Wenn Sie ein neues Secret erstellen möchten, gehen Sie zu Verwaltung > Datenerhebung und ‑änderung > Datenstreams > Stream auswählen > Measurement Protocol API-Secrets > Erstellen.

  • measurement_id: Die Mess-ID für einen Stream, die Sie auf der Google Analytics-Benutzerfläche finden (Verwaltung > Datenstreams > Stream auswählen > Mess-ID).

    Die measurement_id ist nicht Ihre Stream-ID.

Für das Measurement Protocol müssen Sie einen Anfragetext im Format JSON POST body angeben. Beispiel:

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

session_start ist ein reservierter Ereignisname. Wenn Sie jedoch eine neue session_id erstellen, wird eine neue Sitzung erstellt, ohne dass Sie session_start senden müssen. Weitere Informationen zum Zählen der Sitzungen

Jetzt ausprobieren

Hier ist ein Beispiel, mit dem Sie mehrere Ereignisse gleichzeitig senden können. In diesem Beispiel werden ein tutorial_begin-Ereignis und ein join_group-Ereignis an Ihren Google Analytics-Server gesendet. Außerdem werden geografische Informationen über das Feld user_location und Geräteinformationen über das Feld device angegeben.

const measurementId = "MEASUREMENT_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: "CLIENT_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"
    }
  })
});

Zeitstempel überschreiben

Beim Measurement Protocol wird für jedes Ereignis und jede Nutzereigenschaft in der Anfrage der erste Zeitstempel verwendet, der in der folgenden Liste gefunden wird:

  1. Die timestamp_micros des Ereignisses oder der Nutzereigenschaft.
  2. Die timestamp_micros der Anfrage.
  3. Der Zeitpunkt, zu dem die Anfrage im Measurement Protocol eingeht.

Im folgenden Beispiel wird ein Zeitstempel auf Anfrageebene gesendet, der für alle Ereignisse und Nutzerattribute in der Anfrage gilt. Daher wird den Ereignissen tutorial_begin und join_group sowie der Nutzereigenschaft customer_tier im Measurement Protocol der Zeitstempel requestUnixEpochTimeInMicros zugewiesen.

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

Im folgenden Beispiel werden ein Zeitstempel auf Anfrageebene, ein Zeitstempel auf Ereignisebene und ein Zeitstempel auf Nutzereigenschaftsebene gesendet. Daher werden im Measurement Protocol die folgenden Zeitstempel zugewiesen:

  • tutorialBeginUnixEpochTimeInMicros für das tutorial_begin-Event
  • customerTierUnixEpochTimeInMicros für die Nutzereigenschaft customer_tier
  • requestUnixEpochTimeInMicros für das Ereignis join_group und die Nutzereigenschaft 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"
    }
  }
}

Validierungsverhalten für vergangene Ereignisse und Nutzereigenschaften

Ereignisse und Nutzereigenschaften können bis zu 72 Stunden rückdatiert werden. Wenn der Wert für timestamp_micros vor mehr als 72 Stunden liegt, wird das Ereignis oder die Nutzereigenschaft im Measurement Protocol so akzeptiert oder abgelehnt:

  • Wenn validation_behavior nicht oder auf RELAXED festgelegt ist, wird das Ereignis oder die Nutzereigenschaft vom Measurement Protocol akzeptiert, der zugehörige Zeitstempel wird jedoch auf vor 72 Stunden überschrieben.
  • Wenn validation_behavior auf ENFORCE_RECOMMENDATIONS festgelegt ist, wird das Ereignis oder die Nutzereigenschaft vom Measurement Protocol abgelehnt.

Beschränkungen

Für das Senden von Measurement Protocol-Ereignissen an Google Analytics gelten die folgenden Einschränkungen:

  • Anfragen dürfen maximal 25 Ereignisse enthalten.
  • Ereignisse dürfen maximal 25 Parameter haben.
  • Ereignisse dürfen maximal 25 Nutzereigenschaften haben.
  • Namen von Nutzereigenschaften dürfen maximal 24 Zeichen lang sein.
  • Werte von Nutzereigenschaften dürfen maximal 36 Zeichen umfassen.
  • Ereignisnamen dürfen maximal 40 Zeichen lang sein und nur alphanumerische Zeichen und Unterstriche enthalten. Außerdem müssen sie mit einem Buchstaben beginnen.
  • Parameternamen (einschließlich Artikelparameter) dürfen maximal 40 Zeichen lang sein und nur alphanumerische Zeichen und Unterstriche enthalten. Außerdem müssen sie mit einem Buchstaben beginnen.
  • Parameterwerte, einschließlich Artikelparameterwerte, dürfen für eine Standard-Google Analytics-Property maximal 100 Zeichen und für eine Google Analytics 360-Property maximal 500 Zeichen umfassen.
  • Für Artikelparameter können maximal 10 benutzerdefinierte Parameter festgelegt werden.
  • Der Beitragstext darf nicht größer als 130 KB sein.
  • Der Zeitstempel muss innerhalb der letzten 72 Stunden liegen. Weitere Informationen finden Sie unter Validierungsverhalten für vergangene Ereignisse.
  • Mit dem App Measurement Protocol an Google Analytics gesendete Ereignisse werden nicht für Suchzielgruppen in Google Ads für App-Nutzer verwendet.

Zusätzliche Anforderungen für die einzelnen Anwendungsfälle finden Sie unter Häufige Anwendungsfälle.