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

In modo simile a gtag, puoi utilizzare il protocollo Measurement Protocol di Google Analytics per inviare i dati forniti dagli utenti insieme allo User-ID, che possono essere utilizzati per migliorare la misurazione del comportamento e delle conversioni.

Per inviare i dati forniti dall'utente insieme a una richiesta di Measurement Protocol, aggiungi il parametro Parametro user_data nel payload JSON. Il parametro user_id deve essere presente ogni volta che viene fornito user_data.

Measurement Protocol utilizza lo stesso algoritmo di normalizzazione e hashing come il Misurazione avanzata dell'API Google Ads funzionalità. Per problemi di privacy, indirizzi email, numeri di telefono, nomi, cognomi, e gli indirizzi devono essere sottoposti ad hashing utilizzando Algoritmo SHA-256 prima del giorno in fase di caricamento. Il valore sottoposto ad hashing deve essere codificato in formato stringa esadecimale (stringa) contenente solo cifre esadecimali), come88d7ecb5c5b21d7b1.

Al fine di standardizzare i risultati di hashing, prima di eseguire l'hashing di uno dei devi:

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

Corpo del post JSON

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

Consulta la documentazione di riferimento di Measurement Protocol per ulteriori informazioni su come vengono formattati il trasporto e il payload.

Invia i dati forniti dall'utente

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

Tutti i campi di dati utente che iniziano con il prefisso sha256 nel nome devono essere solo con valori sottoposti ad hashing e con codifica 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 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));

Per comodità, tutti i campi ripetuti all'interno dell'oggetto user_data (ad esempio address, sha256_email_address, sha256_phone_number) può essere ha passato un valore singolare invece di un array.

Il seguente codice di esempio chiama Measurement Protocol e trasmette i dati utente insieme allo User-ID.

Node.js

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

Più valori

Gli sviluppatori possono facoltativamente fornire più valori (fino a tre per telefono ed email e 2 per indirizzo) utilizzando un valore di array anziché una stringa. Se acquisisci più di un valore, così aumenterai le probabilità di una corrispondenza.

Node.js

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