Esta guía está basada en una implementación real que llevamos a cabo para un cliente del sector financiero. Cubre cada decisión técnica que nos encontramos en el camino — para que vos no tengas que aprenderlas por las malas. Usaremos el JavaScript (Browser) SDK, el punto de entrada más común para aplicaciones web.
1. Instalar el SDK de JavaScript
La forma más rápida de arrancar es el método de snippet: pegá el script loader de Mixpanel dentro del <head> de tu HTML, justo antes del cierre del tag </head>. Esto carga el SDK de forma asíncrona desde el CDN de Mixpanel, sin bloquear el render de la página.
/* Pegar dentro de — antes de */
Alternativa con npm: si usás un framework moderno (React, Vue, Angular), instalá con npm install mixpanel-browser e importalo en el entry point de tu app. La API es idéntica.
2. Configurar el SDK correctamente
Inmediatamente después del snippet (todavía dentro de <head>), inicializá Mixpanel con tu token de proyecto y un objeto de configuración:
mixpanel.init("YOUR_TOKEN", {
track_pageview: false, // false: trackear pageviews manualmente
persistence: "localStorage",
debug: false // true durante desarrollo
});Para encontrar tu Project Token andá a Settings → Project Settings y scrolleá hasta el campo Project Token.
⚡ Mejor práctica: creá dos proyectos — uno de QA y uno de Producción. Durante el desarrollo apuntá el token a QA; migrá a Producción solo después de validar todos los eventos en tu Tracking Plan. Esto evita contaminar los datos reales con ruido de pruebas.
3. Trackear eventos y propiedades de evento
Todo en Mixpanel gira en torno a los eventos — acciones discretas que un usuario realiza en tu producto. Se trackean con mixpanel.track().
// Evento básico
mixpanel.track("Signed Up");
// Evento con propiedades (siempre agregá contexto)
mixpanel.track("Played Song", {
genre: "hip-hop",
duration: 187,
premium: true
});
// Page view manual
mixpanel.track_pageview({ page: "Pricing" });💡 Convención de nombres: usá Title Case para eventos ("Clicked CTA") y snake_case para propiedades (plan_type, button_label). Elegí una convención y mantenela en todo el Tracking Plan.
4. Propiedades de evento registradas por default
El SDK de JavaScript adjunta automáticamente propiedades útiles a todos los eventos sin que escribas una línea extra: $browser, $device, $current_url, $screen_height, $screen_width, $os, $referrer, mp_country_code, entre otros.
⚠️ Algunos nombres de propiedades están reservados por Mixpanel para procesamientos especiales (ej: $email, $name, $created). Evitá usarlos como propiedades personalizadas a menos que quieras ese comportamiento especial.
5. Tracking automático de parámetros UTM
No necesitás escribir código extra para los UTM. Cuando el SDK se inicializa, lee utm_source, utm_medium, utm_campaign, utm_content y utm_term de la URL y los adjunta automáticamente al primer evento de esa sesión.
Estos valores UTM también se persisten como Super Properties, así que viajan con los eventos subsiguientes de la sesión — dándote datos de atribución a lo largo de todo el journey del usuario, no solo del hit de la landing page.
6. Identificación de usuarios: Simplified ID Management
Implementar bien el ID Management es la parte más importante de toda la implementación de Mixpanel. Hacerlo mal genera usuarios duplicados, funnels rotos y sesiones desconectadas entre dominios.
El Simplified ID Management maneja tres tipos de IDs: el device_id (generado automáticamente al primera visita, identifica sesiones anónimas), el user_id (tu identificador interno de app, pasado a Mixpanel al hacer login/signup), y el distinct_id (el identificador canónico de Mixpanel — igual al device_id antes del login, igual al user_id después).
El journey del usuario paso a paso
1. Primera visita (anónimo): SDK se inicializa → genera device_id = $device:abc → distinct_id = device_id → se almacena en localStorage/cookie.
2. El usuario navega y genera eventos: todos se registran bajo el distinct_id anónimo.
3. El usuario hace Sign Up / Log In: llamás a mixpanel.identify("user_id") → el historial anónimo se fusiona con el perfil identificado → distinct_id = user_id.
4. El usuario hace Logout: llamás a mixpanel.reset() → genera un nuevo device_id anónimo fresco, evitando que otra persona que use el mismo dispositivo herede la sesión.
// Identificar al usuario en login / signup
mixpanel.identify("usr_98765");
// CRÍTICO: reset en logout
// Evita que el próximo usuario en el mismo dispositivo
// herede esta sesión.
mixpanel.reset();🚨 Nunca uses PII como user ID. No pases emails, teléfonos ni documentos directamente a identify(). Usá un ID interno hasheado. Esto mantiene tus datos en cumplimiento con GDPR y protege a tus usuarios.
7. Trackear User Properties (Propiedades de Usuario)
Mixpanel te permite construir un perfil de usuario rico — atributos persistentes que describen quién es el usuario, no solo qué hizo. Podés filtrar cualquier reporte por estas propiedades.
// Setear propiedades de usuario
mixpanel.people.set({
plan: "pro",
cuenta_ahorro: true,
credito_activo: false,
pais: "BO"
});
// set_once — solo escribe si la propiedad no existe todavía.
// Ideal para "Fecha de primer login", "Fuente de signup", etc.
mixpanel.people.set_once({
fecha_primer_login: new Date().toISOString()
});💡 Las propiedades de usuario solo son útiles después de que mixpanel.identify() fue llamado. Siempre identificá primero, después seteá propiedades.
8. Cross-Domain Tracking: cómo manejar cambios de dominio
Esta es la parte más compleja de la mayoría de las implementaciones. Cuando un usuario navega de dominio-a.com a dominio-b.com, el browser crea un nuevo scope de localStorage/cookie para el segundo dominio. Mixpanel lo ve como un usuario anónimo nuevo — rompiendo tu funnel por completo.
La solución es llevar la información de identidad en la URL como query params y re-inicializar Mixpanel en el segundo dominio.
// En el Dominio 1: construir la URL de handoff
const deviceId = mixpanel.get_distinct_id();
const userId = mixpanel.get_property("$user_id");
let destination = "https://dominio-b.com/home";
destination += `?device_id=${encodeURIComponent(deviceId)}`;
if (userId) {
destination += `&$user_id=${encodeURIComponent(userId)}`;
}
window.location.href = destination;// En el Dominio 2: rehidratar la sesión
// CRÍTICO: ejecutar INMEDIATAMENTE después de mixpanel.init()
// y ANTES de cualquier mixpanel.track()
const params = new URLSearchParams(window.location.search);
const prevDistId = params.get("device_id");
const userId = params.get("$user_id");
if (prevDistId) {
if (userId) {
mixpanel.register({ "$device_id": prevDistId.replace("$device:", "") });
mixpanel.identify(userId);
} else {
mixpanel.register({
"distinct_id": prevDistId,
"$device_id": prevDistId.replace("$device:", "")
});
}
}⚠️ Sub-dominios están bien. Moverse entre app.ejemplo.com y blog.ejemplo.com no requiere este patrón — Mixpanel comparte la cookie entre sub-dominios automáticamente. Esta técnica solo es necesaria cuando cambia el dominio raíz.
9. Tracking Server Side
El tracking desde el browser es conveniente pero con pérdidas: ad-blockers, configuraciones de privacidad agresivas y errores de scripts pueden silenciosamente perder eventos. Para acciones críticas del negocio (compras, registros, resets de contraseña), el tracking server-side garantiza la entrega.
Mixpanel tiene SDKs oficiales para Node.js, Python, Ruby, PHP, Go y Java. Si ninguno encaja con tu stack, usá el endpoint de Ingestion API /import — acepta batches de JSON sobre HTTPS y es agnóstico al lenguaje.
// Ejemplo Node.js (npm install mixpanel)
const Mixpanel = require("mixpanel");
const mp = Mixpanel.init("YOUR_TOKEN");
mp.track("Purchase Completed", {
distinct_id: "usr_98765",
amount: 199.00,
currency: "USD",
plan: "pro"
});10. Super Properties
Las Super Properties son propiedades de evento que se adjuntan automáticamente a todos los eventos que disparás — sin pasarlas manualmente en cada track(). Se persisten en la cookie/localStorage de Mixpanel.
Casos de uso clásicos: nombre del producto (product: "24 Online"), segmento de usuario (user_tier: "premium"), versión de la app (app_version: "4.2.1"), entorno (env: "production").
// Registrar Super Properties — una vez en la inicialización
mixpanel.register({
product: "24 Online",
platform: "web",
app_version: "4.2.1"
});
// register_once — solo setea si la propiedad no existe
mixpanel.register_once({
fecha_primera_visita: new Date().toISOString()
});
// Remover cuando ya no es relevante
mixpanel.unregister("flag_campana_temporal");11. Firewall y Ad-Blockers
Si tus usuarios están detrás de un firewall corporativo, las requests a *.mixpanel.com o al CDN en cdn.mxpnl.com pueden ser bloqueadas silenciosamente. Tus opciones:
Opción 1 — Whitelist: agregá *.mixpanel.com y cdn.mxpnl.com a la lista blanca del firewall. Rápido de deployar, pero requiere aprobación de IT.
Opción 2 — Proxy propio: configurá un servidor proxy en tu dominio (ej: analytics.tudominio.com) que reenvíe las requests al endpoint de ingesta de Mixpanel. Esto también elimina la mayoría de los ad-blockers y se configura con la opción api_host en mixpanel.init().
Opción 3 — Server-side: usá tracking server-side para eventos críticos (ver punto 9). Los eventos se originan en tu backend, sin restricciones del browser.
12. Privacidad: Opt-Out y Cookies Seguras
Cuando un usuario retira su consentimiento de tracking, llamá a mixpanel.opt_out_tracking(). Para re-habilitarlo: mixpanel.opt_in_tracking(). Conectá esto con tu banner de cookies — cuando el usuario hace clic en "Rechazar todo", llamá a opt_out antes de que se dispare cualquier track().
mixpanel.opt_out_tracking();
// Re-habilitar si el usuario luego da su consentimiento
mixpanel.opt_in_tracking();
// Verificar estado
if (mixpanel.has_opted_out_tracking()) {
console.log("Usuario optó por no ser trackeado.");
}
// Forzar cookies solo por HTTPS (requerido para PCI/DSS)
mixpanel.set_config({ secure_cookie: true });Checklist de implementación
✅ Snippet del SDK instalado antes de </head> | ✅ Dos proyectos: QA y Producción | ✅ track_pageview: false | ✅ Tracking Plan definido | ✅ identify() en login/signup | ✅ reset() en logout | ✅ Cross-domain handoff implementado (si aplica) | ✅ Tracking server-side para conversiones críticas | ✅ Opt-out integrado en el banner de cookies | ✅ secure_cookie: true | ✅ QA completo con Mixpanel Live View.
¿Necesitás ayuda implementando Mixpanel en tu producto? En Bildung Data ayudamos a equipos de producto e ingeniería a implementar stacks de analytics limpios y escalables — desde el diseño del Tracking Plan hasta la implementación completa del SDK y la construcción de dashboards. Hablemos →