Measurement Protocol-Referenz

In diesem Dokument wird beschrieben, wie Sie Daten mit dem Measurement Protocol an Google Analytics senden.

Übersicht

Es gibt zwei Teile, die Daten über das Measurement Protocol an Google Analytics senden:

  • Transport – wohin und wie Sie Daten senden
  • Die Nutzlast – die Daten, die Sie senden

In diesem Dokument wird beschrieben, wie Sie beide formatieren.

Transport

URL-Endpunkt

Zum Senden von Daten mithilfe des Measurement Protocol senden Sie HTTP-Anfragen an den folgenden Endpunkt:

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

Alle Daten sollten sicher mit dem HTTPS-Protokoll gesendet werden.

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

POST verwenden

Wir empfehlen, Daten über POST zu senden, da dadurch eine größere Nutzlast möglich ist. Geben Sie bei Verwendung von POST die folgende HTTP-Anfrage aus:

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

Dabei gilt:

  • user_agent_string: Ist ein formatierter User-Agent-String, der zur Berechnung der folgenden Dimensionen verwendet wird: Browser-, Plattform- und Mobilfunktionen.

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

  • payload_data – Die BODY der Beitragsanfrage. Der Text muss genau 1 URI-codierte Nutzlast enthalten. Er darf nicht länger als 8.192 Byte sein.
  • IP-Adresse: Wird implizit in der HTTP-Anfrage gesendet und zum Berechnen aller geografischen / Netzwerkdimensionen in Google Analytics verwendet.

NEUIGKEITEN

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

Die Nutzlastdaten werden als URI-maskierte Abfrageparameter gesendet. Die gesamte codierte URL darf nicht länger als 8.000 Byte sein.

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 bietet das Measurement Protocol einen speziellen Parameter (z), 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 last-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, die Daten in der Nutzlast falsch waren oder nicht von Google Analytics verarbeitet wurden.

Wenn du keinen 2xx-Statuscode erhältst, solltest du die Anfrage NICHT wiederholen. Stattdessen sollten Sie alle Fehler in Ihrer HTTP-Anfrage stoppen und korrigieren.

Nutzlastdaten

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

key1=val1&key2=val2

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

Eine vollständige Liste aller Parameter, die Sie über das Measurement Protocol senden können, finden Sie in der Parameterreferenz.

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

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

Alle an Google Analytics gesendeten Werte müssen sowohl UTF-8- als auch URL-codiert sein. Zum Senden des Schlüssels dp mit dem Wert /my page € müssen Sie zuerst sicherstellen, dass dies UTF-8, dann URL-codiert ist, 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 möglicherweise nur mit bestimmten Treffertypen gesendet. Für den Treffertyp pageview muss beispielsweise auch der Parameter „Seitenpfad“ (dp) festgelegt werden. 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 Feld „Verweisdokument“ dr hat beispielsweise eine maximale Länge von 2.048 Byte. Wenn einer der Werte die maximale Länge überschreitet, wird er automatisch gekürzt. Wenn ein Multi-Byte-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 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 gelten möglicherweise eigene Einschränkungen. Eine vollständige Liste aller Datenfelder und zulässigen Typen finden Sie in der Feldreferenz.

Text

Wird für Strings verwendet. Für die Textfelder werden zusätzliche Angaben gemacht. 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 vor dem Abschneiden auf den Rohtext angewendet. Beispiel:

   Hello      World

wird zu:

Hello World

Währung

Wird für den Gesamtwert einer Währung verwendet. 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

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

$-55.00

wird zu:

-55.00

Boolesch

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

  • 1 – Wahr
  • 0 – Falsch

Ganzzahl

Wird für eine Ganzzahl verwendet. Der Wert wird als int64-Signatur gespeichert

Zahl

Wird für eine Ganzzahl oder eine Gleitkommazahl verwendet.