Ähnlich wie bei der Verwendung von gtag können Sie mit dem Google Analytics Measurement Protocol von Nutzern bereitgestellte Daten zusammen mit der User-ID senden. So lassen sich die Analyse des Verhaltens und der Conversions 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, den Parameter user_id immer dann anzugeben, wenn user_data angegeben wird. So lassen sich die Leistung und die Funktionen am genauesten messen.
Für das Measurement Protocol wird derselbe Normalisierungs- und Hashing-Algorithmus wie für die Funktion Erweiterte Analyse mit der Google Ads API verwendet.
Aus Datenschutzgründen müssen E-Mail-Adressen, Telefonnummern, Vor- und Nachnamen sowie Adressen mit dem SHA-256 gehasht werden, bevor sie hochgeladen werden. Der gehashte Wert sollte im Hex-String-Format codiert werden (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 gemäß dem E164-Standard.
- Entfernen Sie alle Punkte (.) vor dem Domainnamen in
gmail.com- undgooglemail.com-E-Mail-Adressen.
JSON-Text des POST-Vorgangs
| Schlüssel | Typ | Beschreibung |
|---|---|---|
| user_id | String | Eine eindeutige Kennung für einen Nutzer. Weitere Informationen zu plattformübergreifenden Analysen mithilfe der User-ID |
| 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:
|
| user_data.sha256_phone_number[] | String-Array | Gehashte und codierte Telefonnummer des Nutzers.
Normalisiert:
|
| 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:
|
| user_data.address[].sha256_last_name | String | Gehashter und codierter Nachname des Nutzers.
Normalisiert:
|
| user_data.address[].sha256_street | String | Gehashte und codierte Straße und Hausnummer des Nutzers.
Normalisiert:
|
| user_data.address[].city | String | Ort der Adresse des Nutzers
Normalisiert:
|
| user_data.address[].region | String | Bundesland oder Gebiet der Adresse des Nutzers
Normalisiert:
|
| user_data.address[].postal_code | String | Postleitzahl der Adresse des Nutzers
Normalisiert:
|
| user_data.address[].country | String | Ländercode der Adresse des Nutzers Gemäß ISO 3166-1 ALPHA-2 formatiert. |
Weitere Informationen zur Formatierung von Transport und Nutzlast finden Sie in der Referenzdokumentation zum Measurement Protocol.
Von Nutzern bereitgestellte Daten senden
Im Gegensatz zum gtag, bei dem vertrauliche, von Nutzern bereitgestellte Daten automatisch gehasht werden, müssen Entwickler beim Measurement Protocol vertrauliche, von Nutzern bereitgestellte Daten mit einem sicheren Einweg-Hashing-Algorithmus namens SHA256 hashen und im Hexadezimalstringformat codieren, bevor sie die API aufrufen.
Alle Nutzerdatenfelder, deren Name mit dem Präfix sha256 beginnt, sollten nur mit gehashten und hexadezimal codierten Werten gefüllt werden.
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 kann für alle wiederholten Felder im Objekt user_data (z. B. address, sha256_email_address, sha256_phone_number) ein einzelner Wert anstelle eines Arrays übergeben werden.
Im folgenden Beispielcode wird das Measurement Protocol aufgerufen und Nutzerdaten werden zusammen mit der User-ID übergeben.
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",
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",
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
}]
}
})
});