Enviar datos proporcionados por los usuarios con User-ID usando Measurement Protocol

Con Measurement Protocol de Google Analytics para Google Analytics 4, puedes enviar datos proporcionados por los usuarios con User-ID, de manera similar a como se hace con gtag. Esto te puede ayudar a medir mejor el comportamiento y las conversiones.

Para enviar datos proporcionados por los usuarios junto con una solicitud de Measurement Protocol, añade el parámetro user_data a la carga útil JSON. El parámetro user_id debe estar presente siempre que se proporcione user_data.

Measurement Protocol usa el mismo algoritmo de normalización y cifrado con hash que la función de medición mejorada de la API de Google Ads. Para evitar problemas de privacidad, se debe usar el algoritmo SHA-256 para cifrar con hash las direcciones de correo electrónico, los números de teléfono, los nombres, los apellidos y las direcciones postales antes de subir estos datos. El valor cifrado con hash se debe codificar con formato de cadena hexadecimal (es decir, como un objeto que contenga solo dígitos hexadecimales), como 88d7ecb5c5b21d7b1.

Para estandarizar los resultados de hash, haz lo siguiente antes de cifrar cualquiera de esos valores:

  • Elimina los espacios iniciales y finales.
  • Convierte el texto a minúsculas.
  • Usa el formato estándar E164 con los números de teléfono.
  • Elimina todos los puntos (.) que haya delante del nombre de dominio en las direcciones de correo de gmail.com y googlemail.com.

Cuerpo de la publicación JSON

Clave Tipo Descripción
user_id string Identificador único del usuario. Consulta el artículo [GA4] Medir la actividad en distintas plataformas con User-ID para obtener más información sobre este identificador.
user_data object Campos mejorados de datos de usuarios que identifican al usuario.
user_data.sha256_email_address[] string array La dirección de correo electrónico del usuario cifrada con hash, codificada y normalizada de la siguiente manera:
user_data.sha256_phone_number[] string array El número de teléfono del usuario cifrado con hash, codificado y normalizado de la siguiente manera:
  • Sin caracteres que no sean dígitos
  • Con el prefijo +
  • Cifrado con hash mediante el algoritmo SHA256
  • Codificado en formato de cadena hexadecimal
user_data.address[] array Identifica al usuario en función de su ubicación física.
user_data.address[].sha256_first_name string El nombre del usuario cifrado con hash, codificado y normalizado de la siguiente manera:
  • Sin dígitos ni símbolos
  • En minúsculas
  • Sin espacios iniciales ni finales
  • Cifrado con hash mediante el algoritmo SHA256
  • Codificado en formato de cadena hexadecimal
user_data.address[].sha256_last_name string El apellido del usuario cifrado con hash, codificado y normalizado de la siguiente manera:
  • Sin dígitos ni símbolos
  • En minúsculas
  • Sin espacios iniciales ni finales
  • Cifrado con hash mediante el algoritmo SHA256
  • Codificado en formato de cadena hexadecimal
user_data.address[].sha256_street string La calle y el número del usuario cifrados con hash, codificados y normalizados de la siguiente manera:
  • Sin símbolos
  • En minúsculas
  • Sin espacios iniciales ni finales
  • Cifrados con hash mediante el algoritmo SHA256
  • Codificados en formato de cadena hexadecimal
user_data.address[].city string La ciudad o localidad de la dirección del usuario, normalizada de la siguiente manera:
  • Sin dígitos ni símbolos
  • En minúsculas
  • Sin espacios iniciales ni finales
user_data.address[].region string El estado o territorio de la dirección del usuario, normalizados de la siguiente manera:
  • Sin dígitos ni símbolos
  • En minúsculas
  • Sin espacios iniciales ni finales
user_data.address[].postal_code string El código postal de la dirección del usuario, normalizado de la siguiente manera:
  • Sin los caracteres . ni ~
  • Sin espacios iniciales ni finales
user_data.address[].country string El código del país de la dirección del usuario, con el formato del estándar ISO 3166-1 alfa-2.

En la referencia de Measurement Protocol encontrarás más información sobre cómo se aplica formato al transporte y a la carga útil.

Enviar datos proporcionados por los usuarios

A diferencia de gtag, que cifra con hash automáticamente los datos sensibles proporcionados por los usuarios, con Measurement Protocol es necesario que un desarrollador cifre esos datos mediante un algoritmo seguro y unidireccional llamado SHA256, y que también los codifique con el formato de cadena hexadecimal antes de llamar a la API.

Todos los campos de datos de usuarios que tienen el prefijo sha256 en el nombre solo se deben rellenar con valores que se hayan cifrado con hash y codificado.

En el ejemplo de abajo, se llevan a cabo los pasos de cifrado y codificación necesarios:

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

Para facilitar el proceso, a todos los campos repetidos del objeto user_data (como address, sha256_email_address o sha256_phone_number) se les puede enviar un valor singular en lugar de un array.

El siguiente código de muestra llama a Measurement Protocol y envía datos de usuario con 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
      }
    }
  })
});

Varios valores

Los desarrolladores pueden proporcionar varios valores (hasta tres para el número de teléfono y la dirección de correo, y dos para la dirección) mediante valores de array en lugar de cadenas. Si recoges más de un valor, será más probable que haya concordancias.

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