Von Nutzern bereitgestellte Daten mit User-ID über das Measurement Protocol senden

Ähnlich wie bei gtag können auch das Google Analytics Measurement Protocol für Google Analytics 4 genutzt werden, um von Nutzern bereitgestellte Daten zusammen mit der User-ID zu senden. Dadurch lassen sich die Funktionsweise und die Conversion-Analyse verbessern.

Wenn Sie von Nutzern bereitgestellte Daten zusammen mit einer Measurement Protocol-Anfrage senden möchten, fügen Sie der JSON-Nutzlast den Parameter user_data hinzu. Der Parameter user_id muss immer vorhanden sein, wenn user_data angegeben wird.

Das Measurement Protocol verwendet denselben Normalisierungs- und Hash-Algorithmus wie die Google Ads API-Funktion für optimierte Analysen. Aus Datenschutzgründen müssen E-Mail-Adressen, Telefonnummern, Vornamen, Nachnamen und Adressen vor dem Hochladen mit dem SHA-256-Algorithmus gehasht werden. Der Hash-Wert sollte im Hexadezimalformat (Stringobjekt, das nur Hexadezimalziffern enthält) codiert sein, z. B. 88d7ecb5c5b21d7b1.

Um die Hash-Ergebnisse zu standardisieren, müssen Sie vor dem Hashen eines dieser Werte Folgendes tun:

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

JSON-Beitragstext

Weitere Informationen zur Formatierung von Transport und Nutzlast finden Sie in der Referenzdokumentation zum Measurement Protocol.

Von Nutzern bereitgestellte Daten senden

Im Gegensatz zu gtag, bei dem sensible von Nutzern bereitgestellte Daten automatisch gehasht werden, müssen Entwickler beim Measurement Protocol sensible von Nutzern bereitgestellte Daten mit dem sicheren Einweg-Hash-Algorithmus SHA256 hashen und vor dem Aufruf der API im Hexadezimalstringformat codieren.

Alle Nutzerdatenfelder, die mit dem Präfix sha256 im Namen beginnen, sollten nur gehashte und hexadezimal codierte Werte enthalten.

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

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

async function populateSensitiveUserData(value) {
  const encoder = new TextEncoder();
  // Convert a string value to UTF-8 encoded text.
  const value_utf8 = encoder.encode(value);
  // Compute the hash (digest) using the SHA-256 algorithm.
  const hash_sha256 = await subtle.digest('SHA-256', value_utf8);
  // Convert buffer to byte array.
  const hash_array = Array.from(new Uint8Array(hash_sha256));
  // Return a hex-encoded string.
  return hash_array.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 Kurzbefehl kann allen wiederkehrenden Feldern im user_data-Objekt (z. B. address, sha256_email_address, sha256_phone_number) ein einzelner Wert anstelle eines Arrays übergeben werden.

Mit dem folgenden Beispielcode wird das Measurement Protocol aufgerufen und es werden Nutzerdaten zusammen mit der User-ID übergeben.

const measurement_id = 'G-XXXXXXXXXX';
const api_secret = '<secret_value>';

// 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=${measurement_id}&api_secret=${api_secret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: 'XXXXXXXXXX.YYYYYYYYYY',
    user_id: "XXX",
    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 optional mehrere Werte angeben (bis zu drei für Telefonnummer und E-Mail-Adresse und bis zu zwei für Adresse), indem sie einen Arraywert anstelle eines Strings verwenden. Wenn Sie mehr als einen Wert erfassen, erhöht die Angabe dieses Werts die Wahrscheinlichkeit einer Übereinstimmung.

const measurement_id = 'G-XXXXXXXXXX';
const api_secret = '<secret_value>';

fetch(`https://www.google-analytics.com/mp/collect?measurement_id=${measurement_id}&api_secret=${api_secret}`, {
  method: "POST",
  body: JSON.stringify({
    client_id: 'XXXXXXXXXX.YYYYYYYYYY',
    user_id: "XXX",
    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
      }]
    }
  })
});