Measurement Protocol-Referenz

In diesem Dokument wird beschrieben, wie Daten mithilfe des Measurement Protocol an Google Analytics gesendet werden.

Überblick

Das Senden von Daten an Google Analytics erfolgt über das Measurement Protocol in zwei Schritten:

  • Der Transport – wohin und wie du Daten sendest
  • Die Nutzlast – die von Ihnen gesendeten Daten

In diesem Dokument wird die Formatierung beider Formate beschrieben.

Transport

URL-Endpunkt

Wenn Sie Daten über das Measurement Protocol senden, senden Sie HTTP-Anfragen an den folgenden Endpunkt:

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

Alle Daten sollten sicher über das HTTPS-Protokoll gesendet werden.

Sie können Daten mit POST- oder GET-Anfragen senden.

POST verwenden

Wir empfehlen, Daten über POST zu senden, da dies eine größere Nutzlast ermöglicht. Wenn Sie POST verwenden, senden Sie die folgende HTTP-Anfrage:

User-Agent: user_agent_string
POST https://www.google-analytics.com/collect
payload_data

Wobei:

  • user_agent_string: ist ein formatierter User-Agent-String, mit dem die folgenden Dimensionen berechnet werden: Funktionen für Browser, Plattform und Mobilgeräte.

    Wenn dieser Wert nicht festgelegt ist, werden die obigen Daten nicht berechnet.

  • payload_dataBODY der Post-Anfrage. Der Text muss genau eine URI-codierte Nutzlast enthalten und darf nicht länger als 8.192 Byte sein.
  • IP-Adresse: Wird implizit in der HTTP-Anfrage gesendet und zur Berechnung aller Geo-/Netzwerkdimensionen in Google Analytics verwendet.

GET

In Umgebungen, in denen Sie keine POST-Daten senden können, können Sie auch HTTP-GET-Anfragen an denselben Endpunkt senden:

GET /collect?payload_data HTTP/1.1
Host: https://www.google-analytics.com
User-Agent: user_agent_string

Wo die Nutzlastdaten als URI-maskierte Abfrageparameter gesendet werden. Die gesamte codierte URL darf 8.000 Byte nicht überschreiten.

Cache-Busting

In einigen Umgebungen, wie z. B. Browsern, werden HTTP GET-Anfragen möglicherweise im Cache gespeichert. Wenn eine Anfrage im Cache gespeichert wird, können nachfolgende Anfragen aus dem Cache abgerufen und nicht an Google Analytics gesendet werden. Für das Durchsuchen des Caches stellt das Measurement Protocol einen speziellen Parameter (z) bereit, der mit einer Zufallszahl festgelegt werden kann. Dadurch wird sichergestellt, dass alle Measurement Protocol-Anfragen eindeutig sind und nachfolgende Anfragen nicht aus dem Cache abgerufen werden.

Wenn Sie den Cache-Buster verwenden, empfehlen wir dringend, diesen Parameter als letzten Parameter in der Nutzlast hinzuzufügen.

https://www.google-analytics.com/collect?payload_data&z=123456

Antwortcodes

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

Wenn Sie keinen 2xx-Statuscode erhalten, sollten Sie die Anfrage NICHT wiederholen. Stattdessen sollten Sie die HTTP-Anfrage beenden und Fehler in Ihrer HTTP-Anfrage korrigieren.

Nutzlastdaten

Alle von Google Analytics mit dem Measurement Protocol erfassten Daten werden als Nutzlast gesendet. Die Nutzlast ähnelt einem URL-Abfragestring, bei dem jeder Parameter einen Schlüssel und einen Wert hat, die durch ein =-Zeichen getrennt und jedes Paar durch ein &-Zeichen getrennt ist. Beispiel:

key1=val1&key2=val2

Für jede Nutzlast gelten Regeln: erforderliche Werte, URI-Codierung, Parameter, die zusammen gesendet werden können, und Parameterlänge. Außerdem hat jeder Parameter einen bestimmten Typ, der ein bestimmtes Format erfordert. In den folgenden Abschnitten werden diese Regeln beschrieben.

In der Parameterreferenz finden Sie eine vollständige Liste aller Parameter, die Sie mit dem Measurement Protocol senden können.

Erforderliche Werte für alle Treffer

Die folgenden Parameter müssen in jeder Nutzlast enthalten sein:

Name Parameter Beispiel Beschreibung
Protokollversion v v=1 Die Protokollversion. Der Wert sollte 1 sein.
Tracking-ID tid tid=UA-123456-1 Mit dieser ID wird festgelegt, an welche Google Analytics-Property Daten gesendet werden.
Client-ID cid cid=xxxxx Eine eindeutige ID für einen bestimmten Nutzer.
Treffertyp t t=pageview Die Art der Interaktion, die für einen bestimmten Nutzer erfasst wird.

Die Daten für Client ID und Hit Type sind Werte, die direkt dem Google Analytics-Datenmodell zugeordnet werden. Wenn Sie den Nutzer 5555 verfolgen möchten, der zu /pageA, /pageB und /pageC gelangt ist, senden Sie die folgenden 3 Nutzlasten:

v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageA
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageB
v=1&tid=UA-123456-1&cid=5555&t=pageview&dp=%2FpageC

Beachten Sie, dass / in %2F codiert wurde.

URL-Codierungswerte

Alle an Google Analytics gesendeten Werte müssen sowohl in UTF-8 als auch URL-codiert sein. Wenn Sie den Schlüssel dp mit dem Wert /my page € senden möchten, muss dieser UTF-8- und dann URL-codiert sein. Daraus ergibt sich der endgültige String:

dp=%2Fmy%20page%20%E2%82%AC

Wenn eines der Zeichen falsch codiert ist, wird es durch das Unicode-Ersatzzeichen xFFFD ersetzt.

Erforderliche Werte für bestimmte Treffertypen

Einige Parameter werden eventuell nur mit bestimmten Treffertypen gesendet. Für den Treffertyp pageview muss beispielsweise auch der Parameter „Seitenpfad“ (dp) festgelegt sein. In der Parameterreferenz wird beschrieben, welche Parameter für welche Treffertypen erforderlich sind.

Maximale Länge

Einige Textwerte im Measurement Protocol haben bestimmte maximale Längen in Byte. Das Feld „Dokumentverweis“ dr hat beispielsweise eine maximale Länge von 2.048 Byte. Wenn einer der Werte die maximale Länge überschreitet, wird er automatisch abgeschnitten. Wenn ein Multibyte-Zeichen die maximale Länge überschreitet, wird das gesamte Zeichen abgeschnitten.

Unterstützte Datentypen

Jedes Datenfeld im Measurement Protocol gehört zu einem bestimmten Typ mit jeweils eigenen Validierungsregeln. Entspricht einer der Parameterwerte nicht den Validierungsregeln, wird der jeweilige Parameter ignoriert und nicht von Google Analytics verarbeitet. Alle anderen Parameter werden wie gewohnt verarbeitet.

Das Measurement Protocol unterstützt die folgenden Datentypen:

Für einzelne Datenfelder können eigene Einschränkungen gelten. Eine vollständige Liste aller Datenfelder und akzeptierten Typen finden Sie in der Feldreferenz.

Text

Wird zur Darstellung von Strings verwendet. Textfelder werden zusätzlich verarbeitet. Alle voran- und nachgestellten Leerzeichen werden entfernt. Interne Ausführungen von zwei oder mehr Leerzeichen (einschließlich Leerzeichen, Tabulatorzeichen, Zeilenumbrüche usw.) werden auf ein einzelnes Leerzeichen reduziert. Diese Transformation wird auf den Rohtext angewendet, bevor er abgeschnitten wird. Beispiel:

   Hello      World

wird:

Hello World

Currency

Wird verwendet, um den Gesamtwert einer Währung darzustellen. Ganzer und Bruchteil der Währung werden durch einen Dezimaltrennzeichen getrennt. Die Genauigkeit kann mit bis zu sechs Dezimalstellen angegeben werden. Folgendes gilt für ein Währungsfeld:

1000.000001

Sobald der Wert an Google Analytics gesendet wurde, wird der gesamte Text bis zur ersten Ziffer, dem --Zeichen oder dem .-Zeichen (Dezimalzeichen) entfernt. Das bedeutet:

$-55.00

wird:

-55.00

Boolesch

Wird verwendet, um zu bestimmen, ob ein Wert wahr oder falsch ist. Gültige Werte sind:

  • 1 – Wahr
  • 0 – Falsch

Ganzzahl

Wird zur Darstellung einer Ganzzahl verwendet. Der Wert wird als vorzeichenbehafteter int64-Wert gespeichert.

Zahl

Wird zur Darstellung einer Ganzzahl oder einer Gleitkommazahl verwendet.