Von Nutzern bereitgestellte Daten mit dem Measurement Protocol senden

Ähnlich wie bei gtag, können Sie mit dem Google Analytics Measurement Protocol von Nutzern bereitgestellte Daten zusammen mit der User-ID senden. Diese Daten können verwendet werden, um die Verhaltens- und Conversion-Analyse zu verbessern.

Wenn Sie von Nutzern bereitgestellte Daten zusammen mit einer Measurement Protocol-Anfrage senden möchten, fügen Sie den Parameter user_data in die JSON-Nutzlast ein. Wir empfehlen, auch den Parameter user_id anzugeben, wenn user_data bereitgestellt wird. So lassen sich die genauesten Messungen und die beste Funktionsweise der Funktionen gewährleisten.

Für das Measurement Protocol wird derselbe Normalisierungs- und Hashing-Algorithmus wie für die Funktion „Erweiterte Messung“ der Google Ads API verwendet. Aus Datenschutzgründen müssen E-Mail-Adressen, Telefonnummern, Vornamen, Nachnamen und Straßenadressen mit dem SHA-256-Algorithmus gehasht werden, bevor sie hochgeladen werden. Der gehashte Wert sollte im Hex-String-Format codiert sein (String-Objekt, das nur Hexadezimalziffern enthält), z. B. 88d7ecb5c5b21d7b1.

Um die Hash-Ergebnisse zu standardisieren, müssen Sie vor dem Hashen eines dieser Werte folgende Schritte ausführen:

  • Entfernen Sie Leerzeichen am Anfang und Ende.
  • Verwenden Sie nur Kleinbuchstaben im Text.
  • Formatieren Sie Telefonnummern entsprechend dem E.164-Standard.
  • Entfernen Sie alle Punkte (.) vor dem Domainnamen in gmail.com- und googlemail.com-E-Mail-Adressen.

JSON-Post-Text

Schlüssel Typ Beschreibung
user_id (optional, aber empfohlen) String Eine eindeutige Kennung für einen Nutzer. Weitere Informationen zu dieser Kennung finden Sie unter User-ID für plattformübergreifende Analysen.
user_data Objekt Erweiterte Nutzerdatenfelder zur Identifizierung eines Nutzers.
user_data.sha256_email_address[] String-Array Gehashte und codierte E-Mail-Adresse des Nutzers. Normalisiert wie folgt:
user_data.sha256_phone_number[] String-Array Gehashte und codierte Telefonnummer des Nutzers. Normalisiert wie folgt:
  • Alle Zeichen entfernen, die keine Ziffern sind
  • Präfix + hinzufügen
  • Mit dem SHA256-Algorithmus hashen
  • Im Hex-String-Format codieren.
user_data.address[] Array Identifiziert einen Nutzer anhand des physischen Standorts.
user_data.address[].sha256_first_name String Gehashter und codierter Vorname des Nutzers. Normalisiert wie folgt:
  • Ziffern und Symbolzeichen entfernen
  • Kleinschreibung
  • Leerzeichen am Anfang und Ende entfernen
  • Mit dem SHA256-Algorithmus hashen
  • Im Hex-String-Format codieren.
user_data.address[].sha256_last_name String Gehashter und codierter Nachname des Nutzers. Normalisiert wie folgt:
  • Ziffern und Symbolzeichen entfernen
  • Kleinschreibung
  • Leerzeichen am Anfang und Ende entfernen
  • Mit dem SHA256-Algorithmus hashen
  • Im Hex-String-Format codieren.
user_data.address[].sha256_street String Gehashte und codierte Straße und Hausnummer des Nutzers. Normalisiert wie folgt:
  • Symbolzeichen entfernen
  • Kleinschreibung
  • Leerzeichen am Anfang und Ende entfernen
  • Mit dem SHA256-Algorithmus hashen
  • Im Hex-String-Format codieren.
user_data.address[].city String Ort der Adresse des Nutzers. Normalisiert wie folgt:
  • Ziffern und Symbolzeichen entfernen
  • Kleinschreibung
  • Leerzeichen am Anfang und Ende entfernen.
user_data.address[].region String Bundesland oder Gebiet der Adresse des Nutzers. Normalisiert wie folgt:
  • Ziffern und Symbolzeichen entfernen
  • Kleinschreibung
  • Leerzeichen am Anfang und Ende entfernen.
user_data.address[].postal_code String Postleitzahl der Adresse des Nutzers. Normalisiert wie folgt:
  • Zeichen . und ~ entfernen
  • Leerzeichen am Anfang und Ende entfernen.
user_data.address[].country String Ländercode der Adresse des Nutzers. Gemäß ISO 3166-1 Alpha-2-Standard formatiert.

Weitere Informationen zur Formatierung des Transports und der Nutzlast finden Sie in der Referenzdokumentation zum Measurement Protocol.

Von Nutzern bereitgestellte Daten senden

Im Gegensatz zu gtag, das vertrauliche von Nutzern bereitgestellte Daten automatisch hasht, müssen Entwickler beim Measurement Protocol vertrauliche von Nutzern bereitgestellte Daten mit einem sicheren Einweg- Hash-Algorithmus namens SHA256 hashen und im Hex-String-Format codieren, bevor sie die API aufrufen.

Alle Nutzerdatenfelder, deren Name mit dem Präfix sha256 beginnt, dürfen nur gehashte und hexadezimal codierte Werte enthalten.

Der folgende Beispielcode führt die erforderlichen Verschlüsselungs- und Codierungsschritte aus:

Node.js

const { subtle } = require('crypto').webcrypto;

async function populateSensitiveUserData(value) {
  const encoder = new TextEncoder();
  // Convert a string value to UTF-8 encoded text.
  const valueUtf8 = encoder.encode(value);
  // Compute the hash (digest) using the SHA-256 algorithm.
  const hashSha256 = await subtle.digest('SHA-256', valueUtf8);
  // Convert buffer to byte array.
  const hashArray = Array.from(new Uint8Array(hashSha256));
  // Return a hex-encoded string.
  return hashArray.map(b => b.toString(16).padStart(2, "0")).join('');
};

// Test the encryption function by calling it.
async function main() {
  return await populateSensitiveUserData('<value>');
}

main()
  .then(v => console.log(v))
  .catch(err => console.error(err));

Als praktische Abkürzung können für alle wiederholten Felder im user_data Objekt (z. B. address, sha256_email_address, sha256_phone_number) einzelne Werte anstelle eines Arrays übergeben werden.

Der folgende Beispielcode ruft das Measurement Protocol auf und übergibt Nutzerdaten zusammen mit der User-ID.

Node.js

const measurementId = "MEASUREMENT_ID";
const apiSecret = "API_SECRET";

// Populate mock User Data using the `populateSensitiveUserData` function defined
// above.
const yourEmailSha256Variable = await populateSensitiveUserData('test@yourdomain.com');
const yourPhoneSha256Variable  = await populateSensitiveUserData('+15555555555');
const yourFirstNameSha256Variable  = await populateSensitiveUserData('john');
const yourLastNameSha256Variable  = await populateSensitiveUserData('doe');
const yourStreetAddressSha256Variable  = await populateSensitiveUserData('123 main street');

// Populate mock unencrypted user data.
const yourCityVariable = 'san francisco';
const yourRegionVariable = 'california';
const yourPostalCodeVariable = '94000';
const yourCountryVariable = 'US';

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    client_id: "CLIENT_ID",
    user_id: "USER_ID",
    events: [{
      name: "purchase"
    }],
    user_data: {
      sha256_email_address: yourEmailSha256Variable,
      sha256_phone_number: yourPhoneSha256Variable,
      address: {
        sha256_first_name: yourFirstNameSha256Variable,
        sha256_last_name: yourLastNameSha256Variable,
        sha256_street: yourStreetAddressSha256Variable,
        city: yourCityVariable,
        region: yourRegionVariable,
        postal_code: yourPostalCodeVariable,
        country: yourCountryVariable
      }
    }
  })
});

Mehrere Werte

Entwickler können statt eines Strings einen Array-Wert verwenden, um mehrere Werte anzugeben (bis zu drei für die Telefonnummer und die E-Mail-Adresse und bis zu zwei für die Anschrift). Wenn Sie mehr als einen Wert erfassen, steigt dann die Wahrscheinlichkeit einer Übereinstimmung.

Node.js

const measurementId = "MEASUREMENT_ID";
const apiSecret = "API_SECRET";

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurementId}&api_secret=${apiSecret}`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    client_id: "CLIENT_ID",
    user_id: "USER_ID",
    events: [{
      name: "purchase"
    }],
    user_data: {
      sha256_email_address: [yourEmailSha256Variable1, yourEmailSha256Variable2],
      sha256_phone_number: [yourPhoneSha256Variable1, yourPhoneSha256Variable2],
      address: [{
        sha256_first_name: yourFirstNameSha256Variable1,
        sha256_last_name: yourLastNameSha256Variable1,
        sha256_street: yourStreetAddressSha256Variable1,
        city: yourCityVariable1,
        region: yourRegionVariable1,
        postal_code: yourPostalCodeVariable1,
        country: yourCountryVariable1
      },{
        sha256_first_name: yourFirstNameSha256Variable2,
        sha256_last_name: yourLastNameSha256Variable2,
        sha256_street: yourStreetAddressSha256Variable2,
        city: yourCityVariable2,
        region: yourRegionVariable2,
        postal_code: yourPostalCodeVariable2,
        country: yourCountryVariable2
      }]
    }
  })
});