Measurement Protocol-Ereignisse an Google Analytics senden

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

Die für Measurement Protocol-Anfragen erforderlichen IDs und Parameter hängen davon ab, ob Sie Ereignisse an einen Webstream oder einen App-Stream senden.

• Bei Webstreams (in der Regel mit gtag.js oder Google Tag Manager instrumentiert) verwenden Sie die measurement_id in der Anfrage-URL und die client_id im JSON-Text, um die Nutzerinstanz zu identifizieren. Die client_id muss mit der ID übereinstimmen, die vom Google Analytics-Tag auf Ihrer Website generiert wurde.
• Bei App-Streams (mit dem Firebase SDK instrumentiert) verwenden Sie die firebase_app_id in der Anfrage-URL und die app_instance_id im JSON-Text, die vom Google Analytics for Firebase SDK bereitgestellt werden.

In dieser Anleitung finden Sie Beispiele für beide Szenarien.

Wichtige Anfragekomponenten nach Streamtyp

Komponente	Web stream (gtag.js/GTM)	App-Stream (Firebase)
URL-Parameter für Datenstream	measurement_id	firebase_app_id
URL-Parameter für API-Secret	Erforderlich	Erforderlich
JSON-Textfeld für Geräte-ID	client_id	app_instance_id

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

Firebase gtag.js

Auf diesem Tab finden Sie eine Anleitung zum Senden von Ereignissen von Ihrem Server, die mit der Nutzeraktivität in einem App-Stream korrelieren. Dabei wird das Google Analytics for Firebase SDK verwendet. Beachten Sie, dass in diesen Anfragen firebase_app_id und app_instance_id verwendet werden.

Vorbereitung

Wenn Sie Ereignisse mit dem Measurement Protocol senden möchten, benötigen Sie bestimmte IDs aus Ihrer Google Analytics-Property oder Ihrem Firebase-Projekt.

API-Secret

Das api_secret wird verwendet, um Ihre Anfragen zu authentifizieren. Es ist wichtig, dieses Secret vertraulich zu behandeln.

So erstellen Sie ein neues Secret:

1. Rufen Sie Google Analytics auf und gehen Sie zu Ihrem Konto und Ihrer Property.
2. Klicken Sie links unten auf Verwaltung.
3. Klicken Sie unter Datenerhebung und ‑änderung auf Datenstreams.
4. Wählen Sie Ihren Web- oder App-Datenstream aus.
5. Klicken Sie auf Measurement Protocol – API-Secrets.
6. Klicken Sie auf Erstellen.
7. Geben Sie einen Alias für das Secret ein und klicken Sie auf Erstellen.

8. Kopieren Sie den Secret-Wert.

   Wichtig:Das api_secret ist privat. Geben Sie es nicht im clientseitigen Code Ihrer Website oder App an.

   • Sicherheitsrisiko:Wenn Sie das api_secret angeben, können nicht autorisierte Parteien beliebige oder Spam-Daten an Ihre Google Analytics-Property senden, was Ihre Berichte verfälschen kann.
   • Korrekte Verwendung:Das Measurement Protocol ist in erster Linie für serverseitige oder vertrauenswürdige Umgebungen konzipiert (z. B. Offlinesysteme oder Server-zu-Server-Kommunikation).
   • Clientseitiges Tracking: Wenn Sie Ereignisse direkt von einem Web browser senden müssen, verwenden Sie das Google-Tag (gtag.js) oder Google Tag Manager.
   • Chrome-Erweiterungen:Bei Manifest V3-Chrome-Erweiterungen können Sie keinen Remote-Code wie gtag.js laden. In diesem Fall ist das Measurement Protocol die empfohlene Methode. Weitere Informationen finden Sie unter Google Analytics in Chrome-Erweiterungen verwenden.

Firebase-App-ID

Die firebase_app_id identifiziert Ihre Firebase-App. Sie ist nicht mit der app_instance_id identisch.

So finden Sie Ihre Firebase-App-ID:

1. Öffnen Sie Ihr Projekt in der Firebase-Konsole.
2. Klicken Sie neben Projektübersicht auf das Zahnradsymbol für die Einstellungen und wählen Sie Projekteinstellungen aus.
3. Gehen Sie auf dem Tab Allgemein zum Abschnitt Meine Apps.
4. Wählen Sie die gewünschte iOS- oder Android-App aus.
5. Kopieren Sie den Wert App-ID.

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?firebase_app_id=<var>FIREBASE_APP_ID</var>&api_secret=<var>API_SECRET</var> HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json

PAYLOAD_DATA

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

Sie müssen in den URL-Suchparametern der Anfrage Folgendes angeben (weitere Informationen zum Ermitteln oder Erstellen dieser Werte finden Sie unter Voraussetzungen):

• api_secret: Das API-Secret zur Authentifizierung der Anfrage.
• firebase_app_id: Die Firebase-App-ID Ihrer Anwendung.

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
        }
      }
   ]
  }

Sie müssen app_instance_id im Anfragetext angeben, um eine eindeutige Installation Ihrer mobilen App zu identifizieren. Beachten Sie, dass sich diese ID von der firebase_app_id unterscheidet, die die App selbst identifiziert. Weitere Informationen zur app_instance_id und zum Abrufen dieser ID mit dem Firebase SDK finden Sie in der Referenzdokumentation zu app_instance_id.

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

Hinweis: In den folgenden Beispielen wird die fetch API verwendet. Sie sind für die Verwendung in serverseitigen oder vertrauenswürdigen Umgebungen vorgesehen (z. B. Node.js oder ein Backend-Server). Sie sollten nicht im clientseitigen (Browser-)Code verwendet werden, da dadurch Ihr api_secret offengelegt würde.

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 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 den Zeitstempel 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 früher 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 auf 72 Stunden vor dem aktuellen Zeitpunkt.
• 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 verarbeitet werden sollen, die vom Google Analytics for Firebase SDK oder gtag.js erhoben 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 von Ereignissen, Parametern 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 Webstreams 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 Webstreams stattdessen das purchase Ereignis.

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