Measurement Protocol-Ereignisse an Google Analytics senden

In diesem Leitfaden wird beschrieben, wie Sie Ereignisse aus Web- und App-Streams des Google Analytics Measurement Protocol 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 Kennungen und Parameter hängen davon ab, ob Sie Ereignisse an einen Web-Stream oder einen App-Stream senden.

  • Bei Webstreams (normalerweise 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 sollte mit der ID übereinstimmen, die vom Google Analytics-Tag auf Ihrer Website generiert wird.
  • 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 diesem Leitfaden 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 die Geräte-ID client_id app_instance_id

Wählen Sie die Plattform aus, die Sie in diesem Leitfaden sehen möchten:

Auf diesem Tab finden Sie eine Anleitung zum Senden von Ereignissen von Ihrem Server, die mit Nutzeraktivitäten in einem App-Stream über das Google Analytics for Firebase SDK korrelieren. Beachten Sie, dass für diese Anfragen firebase_app_id und app_instance_id verwendet werden.

Vorbereitung

Wenn Sie Ereignisse über das Measurement Protocol senden möchten, benötigen Sie bestimmte Kennungen aus Ihrer Google Analytics-Property oder Ihrem Firebase-Projekt.

API-Secret

Die api_secret wird zur Authentifizierung Ihrer Anfragen verwendet. 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 den 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.

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 Console.
  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 Bereich Meine Apps.
  4. Wählen Sie die gewünschte iOS- oder Android-App aus.
  5. Kopieren Sie den Wert für die 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

Sie müssen in den Suchparametern der Anfrage-URL Folgendes angeben (Details zum Suchen 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-Textformat für das Measurement Protocol angeben. Beispiel:

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

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

session_start ist ein reservierter Ereignisname. 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

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 einbezogen.

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 -objekte.

Zeitstempel überschreiben

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

  1. Der timestamp_micros des Ereignisses oder der Nutzereigenschaft.
  2. Die 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 Ereignisse und Nutzerattribute 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 mehr als 72 Stunden zurückliegt, wird das Ereignis oder die Nutzereigenschaft vom Measurement Protocol so akzeptiert oder abgelehnt:

  • 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 festgelegt ist, wird das Ereignis oder die Nutzereigenschaft vom Measurement Protocol abgelehnt.

Ereignisse, die über das Measurement Protocol gesendet werden und mit Ereignissen zusammengeführt oder verarbeitet werden sollen, die über das Google Analytics for Firebase SDK oder gtag.js erfasst wurden, sollten 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

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

  • Sie können pro Property maximal 100 Millionen Anfragen pro Stunde senden, die keine Conversions betreffen. Eine Anfrage ist eine Nicht-Conversion-Anfrage, wenn keines der Ereignisse in der Anfrage ein Schlüsselereignis ist, für das es eine Conversion in Google Ads gibt. Wenn Sie dieses Limit überschreiten, werden alle Nicht-Conversion-Anfragen für die Property für den Rest der Stunde vom Measurement Protocol ignoriert.

  • Anfragen können 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 bei einer Google Analytics-Standard-Property maximal 100 Zeichen und bei einer Google Analytics 360-Property maximal 500 Zeichen enthalten.

    Dieses Limit 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 können maximal 10 benutzerdefinierte Parameter haben.

  • Der Text des Beitrags darf maximal 130 KB groß sein.

  • App-Measurement Protocol-Ereignisse, die an Google Analytics gesendet werden, werden nicht in Zielgruppen für Suchkampagnen in Google Ads für App-Nutzer übernommen.

  • Einige Namen von Ereignissen, Parametern und Nutzereigenschaften sind reserviert und können nicht verwendet werden. Weitere Informationen finden Sie unter Reservierte Namen.

Reservierte Namen

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

Die folgenden Ereignisnamen sind häufige Ursachen für Verwirrung:

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