Hash donde no toca: qué campos de user_data llevan SHA-256 en la API de conversiones

Cada evento de la API de conversiones lleva un objeto user_data con la información que Meta usa para relacionar el evento con una persona: email, teléfono, IP, navegador, cookies de Meta. Esa relación importa más de lo que parece: según Meta, solo los eventos emparejados se pueden usar para la atribución y para optimizar la entrega de anuncios. Y no todos los campos se tratan igual. Los datos de contacto deben llegar con hash; otros, tal como son. Mezclar las dos reglas rompe el emparejamiento sin que la API devuelva ningún error.

Cómo se ve un hash mal aplicado

Los eventos llegan y Events Manager los cuenta, pero la calidad de coincidencia de eventos (Event Match Quality, una puntuación sobre 10) es baja aunque la integración envíe muchos parámetros. Al revisar el payload aparece algo así:

• client_ip_address, client_user_agent, fbc o fbp con cadenas hexadecimales de 64 caracteres, el aspecto de un SHA-256, en lugar de una IP, un user agent o un valor fb.1.….
• O al revés: el email o el teléfono en claro, sin hash.
• O con hash, pero sin normalizar: el hash de Ana@Example.com no es el mismo que el de ana@example.com, así que nunca coincide.

Por qué se aplica el hash donde no toca

Meta distingue tres grupos de campos en user_data:

• Hash obligatorio (SHA-256, después de normalizar): email (em), teléfono (ph), nombre (fn), apellido (ln), fecha de nacimiento (db), género (ge), ciudad (ct), provincia o estado (st), código postal (zp) y país (country).
• Hash recomendado: external_id, tu propio identificador del cliente.
• Sin hash: client_ip_address, client_user_agent, fbc, fbp y otros identificadores de Meta. De la IP, la documentación dice expresamente que nunca debe llevar hash.

Los errores aparecen cuando una integración no respeta esa separación:

• Una función que aplica el hash a todo user_data. Es lo más habitual en desarrollos propios y en plantillas de GTM server-side modificadas: el código recorre el objeto y aplica SHA-256 a cada valor, también a la IP o a las cookies.
• Hash sin normalizar. Meta pide normalizar antes: el email sin espacios y en minúsculas; el teléfono solo con dígitos, con el prefijo del país y sin ceros iniciales; el país en código ISO de dos letras en minúsculas.
• Doble hash. La librería o el SDK ya aplica el hash y el código lo vuelve a aplicar antes. Con el Business SDK de Meta, el hash se hace automáticamente.
• Datos de contacto en claro. Meta indica que sus sistemas no aceptan datos de contacto sin hash.

Cómo encontrar campos con el hash equivocado

1. Captura el payload real que sale del servidor: en los logs, en la vista previa de GTM server-side o en la consola de tu integración.
2. Revisa campo a campo: em, ph y el resto de datos de contacto deben ser hashes de 64 caracteres; client_ip_address debe ser una IP válida (IPv4 o IPv6) y fbc y fbp deben empezar por fb..
3. Calcula a mano el SHA-256 de un email de prueba ya normalizado y compáralo con el em enviado. Si no coincide, falta normalizar o hay doble hash.
4. En Events Manager, abre el Overview del píxel y consulta la calidad de coincidencia de eventos de cada evento; al pulsar en la puntuación, Meta muestra detalles y recomendaciones.

Cómo aplicar el hash solo donde corresponde

• Normaliza y aplica SHA-256 solo a los campos con hash obligatorio (y, si lo envías, a external_id).
• Envía client_ip_address, client_user_agent, fbc y fbp tal cual. La IP, la real del usuario, no la del servidor; el user agent es obligatorio en los eventos web.
• Aplica el hash una sola vez. Si usas el Business SDK o una librería que ya lo hace, entrégale los datos normalizados y en claro.
• Si tienes dudas sobre la estructura, la herramienta Payload Helper de Meta muestra cómo debe quedar el payload de un evento.

Documentación de Meta sobre los parámetros de información del cliente y las buenas prácticas de la API de conversiones (en inglés).

Cómo comprobar que el hash es correcto

• En el payload, los datos de contacto son hashes de 64 caracteres y la IP, el user agent, fbc y fbp llegan legibles.
• El hash de un email de prueba calculado a mano coincide con el em enviado.
• En los días siguientes, la calidad de coincidencia de eventos sube. Meta recomienda apuntar a una puntuación de 6,0 o más.

Los hashes y valores del ejemplo son ilustrativos. La IP pertenece a un rango reservado para documentación.