Invia i dati forniti dagli utenti con lo User-ID utilizzando Measurement Protocol

Analogamente all'utilizzo di gtag, è possibile utilizzare Measurement Protocol di Google Analytics per inviare i dati forniti dagli utenti insieme a User-ID, che può essere utilizzato per migliorare la misurazione del comportamento e delle conversioni.

Per inviare i dati forniti dagli utenti insieme a una richiesta Measurement Protocol, aggiungi il parametro user_data nel payload JSON. Ti consigliamo di includere anche il parametro user_id ogni volta che viene fornito user_data. In questo modo, si garantisce la misurazione più accurata e la funzionalità delle funzionalità.

Measurement Protocol utilizza lo stesso algoritmo di normalizzazione e hashing della funzionalità Misurazione avanzata dell'API Google Ads. Per evitare problemi di privacy, gli indirizzi email, i numeri di telefono, i nomi, i cognomi e gli indirizzi devono essere sottoposti ad hashing utilizzando l'algoritmo SHA-256 prima di essere caricati. Il valore sottoposto ad hashing deve essere codificato in formato stringa esadecimale (oggetto stringa contenente solo cifre esadecimali), ad esempio 88d7ecb5c5b21d7b1.

Per standardizzare i risultati dell'hash, prima di eseguire l'hashing di uno di questi valori devi:

  • Rimuovi gli spazi vuoti iniziali e finali.
  • Converti il testo in minuscolo.
  • Formatta i numeri di telefono secondo lo standard E164.
  • Rimuovi tutti i punti (.) che precedono il nome di dominio negli indirizzi email gmail.com e googlemail.com.

Corpo della richiesta POST JSON

Chiave Tipo Descrizione
user_id stringa un identificatore unico per un utente. Per ulteriori informazioni su questo identificatore, consulta User-ID per l'analisi multipiattaforma.
user_data oggetto Campi dei dati utente avanzati che identificano un utente.
user_data.sha256_email_address[] array di stringhe Indirizzo email dell'utente sottoposto ad hashing e codificato. Normalizzato come segue:
user_data.sha256_phone_number[] array di stringhe Numero di telefono dell'utente sottoposto ad hashing e codifica. Normalizzato come segue:
  • rimuovi tutti i caratteri non numerici
  • aggiungi il prefisso +
  • hash utilizzando l'algoritmo SHA256
  • codifica con il formato della stringa esadecimale.
user_data.address[] matrice Identifica un utente in base alla posizione fisica.
user_data.address[].sha256_first_name stringa Nome dell'utente sottoposto ad hashing e codificato. Normalizzato come segue:
  • rimuovere cifre e simboli
  • minuscolo
  • rimuovere gli spazi iniziali e finali
  • hash utilizzando l'algoritmo SHA256
  • codifica con il formato della stringa esadecimale.
user_data.address[].sha256_last_name stringa Cognome dell'utente sottoposto ad hashing e codificato. Normalizzato come segue:
  • rimuovere cifre e simboli
  • minuscolo
  • rimuovere gli spazi iniziali e finali
  • hash utilizzando l'algoritmo SHA256
  • codifica con il formato della stringa esadecimale.
user_data.address[].sha256_street stringa Via e numero civico dell'utente sottoposti ad hashing e codifica. Normalizzato come segue:
  • rimuovere i caratteri dei simboli
  • minuscolo
  • rimuovere gli spazi iniziali e finali
  • hash utilizzando l'algoritmo SHA256
  • codifica con il formato della stringa esadecimale.
user_data.address[].city stringa La città dell'indirizzo dell'utente. Normalizzato come segue:
  • rimuovere cifre e simboli
  • minuscolo
  • rimuovi gli spazi iniziali e finali.
user_data.address[].region stringa Stato o territorio per l'indirizzo dell'utente. Normalizzato come segue:
  • rimuovere cifre e simboli
  • minuscolo
  • rimuovi gli spazi iniziali e finali.
user_data.address[].postal_code stringa Codice postale dell'indirizzo dell'utente. Normalizzato come segue:
  • rimuovere i caratteri . e ~
  • rimuovi gli spazi iniziali e finali.
user_data.address[].country stringa Codice paese dell'indirizzo dell'utente. Formattato secondo lo standard ISO 3166-1 alpha-2.

Per saperne di più sulla formattazione del trasporto e del payload, consulta la documentazione di riferimento del Measurement Protocol.

Invio dei dati forniti dagli utenti

A differenza di gtag, che esegue automaticamente l'hashing dei dati sensibili forniti dagli utenti, Measurement Protocol richiede a uno sviluppatore di eseguire l'hashing dei dati sensibili forniti dagli utenti utilizzando un algoritmo di hashing unidirezionale sicuro chiamato SHA256 e di codificarli utilizzando il formato stringa esadecimale prima di chiamare l'API.

Tutti i campi di dati utente che iniziano con il prefisso sha256 nel nome devono essere compilati solo con valori sottoposti ad hashing e codificati in formato esadecimale.

Il seguente codice di esempio esegue i passaggi di crittografia e codifica necessari:

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));

Come scorciatoia, tutti i campi ripetuti all'interno dell'oggetto user_data (come address, sha256_email_address, sha256_phone_number) possono ricevere un valore singolo anziché un array.

Il seguente codice di esempio chiama Measurement Protocol e trasmette i dati utente insieme allo 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",
  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
      }
    }
  })
});

Più valori

Gli sviluppatori possono facoltativamente fornire più valori (fino a tre per telefono ed email e due per indirizzo) utilizzando un valore di matrice anziché una stringa. Se acquisisci più di un valore, la probabilità di una corrispondenza aumenterà.

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
      }]
    }
  })
});