Añadir PostHog y Clerk a una aplicación nueva implica configurar dos sistemas distintos que resuelven problemas diferentes. Clerk se encarga del inicio de sesión de los usuarios en tu aplicación, mientras que PostHog hace un seguimiento de lo que hacen los usuarios una vez que han accedido a ella. Puedes configurarlos de forma manual en sus dashboards y kits de desarrollo de software (SDK), o aprovisionarlos con Stripe Projects, que extrae las credenciales de ambos proveedores directamente en el archivo .env de tu proyecto sin que tengas que ir de un dashboard a otro.
Más de 500.000 equipos y casi 250.000 ingenieros utilizan PostHog. Muchos equipos acaban combinando PostHog con un proveedor de autenticación, como Clerk. Stripe Projects simplifica esa configuración al aprovisionar ambos servicios en un único flujo de trabajo.
A continuación, explicaremos qué hace cada proveedor, por qué conectar la identidad autenticada con los eventos de análisis te ayuda a entender mucho más que el simple tráfico, y cómo añadir PostHog y Clerk rápidamente usando Stripe Projects.
De un vistazo:
Al conectar los identificadores (ID) de los usuarios autenticados de Clerk con el método
identify()de PostHog, los datos anónimos de la sesión se convierten en perfiles de usuario identificados sin perder el historial de eventos previo al inicio de sesión.Stripe Projects puede aprovisionar PostHog y Clerk a través de comandos de la interfaz de línea de comandos (CLI) que gestionan la autorización de la cuenta y escriben las credenciales directamente en el archivo
.envde tu proyecto.Las prácticas recomendadas para PostHog y Clerk incluyen separar claramente los entornos y minimizar los datos personales en las propiedades de los eventos.
¿Qué son PostHog y Clerk?
PostHog es una plataforma de análisis de productos. Hace un seguimiento de los eventos, las páginas vistas y el comportamiento de los usuarios dentro de una aplicación y, a continuación, convierte esos datos en embudos, grabaciones de sesiones, marcas de funciones y análisis de cohortes. Clerk es un proveedor de autenticación y gestión de usuarios. Gestiona la creación de cuentas, los inicios de sesión, los tokens de sesión, la autenticación multifactor y los datos del perfil del usuario.
¿Por qué deberías combinar los análisis de PostHog con la autenticación de Clerk?
Al combinar PostHog con Clerk obtienes análisis del tráfico de la parte superior del embudo, como la predicción de la tasa de abandono, los análisis de activación o la adopción de funciones, desglosados por nivel de cuenta. PostHog hace el seguimiento de los usuarios a través de un ID distinto, que comienza como un identificador anónimo generado aleatoriamente vinculado a un navegador o dispositivo. Cuando un usuario inicia sesión a través de Clerk, puedes llamar al método identify() de PostHog y pasar el ID de usuario de Clerk como el nuevo ID distinto. A continuación, PostHog fusiona el historial de la sesión anónima con el perfil identificado, y vincula los eventos registrados antes del inicio de sesión (como páginas vistas, clics en botones e interacciones con funciones) a ese usuario.
Presta atención a los siguientes detalles:
Coherencia en los nombres de los eventos: decide desde el principio si los eventos se escribirán en «snake case» (p. ej., sin espacios) o con la primera letra de cada palabra en mayúscula («title case»), y si describen acciones, como
signed\_up, u objetos, comosignup\_completed. Si mezclas diferentes convenciones, tus dashboards de PostHog serán ilegibles.Usuarios anónimos e identificados: si llamas a
identify()en cada carga de página, acumularás eventos de fusión duplicados en el registro de actividad de PostHog. Llámalo una sola vez, justo después de que Clerk confirme una sesión. También puedes restringir la llamada verificando si el usuario ya ha sido identificado en la sesión actual.Privacidad y consentimiento: en las jurisdicciones con requisitos de consentimiento para el seguimiento, como el Reglamento General de Protección de Datos (RGPD) de la UE, obtén el consentimiento antes de identificar a un usuario o adjuntar datos personales a las propiedades de los eventos. Rara vez es necesario incluir un correo electrónico o un nombre en cada evento de análisis, lo cual además amplía tu superficie de cumplimiento de la normativa.
Cuándo conectar ambos: si tu aplicación consta principalmente de páginas de marketing previas a la creación de cuenta, el seguimiento anónimo es suficiente. Conecta los eventos de Clerk y PostHog una vez que tengas flujos autenticados que valga la pena medir, como la conversión de una prueba gratuita a un plan de pago.
¿Cómo se configuran PostHog y Clerk de forma manual?
Configurarás manualmente ambos proveedores en cuatro sistemas: dos dashboards y dos SDK.
Funciona de la siguiente manera:
1. Crear un proyecto de PostHog
Crea tu cuenta en PostHog y crea un proyecto. Así obtendrás una clave de la interfaz de programación de aplicaciones (API) del proyecto y una URL de host. Necesitarás ambos valores para el SDK.
2. Crear una aplicación de Clerk
En el dashboard de Clerk, crea una aplicación y elige tus métodos de inicio de sesión, como el correo electrónico, Google OAuth o claves de acceso.
3. Instalar los SDK
Ejecuta npm install posthog-js y npm install @clerk/nextjs para una aplicación de Next.js. PostHog se inicializa en el lado del cliente a través de posthog.init(), mientras que Clerk envuelve tu aplicación en un \<ClerkProvider\> y requiere middleware para gestionar la protección de rutas.
4. Configurar las variables de entorno
Añade entre cuatro y seis valores a tu archivo .env.local.
5. Probar la configuración
Confirma que el flujo de inicio de sesión de Clerk genera una sesión y, a continuación, comprueba la vista de eventos en directo de PostHog para confirmar que los eventos se reciben correctamente. Verifica que identify() se activa exactamente una vez por sesión, justo después de que se resuelva la autenticación.
¿Cómo puedes explorar proveedores de análisis con Stripe Projects?
Stripe Projects es una función de la CLI de Stripe para aprovisionar servicios de infraestructura de terceros, como bases de datos, análisis y proveedores de inteligencia artificial (IA), directamente desde la línea de comandos. En lugar de abrir dashboards separados para cada servicio, los exploras y aprovisionas desde una única interfaz vinculada a tu proyecto.
Usa Stripe Projects para explorar opciones de proveedores de análisis ejecutándolo desde el directorio de tu proyecto para enumerar los proveedores disponibles, organizados por categoría y nivel de servicio. Puedes limitar la búsqueda con stripe projects catalog \<provider\> o stripe projects catalog \<category\>, o buscar directamente con stripe projects search \<keyword\>. Si buscas específicamente opciones de análisis, verás a PostHog junto con otros proveedores compatibles, lo que elimina la necesidad de salir de tu terminal o cambiar al navegador.
¿Cómo se añaden PostHog y Clerk con Stripe Projects?
Una vez que hayas elegido PostHog y Clerk, necesitas ejecutar dos comandos para aprovisionarlos desde un proyecto ya inicializado con la CLI de Stripe. Para añadir PostHog, ejecuta stripe projects add posthog/analytics para iniciar el flujo de aprovisionamiento. Stripe Projects gestiona el paso de autorización de la cuenta que, normalmente, requeriría que iniciaras sesión en PostHog directamente y copiaras las claves de forma manual. A continuación, escribe la clave API resultante y la URL del host en el archivo .env de tu proyecto. Al ejecutar stripe projects add clerk/auth ocurre lo mismo para Clerk: se gestiona el flujo de autorización y se recuperan las claves publicables y secretas. Esas claves se escriben en el archivo .env junto a lo que acaba de añadir PostHog.
La diferencia práctica entre la configuración con Stripe Projects y la configuración manual es de dónde proceden las credenciales. En lugar de copiar las claves de dos dashboards y pegarlas en .env.local, Stripe Projects las recupera y las escribe directamente, aunque tú (o tu asistente de código) sigues encargándote de escribir el código de inicialización del SDK y de conectar la lógica de tu aplicación.
También querrás mantener tus claves sincronizadas. Si estás configurando el proyecto en un equipo nuevo por primera vez, el comando stripe projects pull \<projectID\> clona el proyecto existente en un directorio vacío y escribe tu archivo .env, que se conecta a los servicios existentes del proyecto en lugar de aprovisionar unos nuevos. Si ya estás en el directorio del proyecto y necesitas actualizar tu archivo .env local después de que alguien de tu equipo haya añadido o rotado un proveedor, ejecuta stripe projects pull env \--pull en su lugar.
¿Cuáles son las prácticas recomendadas para PostHog y Clerk?
Hay un par de cosas que conviene hacer bien antes de implementar esta integración.
Esto es lo que debes tener presente:
Separa claramente los entornos: utiliza distintos proyectos de PostHog y aplicaciones de Clerk para el desarrollo y la producción. Si mezclas registros de prueba con datos reales de los usuarios, tus análisis serán poco fiables y se saturará tu lista de usuarios de Clerk con cuentas desechables.
Nunca expongas la clave secreta de Clerk en el lado del cliente: solo debe estar en las variables de entorno del lado del servidor. La clave publicable es segura para el navegador, pero la clave secreta no.
Minimiza los datos personales en las propiedades de los eventos: envía un ID de usuario en lugar de una dirección de correo electrónico, ya que el ID por sí solo te permite vincular de nuevo los datos a la tabla de usuarios de Clerk más adelante, en caso de necesitarlo.
Respeta el consentimiento antes de identificar a los usuarios: si tu jurisdicción requiere consentimiento para el seguimiento, restringe la llamada a
identify()hasta que lo obtengas.Prueba el comportamiento de la fusión de forma explícita: regístrate como un usuario anónimo, genera algunos eventos y, a continuación, inicia sesión para confirmar que PostHog fusiona ese historial en el perfil identificado en lugar de crear uno nuevo y desconectado.
Documenta tu esquema de eventos: una referencia compartida para los nombres y las propiedades de los eventos evita que distintas partes de tu equipo hagan el seguimiento de la misma acción con tres nombres diferentes.
Cómo puede ayudar Stripe Projects
Stripe Projects permite a los desarrolladores y a sus asistentes de inteligencia artificial añadir servicios, generar credenciales y gestionar la facturación desde la interfaz de línea de comandos (CLI).
Esto es lo que puedes conseguir con Stripe Projects:
Aprovisiona servicios de terceros desde la línea de comandos: utiliza un solo flujo de trabajo para añadir servicios, gestionar credenciales y actualizar planes en lugar de usar herramientas y flujos de trabajo diferentes para cada proveedor. Gestiona el alojamiento, las bases de datos, la autenticación, la IA y muchas cosas más sin necesidad de usar dashboards, archivos de configuración o código de infraestructura.
Sincroniza las credenciales de forma automática: mantén la portabilidad de las variables de entorno entre configuraciones locales, equipos, miembros del equipo y asistentes; sin tener que copiar y pegar claves de la interfaz de programación de aplicaciones (API).
Gestiona la facturación desde la CLI o tu asistente de código: configura los datos de facturación una vez y compártelos de forma segura con servicios de terceros. Sube y baja de nivel, supervisa el consumo y gestiona las suscripciones desde la CLI.
Obtén más información sobre cómo Stripe Projects ayuda a simplificar el aprovisionamiento de las aplicaciones o copia y pega este comando en tu terminal para empezar hoy mismo:
El contenido de este artículo tiene solo fines informativos y educativos generales y no debe interpretarse como asesoramiento legal o fiscal. Stripe no garantiza la exactitud, la integridad, la adecuación o la vigencia de la información incluida en el artículo. Busca un abogado o un asesor fiscal profesional y con licencia para ejercer en tu jurisdicción si necesitas asesoramiento para tu situación particular.