Measurement Protocol-Ereignisse an Google Analytics senden

In dieser Anleitung wird beschrieben, wie Sie Google Analytics Measurement Protocol-Web- und App-Stream-Ereignisse 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 Web-Stream oder einen App-Stream senden.

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

In diesem Leitfaden finden Sie Beispiele für beide Szenarien.

Schlüsselanfragekomponenten 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-Feld für Geräte-ID client_id app_instance_id

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

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

Vorbereitung

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

API-Secret

Der api_secret wird zur Authentifizierung Ihrer Anfragen verwendet. Es ist wichtig, dass Sie ihn vertraulich behandeln.

So erstellen Sie ein neues Secret:

  1. Rufen Sie Google Analytics auf und wählen Sie Ihr Konto und Ihre Property aus.
  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.

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. Rufen Sie auf dem Tab Allgemein den Bereich Meine Apps auf.
  4. Wählen Sie die gewünschte iOS- oder Android-App aus.
  5. Kopieren Sie den Wert unter 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 Anfrage-URL-Suchparametern Folgendes angeben (weitere Informationen 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.

Für das Measurement Protocol müssen Sie einen Anfragetext im Format JSON POST body 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 app_instance_id im Anfragebody angeben, um eine eindeutige Installation Ihrer mobilen App zu identifizieren. Das ist nicht dasselbe wie firebase_app_id, mit dem die App selbst identifiziert wird. Weitere Informationen zur app_instance_id und dazu, wie Sie sie mit dem Firebase SDK abrufen, finden Sie in der Referenzdokumentation zur App-Instanz-ID.

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

Jetzt ausprobieren

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 sind geografische Informationen über das Feld user_location und Geräteinformationen über das Feld device enthalten.

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 im Abschnitt Firebase-Konfigurationsdateien und -Objekte.

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 Nutzereigenschaften 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-Ereignis
  • 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 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.

Ereignisse, die über das Measurement Protocol gesendet werden und mit Ereignissen zusammengeführt oder in Verbindung mit Ereignissen verarbeitet werden sollen, die über das Google Analytics for Firebase SDK oder gtag.js erfasst werden, sollten innerhalb von 48 Stunden nach dem ursprünglichen clientseitigen Ereignis-Zeitstempel in 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 ohne Conversion pro Stunde senden. 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 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.

    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 Beitragstext darf maximal 130 KB groß sein.

  • Mit dem App Measurement Protocol an Google Analytics gesendete Ereignisse werden nicht für Suchzielgruppen in Google Ads für App-Nutzer verwendet.

  • 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:

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