Agrega PostHog a una nueva aplicación: Cómo preparar y configurar PostHog y Clerk

Projects

Agrega servicios, genera credenciales y gestiona la facturación desde la CLI, o deja que tu agente lo haga.

Más información 
  1. Introducción
  2. Conclusiones principales
  3. ¿Qué son PostHog y Clerk?
  4. ¿Por qué conviene combinar los análisis de PostHog con la autenticación de Clerk?
  5. Cómo configurar PostHog y Clerk de forma manual
    1. 1. Crear un proyecto de PostHog
    2. 2. Crear una aplicación de Clerk
    3. 3. Instalar los SDK
    4. 4. Configurar las variables de entorno
    5. 5. Probar la configuración
  6. Cómo explorar los proveedores de análisis con Stripe Projects
  7. Cómo agregar PostHog y Clerk con Stripe Projects
  8. ¿Cuáles son las prácticas recomendadas para PostHog y Clerk?
  9. Cómo puede ayudar Stripe Projects

Agregar PostHog y Clerk a una aplicación nueva implica configurar dos sistemas diferentes que resuelven problemas distintos. Clerk se encarga del inicio de sesión de los usuarios en tu aplicación, mientras que PostHog rastrea lo que hacen los usuarios una vez que ingresan. Puedes configurarlos de forma manual a través de 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 alternar entre Dashboards.

Más de 500,000 equipos y casi 250,000 ingenieros usan PostHog. Muchos equipos eventualmente combinan PostHog con un proveedor de autenticación, como Clerk. Stripe Projects simplifica esa configuración al aprovisionar ambos servicios en un solo flujo de trabajo.

A continuación, analizaremos qué hace cada proveedor, por qué conectar la identidad autenticada a los eventos de análisis te ayuda a comprender más que solo el tráfico y cómo agregar PostHog y Clerk rápidamente usando Stripe Projects.

Conclusiones principales

  • Al conectar los identificadores de usuario (ID) autenticados de Clerk con el método identify() de PostHog, los datos de sesión anónimos 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 mediante comandos de la interfaz de línea de comandos (CLI) que manejan la autorización de la cuenta y escriben las credenciales directamente en el archivo .env de tu proyecto.

  • Las prácticas recomendadas para PostHog y Clerk incluyen separar los entornos de forma limpia 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. Rastrea eventos, visitas a páginas y el comportamiento de los usuarios dentro de una aplicación; luego, convierte esos datos en embudos, grabaciones de sesiones, marcas de funcionalidades y análisis de cohortes. Clerk es un proveedor de autenticación y gestión de usuarios. Se encarga de la creación de cuentas, el inicio de sesión, los tokens de sesión, la autenticación multifactor y los datos de perfil de usuario.

¿Por qué conviene combinar los análisis de PostHog con la autenticación de Clerk?

Combinar PostHog con Clerk te brinda análisis sobre el tráfico de la parte superior del embudo, como la predicción de abandonos, los análisis de onboarding o la adopción de funcionalidades, desglosados por nivel de cuenta. PostHog hace un seguimiento de los usuarios a través de un ID distinto, que comienza como un identificador anónimo generado aleatoriamente y 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 sesión anónima con el perfil identificado, lo que vincula los eventos rastreados antes del inicio de sesión — como visitas a páginas, clics en botones e interacciones con funcionalidades — a ese usuario.

Presta mucha atención a estos detalles:

  • Coherencia en la nomenclatura de los eventos: Decide desde el principio si los eventos se escribirán en «snake case» (p. ej., sin espacios) o en mayúsculas y minúsculas (title case), y si describen acciones como signed\_up u objetos como signup\_completed. Mezclar convenciones hace que tus Dashboards de PostHog sean ilegibles.

  • Usuarios anónimos frente a 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 vez, justo después de que Clerk confirme una sesión. También puedes restringir la llamada y condicionarla a la verificación de si el usuario ya se identificó en la sesión actual.

  • Privacidad y consentimiento: En jurisdicciones con requisitos de consentimiento para el rastreo, como en el marco del Reglamento General de Protección de Datos (RGPD) en 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, y esto amplía tu superficie de cumplimiento de la normativa.

  • Cuándo conectar los dos: Si tu aplicación consta principalmente de páginas de marketing previas a la creación de una cuenta, el rastreo 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 versión de prueba a una de pago.

Cómo configurar PostHog y Clerk de forma manual

Configurarás ambos proveedores de forma manual en cuatro sistemas: dos Dashboards y dos SDK.

Funciona de la siguiente manera:

1. Crear un proyecto de PostHog

Crea una cuenta en PostHog y crea un proyecto. Esto te proporcionará una clave de 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 Next.js. PostHog se inicializa en el lado del cliente mediante posthog.init(), mientras que Clerk envuelve tu aplicación en un \<ClerkProvider\> y requiere middleware para manejar la protección de rutas.

4. Configurar las variables de entorno

Agrega de cuatro a seis valores a tu archivo .env.local.

5. Probar la configuración

Confirma que el flujo de inicio de sesión de Clerk produce una sesión y, luego, verifica la vista de eventos en vivo de PostHog para confirmar que los eventos estén llegando. Comprueba que identify() se active exactamente una vez por sesión, justo después de que se resuelva la autenticación.

Cómo explorar los proveedores de análisis con Stripe Projects

Stripe Projects es una funcionalidad de la CLI de Stripe para aprovisionar servicios de infraestructura de terceros, lo que incluye 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, puedes explorarlos y aprovisionarlos desde una interfaz vinculada a tu proyecto.

Usa Stripe Projects para explorar las 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 delimitar la búsqueda con stripe projects catalog \<provider\> o stripe projects catalog \<category\>, o bien buscar directamente con stripe projects search \<keyword\>. Si buscas análisis en específico, verás PostHog junto a otros proveedores compatibles, lo que elimina la necesidad de abandonar tu terminal o cambiar a un navegador.

Cómo agregar PostHog y Clerk con Stripe Projects

Una vez que hayas elegido PostHog y Clerk, se necesitan dos comandos para aprovisionar ambos desde un proyecto ya inicializado con la CLI de Stripe. Para agregar PostHog, ejecuta stripe projects add posthog/analytics para iniciar el flujo de aprovisionamiento. Stripe Projects maneja el paso de autorización de la cuenta que normalmente requeriría que inicies sesión en PostHog directamente y copies las claves de forma manual. Luego, escribe la clave API resultante y la URL del host en el archivo .env de tu proyecto. Ejecutar stripe projects add clerk/auth hace lo mismo para Clerk: administra el flujo de autorización y recupera las claves publicables y secretas. Estas se escriben en el archivo .env junto con lo que acaba de agregar PostHog.

La diferencia práctica entre la configuración con Stripe Projects y la configuración manual radica en de dónde provienen las credenciales. En lugar de copiar claves de dos Dashboards y pegarlas en el archivo .env.local, Stripe Projects las recupera y escribe directamente, aunque tú (o tu agente de programación) aún tengan que escribir el código de inicialización del SDK y configurar la lógica de tu aplicación por su cuenta.

También querrás mantener tus claves sincronizadas. Si estás configurando el proyecto en una máquina nueva por primera vez, 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 otros nuevos. Si ya estás en el directorio del proyecto y necesitas actualizar tu archivo .env local después de que un compañero de equipo agregue o rote un proveedor, ejecuta stripe projects pull env \--pull en su lugar.

¿Cuáles son las prácticas recomendadas para PostHog y Clerk?

Vale la pena hacer bien algunas cosas antes de lanzar esta integración.

Esto es lo que debes tener en cuenta:

  • Separa los entornos de forma limpia: Usa proyectos de PostHog y aplicaciones de Clerk diferentes para desarrollo y producción. Mezclar las creaciones de cuentas de prueba con datos de usuarios reales hace que tus análisis no sean fiables y llena tu lista de usuarios de Clerk con cuentas temporales.

  • Nunca expongas la clave secreta de Clerk del lado del cliente: Solo pertenece a las variables de entorno del lado del servidor. La clave publicable es segura para el navegador; la clave secreta no lo es.

  • 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 volver a unir los datos a la tabla de usuarios de Clerk más adelante si lo necesitas.

  • Respeta el consentimiento antes de identificar a los usuarios: Si tu jurisdicción requiere el consentimiento de rastreo, condiciona la llamada a identify() a ese consentimiento.

  • Prueba el comportamiento de fusión de manera explícita: Crea una cuenta como usuario anónimo, genera algunos eventos, luego inicia sesión y confirma que PostHog fusione ese historial en el perfil identificado en lugar de comenzar uno nuevo 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 rastreen la misma acción con tres nombres diferentes.

Cómo puede ayudar Stripe Projects

Stripe Projects permite a los desarrolladores y a sus agentes de IA agregar servicios, generar credenciales y gestionar la facturación desde la interfaz de línea de comandos (CLI).

Stripe Projects te ayuda a hacer lo siguiente:

  • Aprovisionar servicios de terceros desde la línea de comandos: Usa un solo flujo de trabajo para agregar servicios, gestionar credenciales y actualizar planes, en lugar de usar herramientas y flujos de trabajo diferentes para cada proveedor. Administra el alojamiento, las bases de datos, la autenticación, la IA y más sin necesidad de usar Dashboards, archivos de configuración ni código de infraestructura.

  • Sincronizar credenciales de forma automática: Mantén las variables de entorno portátiles en configuraciones locales, máquinas, compañeros de equipo y agentes — sin tener que copiar y pegar claves de interfaz de programación de aplicaciones (API).

  • Gestionar la facturación desde la CLI o tu agente de programación: Configura los detalles de facturación una sola vez y compártelos de forma segura con servicios de terceros. Sube y baja de nivel, monitorea el consumo y administra las suscripciones desde la CLI.

Obtén más información sobre cómo Stripe Projects ayuda a simplificar el aprovisionamiento de aplicaciones, o bien 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, adecuación o vigencia de la información incluida en el artículo. Si necesitas asistencia para tu situación particular, te recomendamos consultar a un abogado o un contador competente con licencia para ejercer en tu jurisdicción.

Más artículos

  • Hubo un problema. Vuelve a intentarlo o comunícate con soporte.

¿Todo listo para empezar?

Crea una cuenta y empieza a aceptar pagos sin necesidad de firmar contratos ni proporcionar datos bancarios. Si lo prefieres, puedes ponerte en contacto con nosotros para que diseñemos un paquete personalizado para tu empresa.
Payments

Payments

Acepta pagos en línea y en persona desde cualquier parte del mundo con una solución de pagos diseñada para todo tipo de negocios.

Documentación de Payments

Encuentra una guía para integrar las API de pagos de Stripe.