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-Anfragen POST gesendet werden.

Senden Sie Anfragen an den folgenden Endpunkt:

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

Wenn Ihre Daten in der EU erhoben werden sollen, 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 falsch formatiert ist oder die Daten falsch sind oder nicht von Google Analytics verarbeitet werden.

Nutzlast

Die Nutzlast besteht aus zwei Teilen:

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

Anfrageparameter

Parametername Beschreibung

api_secret

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

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

Privat für Ihre Organisation. Sollte regelmäßig aktualisiert werden, um übermäßigen SPAM zu vermeiden.

JSON-POST-Text

Schlüssel Typ Beschreibung

user_id

 string

Optional: Eine eindeutige Kennung für einen Nutzer. Weitere Informationen zu plattformübergreifenden Analysen mithilfe der User-ID 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 stattgefunden haben. Kann durch user_property oder Zeitstempel für Ereignisse überschrieben werden. Ereignisse können basierend auf der Zeitzone der Property bis zu 3 Kalendertage rückdatiert werden.

user_properties

 object Optional: Die Nutzereigenschaften für die Analyse.

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. Auf true gesetzt, um anzugeben, dass die Daten des Nutzers nicht für personalisierte Werbung verwendet werden sollen.

user_location

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

ip_override

 string Optional: Die 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.

events[]

 array Erforderlich. Ein Array mit event-Elementen. Pro Anfrage können bis zu 25 Ereignisse gesendet werden. Eine Liste aller gültigen Ereignisse finden Sie in der Ereignisreferenz.

events[].name

 string Erforderlich. Name des Ereignisses. Alle Optionen finden Sie unter Ereignisse.

events[].params

 object Optional: Parameter für das Ereignis. Unter Ereignisse finden Sie die empfohlenen Parameter für jedes Ereignis und unter Allgemeine Ereignisparameter.

Häufige Ereignisparameter

Das Measurement Protocol hat die folgenden gemeinsamen Ereignisparameter:

Schlüssel Typ Beschreibung

session_id

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

engagement_time_msec

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

timestamp_micros

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

Mit dem Attribut consent werden Einwilligungs-Typen 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 für das Senden von Nutzerdaten aus den Ereignissen und Nutzereigenschaften der Anfrage zu Werbezwecken an Google.

GRANTED oder DENIED.

ad_personalization

 string

Optional: Einwilligung für personalisierte Werbung für den Nutzer.

GRANTED oder DENIED.

Geografische Daten

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

So ist das Feld user_location aufgebaut. 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 Stadtnamen richtig einer Stadt-ID zuordnen kann.

region_id

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

country_id

 string Optional: Das Land im ISO 3166-1 alpha-2-Format. 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 in Google Analytics ignoriert.

Wenn Sie user_location oder ip_override nicht senden, leitet Google Analytics geografische Informationen aus dem Tagging von Ereignissen mit client_id

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

Geräteinformationen

Verwenden Sie das Feld device, um Geräteinformationen zu senden. Hier sehen Sie 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. Beispiel: 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"
}

Unabhängig davon, ob Sie angeben, wendet Google Analytics die Einstellungen für detaillierte Gerätedaten der Property auf die Anfrage an.

Benutzerdefinierte Parameter

Sie können benutzerdefinierte Parameter auf Nutzer-, Ereignis- und 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 werden Parameter empfohlen. 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
  • in_app_purchase
  • notification_dismiss
  • notification_foreground
  • notification_open
  • notification_receive
  • notification_send
  • os_update
  • session_start
  • user_engagement

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_