Enviar datos proporcionados por el usuario con User-ID a través del Protocolo de medición

Al igual que con gtag, es posible usar el Protocolo de medición de Google Analytics para Google Analytics 4 a fin de enviar datos proporcionados por el usuario junto con User-ID, que se puede usar para mejorar el comportamiento y la medición de conversiones.

Para enviar datos proporcionados por el usuario junto con una solicitud del Protocolo de medición, agrega el parámetro user_data en la carga útil de JSON. El parámetro user_id debe estar presente siempre que se proporcione user_data.

El Protocolo de medición usa el mismo algoritmo de normalización y hash que la función de Medición mejorada de la API de Google Ads. Por cuestiones de privacidad, las direcciones de correo electrónico, los números de teléfono, los nombres, los apellidos y las direcciones deben tener un hash mediante el algoritmo SHA-256 antes de la carga. El valor de hash debe estar codificado en formato de string hexadecimal (objeto de string que solo contiene dígitos hexadecimales), como 88d7ecb5c5b21d7b1.

Para estandarizar los resultados del hash, antes de generar un hash de uno de estos valores, debes hacer lo siguiente:

• Quita los espacios en blanco iniciales y finales.
• Convierte el texto a minúsculas.
• Escribe los números de teléfono con el formato estándar E164.
• Quita todos los puntos (.) que anteceden al nombre de dominio en las direcciones de correo electrónico gmail.com y googlemail.com.

Cuerpo de la entrada en formato JSON

Consulta la documentación de referencia del Protocolo de medición para obtener más información sobre cómo se formatean el transporte y la carga útil.

Enviar datos proporcionados por el usuario

A diferencia de gtag, que genera un hash para los datos sensibles proporcionados por el usuario de forma automática, el Protocolo de medición requiere que un desarrollador genere un hash para esos datos mediante un algoritmo de hash unidireccional seguro llamado SHA256 y lo codifique con un formato de cadena hexadecimal antes de llamar a la API.

Todos los campos de datos del usuario que comiencen con el prefijo sha256 en su nombre solo deben propagarse con valores con codificación hexadecimal y hash.

El siguiente código de ejemplo realiza los pasos necesarios de encriptación y codificación:

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

Como acceso directo útil, se puede pasar un valor singular en lugar de un array a todos los campos repetidos dentro del objeto user_data (como address, sha256_email_address o sha256_phone_number).

El siguiente código de muestra llama al Protocolo de medición y pasa los datos del usuario junto con User-ID.

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

// Populate mock User Data using the `populateSensitiveUserData` function defined
// above.
const yourEmailSha256Variable = await populateSensitiveUserData('[email protected]');
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

De manera opcional, los desarrolladores pueden proporcionar varios valores (hasta 3 para el teléfono y el correo electrónico, y 2 para la dirección) mediante un valor de array en lugar de una cadena. Si capturas más de un valor, proporcionar esta información aumentará las probabilidades de una coincidencia.

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