Measurement Protocol-Referenz

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

Überblick

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

• Der Transport – wohin und wie Daten gesendet werden
• Die Nutzlast – die von Ihnen gesendeten Daten

In diesem Dokument wird beschrieben, wie beide formatiert werden.

Transport

URL-Endpunkt

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

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, geben Sie die folgende HTTP-Anfrage aus:

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: Browser-, Plattform- und Mobilgerätefunktionen.

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

• payload_data – BODY 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 geografischen / 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

Der Ort, an dem die Nutzlastdaten als URI-maskierte Abfrageparameter gesendet werden. Die gesamte codierte URL darf 8.000 Byte nicht überschreiten.

Cache-Busting

In einigen Umgebungen, z. B. in Browsern, werden HTTP GET-Anfragen möglicherweise im Cache gespeichert. Wenn eine Anfrage im Cache gespeichert wird, werden nachfolgende Anfragen möglicherweise aus dem Cache abgerufen und nicht an Google Analytics gesendet. 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 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 den Vorgang beenden und alle Fehler in Ihrer HTTP-Anfrage korrigieren.

Nutzlastdaten

Alle Daten, die von Google Analytics mit dem Measurement Protocol erfasst werden, 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 sind und jedes Paar durch ein &-Zeichen getrennt ist. Beispiel:

key1=val1&key2=val2

Jede Nutzlast hat Regeln, die Folgendes steuern: erforderliche Werte, URI-Codierung, Parameter, die zusammen gesendet werden können, und Parameterlänge. Außerdem hat jeder Parameter einen bestimmten Typ, für den ein bestimmtes Format erforderlich ist. Diese Regeln werden in den folgenden Abschnitten erläutert.

In der Parameterreferenz finden Sie eine vollständige Liste aller Parameter, die mit dem Measurement Protocol gesendet werden 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 wurde.

Die Daten für Client ID und Hit Type sind Werte, die dem Google Analytics-Datenmodell direkt zugeordnet werden. Wenn Sie den Nutzer 5555 verfolgen möchten, der zu /pageA, /pageB und /pageC gelangt ist, senden Sie die folgenden drei 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

Wie Sie sehen, wurde / in %2F codiert.

URL-Codierungswerte

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

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 eine bestimmte maximale Länge in Byte. Das Dokumentverweis-Feld dr hat beispielsweise eine maximale Länge von 2.048 Byte. Wenn einer der Werte größer als die Maximallänge ist, 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. Wenn einer der Parameterwerte nicht den Validierungsregeln entspricht, wird dieser spezifische Parameter ignoriert und nicht von Google Analytics verarbeitet. Alle anderen Parameter werden wie gewohnt verarbeitet.

Hinweis: Wenn ein erforderlicher Parameter fehlerhaft ist, wird nicht die gesamte Nutzlast verarbeitet. Wenn beispielsweise der Wert bogus für den erforderlichen Treffertypparameter gesendet wird, würde die gesamte Nutzlast nicht verarbeitet werden.

Das Measurement Protocol unterstützt die folgenden Datentypen:

• Text
• Währung
• Boolesch
• Ganzzahl
• Number

Für einzelne Datenfelder können eigene Einschränkungen gelten. In der Feldreferenz finden Sie eine vollständige Liste aller Datenfelder und zulässigen Typen.

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 zu:

Hello World

Währung

Wird verwendet, um den Gesamtwert einer Währung darzustellen. Ein Dezimalpunkt wird als Trennzeichen zwischen dem Ganzen und dem Bruchteil der Währung verwendet. Die Genauigkeit kann mit bis zu sechs Dezimalstellen angegeben werden. Folgendes gilt für ein Währungsfeld:

1000.000001

Nachdem 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 zu:

-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.