Measurement Protocol-Ereignisse an Google Analytics senden

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

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

Firebase gtag.js

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

Tipp: Wenn Ihre Daten in der EU erfasst werden sollen, ändern Sie den HOST im Beispiel in region1.google-analytics.com.

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

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

  Sie können unter Verwaltung > Datenerhebung und ‑änderung > Datenstreams > Stream auswählen > Measurement Protocol API-Secrets > Erstellen ein neues Secret erstellen.

• firebase_app_id: Die Firebase-App-ID finden Sie in der Firebase Console unter Projekteinstellungen > Allgemein > Ihre Apps > App-ID.

  Die firebase_app_id ist nicht mit der app_instance_id identisch. Die firebase_app_id identifiziert Ihre App, während app_instance_id eine einzelne Installation der App identifiziert.

Sie müssen einen Anfragetext im JSON-POST-Format für das Measurement Protocol angeben. Hier ein Beispiel:

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

session_start ist ein reservierter Ereignis name. Sie können jedoch eine neue session_id generieren, um eine neue Sitzung zu erstellen, ohne session_start senden zu müssen. Informationen zum Zählen von Sitzungen.

Jetzt ausprobieren

Hier 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 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"
    }
  })
});

Das Format von firebase_app_id ist plattformspezifisch. Weitere Informationen finden Sie unter Anwendungs-ID unter Firebase-Konfigurationsdateien und ‑objekten.

Zeitstempel überschreiben

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

1. Der timestamp_micros des Ereignisses oder der Nutzereigenschaft.
2. Der timestamp_micros der Anfrage.
3. Der Zeitpunkt, zu dem das Measurement Protocol die Anfrage empfängt.

Im folgenden Beispiel wird ein Zeitstempel auf Anfrageebene gesendet, der für alle der Ereignisse und Nutzer Eigenschaften in der Anfrage gilt. Daher weist das Measurement Protocol den Ereignissen tutorial_begin und join_group sowie der Nutzereigenschaft customer_tier einen Zeitstempel von requestUnixEpochTimeInMicros zu.

{
  "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 weist das Measurement Protocol die folgenden Zeitstempel zu:

• tutorialBeginUnixEpochTimeInMicros für das Ereignis tutorial_begin
• 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 zurückdatiert werden. Wenn der Wert timestamp_micros vor mehr als 72 Stunden liegt, akzeptiert oder lehnt das Measurement Protocol das Ereignis oder die Nutzereigenschaft wie folgt ab:

• Wenn validation_behavior nicht festgelegt oder auf RELAXED gesetzt ist, akzeptiert das Measurement Protocol das Ereignis oder die Nutzereigenschaft, überschreibt aber den Zeitstempel mit dem Zeitpunkt vor 72 Stunden.
• Wenn validation_behavior auf ENFORCE_RECOMMENDATIONS gesetzt ist, lehnt das Measurement Protocol das Ereignis oder die Nutzereigenschaft ab.

Ereignisse, die mit dem Measurement Protocol gesendet werden und mit Ereignissen verknüpft oder zusammen mit Ereignissen verarbeitet werden sollen, die mit dem Google Analytics for Firebase SDK oder gtag.js erfasst wurden, müssen innerhalb von 48 Stunden nach dem ursprünglichen clientseitigen Ereigniszeitstempel bei Google Analytics eingehen. Ereignisse, die später eingehen, werden möglicherweise nicht wie erwartet verarbeitet, insbesondere für Zwecke wie die Conversion-Attribution.

Beschränkungen

Die folgenden Beschränkungen gelten für das Senden von Measurement Protocol-Ereignissen an Google Analytics:

Hinweis: Informationen zu den Beschränkungen von 360-Funktionen finden Sie unter Google Analytics 360.

• 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 maximal 100 Zeichen für eine Google Analytics-Standard-Property und maximal 500 Zeichen für eine Google Analytics 360-Property enthalten.

  Diese Beschränkung gilt nicht für die Parameter session_id und session_number, wenn ihre Werte von den entsprechenden integrierten Variablen Analytics-Sitzungs-ID und Analytics-Sitzungsnummer in Google Tag Manager bereitgestellt werden.

• Artikelparameter dürfen maximal 10 benutzerdefinierte Parameter haben.

• Der Post-Text darf maximal 130 KB groß sein.

• App Measurement Protocol-Ereignisse, die an Google Analytics gesendet werden, füllen keine Suchzielgruppen in Google Ads für App-Nutzer.

• Einige Namen für Ereignisse, Parameter und Nutzereigenschaften sind reserviert und können nicht verwendet werden. Weitere Informationen finden Sie unter Reservierte Namen für Details.

Reservierte Namen

Das Measurement Protocol hat mehrere reservierte Namen, die nicht für Ereignisse, Parameter oder Nutzereigenschaften verwendet werden können.

Die folgenden Ereignisnamen führen häufig zu Verwirrung:

• screen_view: Dieses Ereignis ist nur für App Streams zulässig. Verwenden Sie für Web-Streams stattdessen page_view.
• ad_impression: Dieses Ereignis ist nur für App Streams zulässig.
• in_app_purchase: Dieses Ereignis ist nur für App Streams zulässig. Verwenden Sie für Web-Streams stattdessen das purchase Ereignis.

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