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, 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. Diese werden vom Google Analytics for Firebase SDK bereitgestellt.

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:

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 diese Anfragen firebase_app_id und app_instance_id verwenden.

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

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.

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

Sie müssen in den URL-Abfrageparametern der Anfrage Folgendes angeben (Informationen zum Suchen oder Erstellen dieser Werte finden Sie unter Vorbereitung):

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

Sie müssen einen Anfrage-Text 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 Anfrage-Text angeben, um eine eindeutige Installation Ihrer mobilen App zu identifizieren. Diese ID unterscheidet sich von der firebase_app_id, 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 Ereignis name. Wenn Sie eine neue session_id erstellen, wird eine neue Sitzung erstellt, ohne dass Sie session_start senden müssen. Informationen zur Zählung 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 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 älter als 72 Stunden ist, 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 über das Measurement Protocol gesendet werden und mit Ereignissen verknüpft oder zusammen mit Ereignissen 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:

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

  • 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 Google Analytics-Standard-Property maximal 100 Zeichen und für eine 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 dürfen maximal 10 benutzerdefinierte Parameter haben.

  • Der Post-Text darf nicht größer als 130 KB sein.

  • App Measurement Protocol-Ereignisse, die an Google Analytics gesendet werden, füllen in Google Ads keine Suchzielgruppen 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:

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