Measurement Protocol-Referenz

Auf dieser Seite werden der Transportmechanismus und die Datenparameter für das Measurement Protocol beschrieben.

Transport

Alle Daten müssen sicher über HTTPS-POST-Anfragen gesendet werden.

Senden Sie Anfragen an den folgenden Endpunkt:

https://www.google-analytics.com/mp/collect

Wenn Sie möchten, dass Ihre Daten in der EU erhoben werden, verwenden Sie stattdessen den folgenden Endpunkt:

https://region1.google-analytics.com/mp/collect

Hier ein Beispiel für eine POST-Anfrage:

POST /mp/collect HTTP/1.1
HOST: www.google-analytics.com
Content-Type: application/json
PAYLOAD_DATA

Ersetzen Sie PAYLOAD_DATA durch die Nutzlast der Anfrage.

Das Measurement Protocol gibt den Statuscode 2xx zurück, wenn die HTTP-Anfrage empfangen wird. Das Measurement Protocol gibt keinen Fehlercode zurück, wenn die Nutzlast fehlerhaft ist oder die Daten falsch sind oder nicht von Google Analytics verarbeitet werden.

Nutzlast

Die Nutzlast besteht aus zwei Teilen:

  1. Suchparameter
  2. Ein JSON-POST-Text.

Suchparameter

Parametername Beschreibung

api_secret

 Erforderlich. das API-Secret aus der Google Analytics-Benutzeroberfläche.

Sie finden ihn unter Verwaltung > Datenstreams > Stream auswählen > Measurement Protocol > Erstellen.

Nur für Ihre Organisation sichtbar. Sollte regelmäßig aktualisiert werden, um übermäßigen Spam zu vermeiden.

firebase_app_id

 Erforderlich. Firebase-App-ID. Die Kennung für eine Firebase-App.

Sie finden sie in der Firebase Console unter Projekteinstellungen > Allgemein > Meine Apps > App-ID.

JSON-POST-Text

Die Größe des JSON-POST-Bodys muss kleiner als 130 kB sein.

Schlüssel Typ Beschreibung

app_instance_id

 string Erforderlich. Eindeutige Kennung für eine bestimmte Installation einer Firebase-App.

Nicht dasselbe wie ein Web-client_id.

Muss mit dem Firebase SDK abgerufen werden:

user_id

 string

Optional: Eine eindeutige Kennung für einen Nutzer. Weitere Informationen zu dieser Kennung finden Sie unter User-ID für plattformübergreifende Analysen. Darf nur UTF-8-Zeichen enthalten.

timestamp_micros

 number

Optional: Ein Unix-Zeitstempel in Mikrosekunden, nicht in Millisekunden. Stellt die Uhrzeit des Ereignisses dar. Sollte nur festgelegt werden, um Ereignisse aufzuzeichnen, die in der Vergangenheit aufgetreten sind. Kann durch user_property oder Ereigniszeitstempel überschrieben werden. Ereignisse können bis zu 72 Stunden zurückdatiert werden.

user_properties

 object Optional: Die Nutzereigenschaften für die Messung. Pro Anfrage können bis zu 25 Nutzereigenschaften gesendet werden. Namen von Nutzereigenschaften dürfen maximal 24 Zeichen lang sein und Werte von Nutzereigenschaften maximal 36 Zeichen umfassen.

user_data

 object Optional: Von Nutzern bereitgestellte Daten
object Optional: Einwilligungseinstellungen für die Anfrage. Weitere Informationen finden Sie im Abschnitt zur Einwilligung.

non_personalized_ads

 boolean Optional. Legen Sie den Wert auf true fest, um anzugeben, dass die Daten des Nutzers nicht für personalisierte Anzeigen verwendet werden sollen.

user_location

 object Optional: Legt die geografischen Informationen für die Anfrage in einem strukturierten Format fest.

ip_override

 string Optional: IP-Adresse, die Google Analytics verwendet, um geografische Informationen für die Anfrage abzuleiten.

device

 object Optional. Legt die Geräteinformationen für die Anfrage in einem strukturierten Format fest.

validation_behavior

 string

Optional. Legt das Validierungsverhalten für die Anfrage fest.

RELAXED oder ENFORCE_RECOMMENDATIONS. Wenn keine Angabe gemacht wird, ist der Standardwert RELAXED.

events[]

 array Erforderlich. Ein Array von event-Elementen. Pro Anfrage können bis zu 25 Ereignisse gesendet werden. In der Referenz zu Ereignissen finden Sie empfohlene Ereignisse.

events[].name

 string Erforderlich. Name des Ereignisses. Ereignisnamen dürfen maximal 40 Zeichen lang sein. Eine Liste der empfohlenen Ereignisse finden Sie unter Ereignisse.

events[].params

 object Optional: Parameter für das Ereignis. Pro Ereignis können bis zu 25 Parameter gesendet werden. Unter Ereignisse finden Sie die empfohlenen Parameter für jedes Ereignis und unter Allgemeine Ereignisparameter weitere Informationen.

Parameternamen dürfen maximal 40 Zeichen lang sein. Parameterwerte dürfen bei einer standardmäßigen Google Analytics-Property maximal 100 Zeichen und bei einer Google Analytics 360-Property maximal 500 Zeichen umfassen.

Häufige Ereignisparameter

Das Measurement Protocol hat die folgenden allgemeinen Ereignisparameter:

Schlüssel Typ Beschreibung

session_id

 number Eine positive Zahl, die die Nutzersitzung identifiziert. Erforderlich für mehrere häufige Anwendungsfälle. Muss dem regulären Ausdruck ^\d+$ entsprechen.

Muss mit dem Firebase SDK abgerufen werden:

engagement_time_msec

 number Die Dauer des Nutzer-Engagements für das Ereignis in Millisekunden. Verwenden Sie einen Wert, der die Dauer der Nutzerinteraktion seit dem vorherigen Ereignis widerspiegelt.

timestamp_micros

 number Die Unix-Epochenzeit (in Mikrosekunden) für das Ereignis. Mit diesem Parameter können Sie den Zeitstempel des Ereignisses überschreiben.

Mit dem Attribut consent werden Einwilligungstypen und -status konfiguriert. Wenn Sie consent nicht angeben, verwendet Google Analytics die Einwilligungseinstellungen aus entsprechenden Onlineinteraktionen für den Client oder die App-Instanz.

Schlüssel Typ Beschreibung

ad_user_data

 string

Optional: Einwilligung zum Senden von Nutzerdaten aus den Ereignissen und Nutzereigenschaften der Anfrage zu Werbezwecken an Google.

GRANTED oder DENIED.

ad_personalization

 string

Optional: Einwilligung des Nutzers in personalisierte Anzeigen.

GRANTED oder DENIED.

Geografische Daten

Die Attribute user_location und ip_override enthalten geografische Informationen. user_location hat Vorrang vor ip_override.

Hier ist die Struktur des Felds user_location. Geben Sie so viele Attribute wie möglich an. Wir empfehlen mindestens country_id und region_id.

Schlüssel Typ Beschreibung

city

 string Optional: Der Name der Stadt. Wenn sich die Stadt in den USA befindet, legen Sie auch country_id und region_id fest, damit Google Analytics den Städtenamen einer Stadt-ID zuordnen kann.

region_id

 string Optional: Das Land und die Untergruppe gemäß ISO 3166. Beispiel: US-CA, US-AR, CA-BC, GB-LND, CN-HK.

country_id

 string Optional: Das Land im Format ISO 3166-1 alpha-2. Beispiele: US, AU, ES, FR.

subcontinent_id

 string Optional: Der Subkontinent im UN M49-Format. Beispiele: 011, 021, 030, 039.

continent_id

 string Optional: Der Kontinent im UN M49-Format. Beispiele: 002, 019, 142, 150.

Hier ein Beispiel für user_location:

"user_location": {
  "city": "Mountain View",
  "region_id": "US-CA",
  "country_id": "US",
  "subcontinent_id": "021",
  "continent_id": "019"
}

ip_override ist eine Alternative zu user_location. Wenn Sie stattdessen ip_override senden, leitet Google Analytics geografische Informationen aus der IP-Adresse ab. Wenn Sie user_location senden, wird ip_override von Google Analytics ignoriert.

Wenn Sie user_location oder ip_override nicht senden, leitet Google Analytics geografische Informationen aus Tagging-Ereignissen mitab. app_instance_id.

Google Analytics wendet die Einstellungen für detaillierte Standortdaten der Property auf die Anfrage an, unabhängig von den gesendeten geografischen Informationen.

Geräteinformationen

Verwenden Sie das Feld device, um Geräteinformationen zu senden. Hier ist die Struktur des Felds device. Geben Sie so viele Attribute wie möglich an. Wir empfehlen mindestens category.

Schlüssel Typ Beschreibung

category

 string Optional. Die Kategorie des Geräts. Beispiele: desktop, tablet, mobile, smart TV.

language

 string Optional. Die Sprache im ISO 639-1-Format. Beispiel: en, en-US.

screen_resolution

 string Optional. Die Auflösung des Geräts, formatiert als WIDTHxHEIGHT. Beispiel: 1280x2856, 1080x2340.

operating_system

 string Optional. Das Betriebssystem oder die Plattform. Beispiel: MacOS.

operating_system_version

 string Optional. Die Version des Betriebssystems oder der Plattform. Beispiel: 13.5.

model

 string Optional. Das Modell des Geräts. Beispiel: Pixel 9 Pro, Samsung Galaxy S24.

brand

 string Optional. Die Marke des Geräts. Beispiel: Google, Samsung.

browser

 string Optional. Die Marke oder der Typ des Browsers. Beispiel: Chrome, Firefox.

browser_version

 string Optional. Die Version des Browsers. Beispiel: 136.0.7103.60, 5.0.

Das folgende Snippet zeigt ein Beispiel für device-Einstellungen:

"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"
}
Wenn in einer Anfrage die device nicht angegeben ist, leitet Google Analytics Geräteinformationen aus Tagging-Ereignissen mithilfe von app_instance_id ab.

Unabhängig davon, ob Siedevice,angeben, werden in Google Analytics die Einstellungen für detaillierte Gerätedaten der Property auf die Anfrage angewendet.

Validierungsverhalten

Das Attribut validation_behavior steuert, wie das Measurement Protocol den Inhalt der Anfrage validiert.

  • Bei der RELAXED-Validierung werden nur fehlerhafte Anfragen abgelehnt. Ereignisse und Parameter mit ungültigen Feldnamen oder Daten, die nicht dem richtigen Typ entsprechen, werden möglicherweise weiterhin akzeptiert. Parameter, die die Limits überschreiten, werden jedoch ignoriert. Das Measurement Protocol verwendet standardmäßig die RELAXED-Validierung.
  • Bei der ENFORCE_RECOMMENDATIONS-Validierung werden Ereignis- und Artikelparameter abgelehnt, die nicht den richtigen Typ haben oder Parameter enthalten, die die Limits überschreiten. Außerdem werden in ENFORCE_RECOMMENDATIONS alle Ereignisse oder Nutzereigenschaften mit einem Zeitstempel abgelehnt, der nicht innerhalb der letzten 72 Stunden liegt.

Wir empfehlen folgende Vorgehensweise:

  • Verwenden Sie ENFORCE_RECOMMENDATIONS, wenn Sie Ereignisse validieren, um möglichst viel Feedback zu potenziellen Problemen mit Ihren Anfragen zu erhalten.

    Sie können Anfragen auch mit dem Event Builder validieren, da er bei der Validierung von Anfragen ENFORCE_RECOMMENDATIONS angibt.

  • Geben Sie validation_behavior nicht an, wenn Sie Ereignisse senden, um die vom Measurement Protocol abgelehnten Daten zu minimieren.

    Wenn Sie beim Senden einer bestimmten Anfrage die strikte Validierung gegenüber der Datenerhebung priorisieren möchten, fügen Sie das Feld validation_behavior hinzu und setzen Sie es auf ENFORCE_RECOMMENDATIONS.

Benutzerdefinierte Parameter

Sie können benutzerdefinierte Parameter auf Nutzerebene, ereignisbezogen und auf Artikelebene in eine Measurement Protocol-Nutzlast einfügen.

  • Benutzerdefinierte Parameter auf Nutzerebene können in user_properties enthalten sein.
  • Benutzerdefinierte Parameter auf Ereignisebene können in events[].params enthalten sein.
  • Benutzerdefinierte Parameter auf Artikelebene können in items enthalten sein.

Für einige Ereignisse gibt es empfohlene Parameter. Unter Ereignisse finden Sie die empfohlenen Parameter für alle unterstützten Ereignisse.

Reservierte Namen

Einige Namen von Ereignissen, Parametern und Nutzereigenschaften sind reserviert und können nicht verwendet werden:

Reservierte Ereignisnamen

Die folgenden Ereignisnamen sind reserviert und können nicht verwendet werden:

  • ad_activeview
  • ad_click
  • ad_exposure
  • ad_query
  • ad_reward
  • adunit_exposure
  • app_clear_data
  • app_exception
  • app_install
  • app_remove
  • app_store_refund
  • app_update
  • app_upgrade
  • dynamic_link_app_open
  • dynamic_link_app_update
  • dynamic_link_first_open
  • error
  • firebase_campaign
  • firebase_in_app_message_action
  • firebase_in_app_message_dismiss
  • firebase_in_app_message_impression
  • first_open
  • first_visit
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

Außerdem sind die Ereignisse ad_impression, in_app_purchase und screen_view nur für App-Streams zulässig.

Reservierte Parameternamen

Die folgenden Parameternamen sind reserviert und können nicht verwendet werden:

  • firebase_conversion

Parameternamen dürfen nicht mit folgenden Zeichen oder Präfixen beginnen:

  • _ (underscore)
  • firebase_
  • ga_
  • google_
  • gtag.

Reservierte Namen von Nutzereigenschaften

Die folgenden Namen von Nutzereigenschaften sind reserviert und können nicht verwendet werden:

  • first_open_time
  • first_visit_time
  • last_deep_link_referrer
  • user_id
  • first_open_after_install

Außerdem dürfen Namen von Nutzereigenschaften nicht mit folgenden Zeichen oder Präfixen beginnen:

  • _ (underscore)
  • firebase_
  • ga_
  • google_