Measurement Protocol-Referenz

Übersicht

Das Senden von Daten über das Measurement Protocol an Google Analytics besteht aus zwei Teilen:

  1. Transportschicht: Wo und wie Daten gesendet werden
  2. Nutzlast: Die von Ihnen gesendeten Daten

In diesem Dokument wird beschrieben, wie Transport und Nutzlast formatiert werden.

Transport

URL-Endpunkt

Sie senden Daten mit dem Measurement Protocol, indem Sie HTTP-POST-Anfragen an den folgenden Endpunkt senden:

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

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

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

Senden Sie die folgende POST-Anfrage, um ein Ereignis zu senden:

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

  • <payload_data>

    Der BODY der Anfrage. Weitere Informationen finden Sie unter Nutzlast.

Antwortcodes

Das Measurement Protocol gibt immer den Statuscode 2xx zurück, wenn die HTTP-Anfrage empfangen wurde. Das Measurement Protocol gibt keinen Fehlercode zurück, wenn die Nutzlastdaten fehlerhaft formatiert sind oder die Daten in der Nutzlast falsch sind oder nicht von Google Analytics verarbeitet wurden.

Nutzlast

Die Daten werden über das Measurement Protocol in zwei Teilen an Google Analytics gesendet:

  1. Abfrageparameter
  2. Einen JSON POST-Textkörper

Suchparameter

Parametername Beschreibung

api_secret

Erforderlich. Eine API Secret, die über die Google Analytics-Benutzeroberfläche generiert wird.

Wenn Sie ein neues Secret erstellen möchten, gehen Sie in Google Analytics so vor:
Verwaltung > Datenstreams > Stream auswählen > Measurement Protocol > Erstellen

Wir empfehlen, diese nur für Ihre Organisation freizugeben. Wenn Sie das Analyseprotokoll clientseitig implementieren, sollten Sie api_secrets regelmäßig rotieren, um übermäßigen Spam zu vermeiden.

JSON-Posttext

Schlüssel Typ Beschreibung

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.

timestamp_micros

 number

Optional. Ein Unix-Zeitstempel (in Mikrosekunden) für die Zeit, die dem Ereignis zugeordnet werden soll. Diese Einstellung sollte nur festgelegt werden, um Ereignisse aufzuzeichnen, die in der Vergangenheit stattgefunden haben. Dieser Wert kann über user_property oder Ereigniszeitstempel überschrieben werden. Ereignisse können je nach Zeitzone der Unterkunft bis zu drei Kalendertage rückdatiert werden.

user_properties

 object Optional. Die Nutzereigenschaften für die Analyse. Weitere Informationen finden Sie unter Nutzereigenschaften.

user_data

 object Optional. Von Nutzern bereitgestellte Daten Weitere Informationen finden Sie im Leitfaden zu von Nutzern bereitgestellten Daten.
object Optional. Legt die Einwilligungseinstellungen für die Anfrage fest. Weitere Informationen finden Sie im Abschnitt zur Einwilligung.

non_personalized_ads

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

user_location

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

ip_override

 object Optional. Eine IP-Adresse, anhand derer Google Analytics geografische Informationen für die Anfrage ableiten kann.

events[]

 array Erforderlich. Ein Array von Ereigniselementen. Pro Anfrage können bis zu 25 Ereignisse gesendet werden. Eine Liste aller gültigen Ereignisse finden Sie in der Referenz.

events[].name

 string Erforderlich. Der Name des Ereignisses. Eine vollständige Liste aller Optionen finden Sie in der Referenz zu Ereignissen.

events[].params

 object Optional. Die Parameter für das Ereignis. Die vorgeschlagenen Parameter für jedes Ereignis finden Sie unter Ereignisse.

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

Schlüssel Typ Beschreibung

ad_user_data

 string

Optional. Legt die Einwilligung für das Senden von Nutzerdaten aus den Ereignissen und Nutzereigenschaften der Anfrage zu Werbezwecken an Google fest.

Muss entweder GRANTED oder DENIED sein.

ad_personalization

 string

Optional. Legt die Einwilligung für personalisierte Werbung für den Nutzer fest.

Muss entweder GRANTED oder DENIED sein.

Geografische Daten

Verwenden Sie die Attribute user_location oder ip_override, um geografische Informationen für Ereignisse in einer Anfrage anzugeben. user_location hat Vorrang vor ip_override. Die folgende Tabelle enthält 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. Den Namen der Stadt.

region_id

 string Optional. Das Land und die Untergruppe 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. Beispiel: 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.

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

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

Als Alternative zu den strukturierten Informationen in user_location können Sie im Attribut ip_override eine IP-Adresse angeben. In Google Analytics werden dann geografische Informationen aus der IP-Adresse abgeleitet. Wenn in der Anfrage user_location angegeben ist, wird ip_override in Google Analytics ignoriert.

Wenn in einer Anfrage weder user_location noch ip_override angegeben ist, werden in Google Analytics geografische Informationen aus Tagging-Ereignissen mit client_id.

Unabhängig davon, ob Sie user_location oder ip_override angeben, werden in Google Analytics die Einstellungen für detaillierte Standortdaten der Property auf die Anfrage angewendet.

Benutzerdefinierte Parameter

Zusätzlich zu den vorgeschriebenen Parametern können Sie in einer Measurement Protocol-Nutzlast benutzerdefinierte Parameter auf Nutzer-, Ereignis- und Artikelebene angeben.

  • Benutzerdefinierte Parameter auf Nutzerebene können in das user_properties-Objekt der Nutzlast aufgenommen werden.
  • Benutzerdefinierte Parameter auf Ereignisebene können im events[].params-Objekt der Nutzlast enthalten sein.
  • Benutzerdefinierte Parameter auf Artikelebene können für jedes Ereignis im items-Array 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

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

Außerdem dürfen Parameternamen 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_