PostHog

Adapty puede enviar eventos de suscripción (compras, renovaciones, reembolsos, inicios de prueba) al flujo de eventos de PostHog, para que se unan al resto de tus datos.

Cada evento incluye datos de ingresos, moneda, store y producto, además del paywall y la variante de prueba A/B que generó la compra. Cualquier herramienta de PostHog puede usar estos datos en cuanto lleguen.

Los eventos de suscripción de Adapty añaden una dimensión de ingresos a todo lo que ya rastreas en PostHog:

• ¿Qué acciones in-app predicen una suscripción? Correlaciona tus propios eventos de PostHog con trial_started y subscription_started para detectar el comportamiento que lleva a las compras.
• ¿Qué variante del experimento generó más ingresos? Usa los eventos de ingresos de Adapty como métrica para un experimento de PostHog sobre cualquier cambio en el producto. Las pruebas A/B de Adapty cubren paywalls y onboardings.
• ¿Qué ocurre antes de un reembolso? Crea un insight sobre subscription_refunded, luego abre los perfiles detrás de él y revisa sus grabaciones de sesión.
• ¿Afectan los errores a las renovaciones? Cruza el seguimiento de errores con subscription_renewal_cancelled, que se dispara en cuanto un usuario desactiva la renovación automática, mucho antes de subscription_expired.
• ¿Cómo retienen los suscriptores en comparación con los usuarios gratuitos? Crea cohortes y curvas de retención basadas en el estado de acceso derivado; consulta Cómo distinguir un suscriptor de un usuario gratuito.
• ¿Qué paywall y variante generaron los ingresos? Los eventos de compra incluyen el paywall y la variante que los originaron, así que puedes desglosar los ingresos por paywall. Registra las vistas de paywall con el SDK de PostHog para medir la tasa de vista-a-compra junto a ellos.
• Haz preguntas cruzando ambos conjuntos de datos con insights o SQL.

Cómo funciona la integración

PostHog identifica a cada usuario mediante una cadena llamada distinct_id. Todo lo relacionado con esta integración depende de que Adapty y PostHog utilicen la misma cadena.

1. El SDK de PostHog asigna al usuario un distinct_id. En el primer lanzamiento, esta cadena es anónima y tiene alcance de dispositivo. Sin embargo, puedes asignarle un valor personalizado al iniciar sesión, o restablecerlo al cerrarla.
2. En cada lanzamiento de la app, después de Adapty.activate() y antes de que pueda producirse cualquier compra, pasa el distinct_id a Adapty con setIntegrationIdentifier(). Adapty adjunta el valor al perfil de Adapty del usuario como posthog_distinct_user_id.
3. Cuando el usuario inicia una prueba o realiza una compra, los servidores de Adapty envían el evento a la API de captura de PostHog con ese distinct_id adjunto. El intercambio ocurre de servidor a servidor, fuera de tu app.
4. PostHog asocia el evento a la persona que tiene ese distinct_id, de modo que los ingresos por suscripción aparecen junto al resto de la actividad del usuario en tu app.

Hacer coincidir el ID de Adapty con el de PostHog

Ambos sistemas deben usar el mismo distinct_id para un usuario; de lo contrario, una misma persona se divide en dos entidades sin conexión. Tienes dos formas de evitar esta fragmentación, y cuál usar depende de cuándo puede producirse una compra.

Si una compra requiere inicio de sesión, llama a identify() de PostHog con tu Customer User ID en el momento en que el usuario inicia sesión. Adapty ya usa ese valor cuando no tiene otro, así que ambos sistemas coinciden.

Si los usuarios anónimos pueden realizar compras, lee el distinct_id de PostHog y pásalo a Adapty con setIntegrationIdentifier. Llámalo en cada inicio después de Adapty.activate(), y de nuevo después de cada reset() de PostHog. Los perfiles anónimos no tienen Customer User ID, por lo que el propio ID de PostHog es el único valor que ambos sistemas pueden compartir — consulta Configura el código de tu app.

Sea cual sea la ruta que elijas, el valor debe sobrevivir a una reinstalación. Adapty crea un nuevo perfil en cada reinstalación, y PostHog un nuevo distinct_id anónimo por dispositivo, por lo que ninguno de los dos sistemas mantiene la identidad a través de esa brecha por sí solo. Adapty sí transfiere el acceso de pago entre los perfiles anónimos de un usuario, pero eso vincula niveles de acceso, no identidad analítica: el perfil que hereda sigue enviando eventos con su propio ID. Sin un ID estable que sea propiedad de tu propio backend, un suscriptor que reinstala la app aparece en PostHog como una persona nueva con una renovación y sin ninguna compra previa.

Los IDs que no coinciden provocan fragmentación de datos — consulta Un usuario aparece como varias personas.

Instrucciones de configuración

Copia el token de tu proyecto de PostHog

1. Inicia sesión en el despliegue que aloja tus datos — US Cloud o EU Cloud — y selecciona el proyecto que quieres conectar.

2. Ve a Settings > Project > General y busca la sección Project token & ID.

   

3. Copia el Project token. Empieza por phc_. PostHog lo describe como de solo escritura y seguro para publicar, por lo que no necesitas rotarlo.

Configurar Adapty

1. Abre Integrations > PostHog en el Adapty Dashboard.

2. Activa el interruptor de PostHog.

3. Pega el token en Project API key. Adapty lo valida contra PostHog al guardar — si el token no es válido, falla de inmediato en lugar de descartar los eventos en silencio.

4. La sección “server location” depende de tu configuración.

• Si utilizas PostHog Cloud, establece la Region según el entorno en el que iniciaste sesión: US Cloud o EU Cloud. Deja el campo PostHog Instance URL vacío.
  • Si utilizas tu propia instancia, selecciona Self-hosted e introduce la URL en el campo PostHog Instance URL. No selecciones ninguna región. Adapty debe poder conectarse a la instancia sin proxy ni VPN.

5. En How the revenue data should be send, elige qué dato de ingresos envía Adapty. Las tres opciones coinciden con las vistas de ingresos de Adapty Analytics, de modo que tu elección también determina la vista con la que deberían coincidir tus cifras en PostHog.

6. Configura las opciones restantes:

7. Cambia el nombre o desactiva eventos individuales en la sección Events names. PostHog acepta cualquier nombre de evento que no esté vacío, así que usa el que encaje con tu taxonomía existente.

8. Haz clic en Save.

Mantén los datos sandbox fuera de producción

Adapty envía transacciones sandbox y de producción a través de la misma integración, por lo que ambas llegan al mismo proyecto de PostHog. La integración utiliza una sola Project API key, sin ninguna clave sandbox separada que apuntar a otro lugar.

Darle a tu build de desarrollo su propio proyecto de PostHog tampoco evitará que los eventos sandbox lleguen al de producción. El sandbox es una propiedad de la transacción del store, no de tu build. Las compras realizadas durante la revisión de App Store y mediante TestFlight son transacciones sandbox procedentes de un build de producción.

En su lugar, sepáralos con consultas. Cada evento incluye una propiedad environment con el valor Sandbox o Production. Filtra por ella para aislar los ingresos reales:

WHERE properties.environment = 'Production'

Configura el código de tu app

1. Solicita al SDK de PostHog el distinct_id actual:

   • En cada inicio de la app, después de Adapty.activate() y antes de que pueda producirse cualquier compra. PostHog atribuye cualquier evento anterior a una persona diferente.
   • Después del reset() de PostHog, que la mayoría de las apps ejecutan al cerrar sesión. reset() genera un nuevo ID anónimo y no lo vincula a la persona anterior, por lo que un valor desactualizado sigue apuntando al usuario que acaba de cerrar sesión.

2. Pásalo a Adapty con setIntegrationIdentifier().

let distinctId = PostHogSDK.shared.getDistinctId()

do {
    try await Adapty.setIntegrationIdentifier(.posthogDistinctUserId(distinctId))
} catch {
    // handle the error
}

Adapty.setIntegrationIdentifier(
    AdaptyIntegrationIdentifier.posthogDistinctUserId(PostHog.distinctId())
) { error ->
    if (error != null) {
        // handle the error
    }
}

Adapty.setIntegrationIdentifier(
    AdaptyIntegrationIdentifier.posthogDistinctUserId(PostHog.distinctId()),
    error -> {
        if (error != null) {
            // handle the error
        }
    }
);

try {
    final distinctId = await Posthog().getDistinctId();

    await Adapty().setIntegrationIdentifier(
        key: "posthog_distinct_user_id",
        value: distinctId,
    );
} on AdaptyError catch (adaptyError) {
    // handle the error
} catch (e) {
    // handle the error
}

const posthog = usePostHog();

try {
    await adapty.setIntegrationIdentifier(
        "posthog_distinct_user_id",
        posthog.getDistinctId()
    );
} catch (error) {
    // handle `AdaptyError`
}

Verificar la integración

1. Realiza una compra en sandbox y abre el Event Feed en el Adapty Dashboard. Cada intento de entrega aparece con su resultado. Adapty verifica tu Project API key y la URL de la instancia al guardar, por lo que los fallos en esta etapa son poco frecuentes. Las causas más habituales:

   • Una clave que dejó de funcionar. PostHog devuelve 401 si eliminas la clave de integración.
   • Una instancia que dejó de responder. Adapty deja de esperar después de 10 segundos. Puede afectar a despliegues autohospedados.

   Pasa el cursor sobre un evento fallido para leer la respuesta de PostHog.

2. En PostHog, abre la vista Activity y busca el evento. La propiedad environment de tu compra debería ser Sandbox.

3. Abre el perfil de esa persona y comprueba la pestaña Distinct IDs. Los eventos propios de tu app y los eventos de servidor de Adapty deberían pertenecer a una misma persona. Si aparecen dos personas para el mismo usuario, significa que los IDs no coinciden — consulta Un usuario aparece como varias personas.

Informar ingresos en PostHog

Adapty Analytics sigue siendo la fuente de verdad para las cifras de ingresos, ya que calcula a partir de los datos completos del store, mientras que PostHog solo recibe lo que esta integración le reenvía. Si también quieres ver los ingresos en un dashboard de PostHog junto a tus métricas de producto, la función Revenue Analytics de PostHog los lee a partir de las propiedades de evento que tú indiques. Abre Data management > Revenue en PostHog y configura:

Deja la opción “values are in cents” de PostHog desactivada. Adapty envía importes en decimal, no en unidades menores.

Estructura de eventos de PostHog

Adapty envía los eventos que hayas habilitado en la sección Events names de la página de integración de PostHog, con una solicitud de captura por evento:

{
  "api_key": "phc_YOUR_PROJECT_TOKEN",
  "distinct_id": "john.doe@example.com",
  "timestamp": "2026-01-08T11:06:12+00:00",
  "event": "subscription_started",
  "properties": {
    "$ip": "10.168.1.1",
    "$geoip_time_zone": "America/New_York",
    "$geoip_disable": true,
    "$set": {
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "birthday": "1990-01-01",
      "gender": "male",
      "os": "iOS"
    },
    "*": "{{other_event_properties}}"
  }
}

Hay cinco propiedades exclusivas de webhooks que nunca aparecen aquí; consulta Limitaciones.

Prioridad del Distinct ID

Adapty utiliza el primer valor que detecta:

Adapty resuelve este orden por evento, no una vez por usuario. Un evento que se dispara antes de que llegue tu llamada a setIntegrationIdentifier queda registrado bajo un ID de menor prioridad, y PostHog crea una segunda persona para el mismo usuario.

Elige una de las dos configuraciones en Vincular el ID de Adapty con el de PostHog y coloca el valor antes de que pueda dispararse cualquier evento. Para los perfiles que ya se han dividido, consulta Un usuario aparece como varias personas.

Propiedades de IP y ubicación

Para segmentar los eventos de Adapty por ubicación, usa las propiedades store_country y profile_country. Adapty desactiva la búsqueda de ubicación de PostHog, por lo que PostHog no añade valores $geoip_* propios. Las tres propiedades que se indican a continuación se aplican por evento, por lo que la configuración de tu proyecto y tus propios eventos no se ven afectados.

Propiedades de persona

Todo lo que hay dentro de $set se convierte en una propiedad de persona en PostHog, en lugar de una propiedad de evento. PostHog asocia las propiedades de persona al usuario en sí, no a un evento concreto, por lo que describen el estado actual del usuario y no un momento puntual en el tiempo. Adapty omite cualquier campo para el que no tenga valor, y elimina $set por completo cuando no hay ninguno.

Limitaciones

• Sin nivel de acceso ni estado de suscripción. El evento access_level_updated es exclusivo de las integraciones de webhook, por lo que Adapty no envía a PostHog ningún campo que describa a qué tiene acceso el usuario actualmente — consulta Cómo distinguir a un suscriptor de un usuario gratuito.
• Sin relleno histórico. Adapty reenvía eventos desde el momento en que habilitas la integración. Las compras anteriores nunca llegan a PostHog.
• PostHog no geolocaliza los eventos de Adapty. PostHog infiere la ubicación a partir de la dirección IP del origen del evento. El origen de los eventos de Adapty es siempre un servidor de Adapty, no el dispositivo del usuario. Para evitar la contaminación de datos, Adapty indica a PostHog que omita la búsqueda. Adapty rellena $geoip_time_zone, store_country y profile_country, pero no datos de ubicación más precisos.
• No puedes filtrar eventos de Adapty por origen. PostHog registra el SDK que envía en $lib — posthog-ios, posthog-android, web — pero Adapty publica directamente en la API de PostHog sin intermediación del SDK, por lo que esa propiedad permanece vacía. Filtra por nombre de evento en su lugar.

Solución de problemas

• Los eventos no aparecen en PostHog
• access_level_updated aparece como fallido en el Event Feed
• Un usuario aparece como varias personas en PostHog
• Los ingresos en PostHog no coinciden con Adapty Analytics
• Los eventos aparecen en PostHog antes de que ocurran
• Sin datos de país o ciudad en los eventos de Adapty
• Cómo distinguir a un suscriptor de un usuario gratuito
• Las vistas de paywall no aparecen en PostHog

Los eventos no aparecen en PostHog

• Primero comprueba el Event Feed de Adapty. Una entrega fallida muestra el error que devolvió PostHog.
• Una entrega exitosa no garantiza que PostHog haya conservado el evento. PostHog responde 200 OK en cuanto el payload y la clave son válidos, pero descarta silenciosamente los eventos que no tienen nombre o tienen un distinct_id vacío.
• Confirma que el evento que buscas está habilitado en la configuración de la integración.
• Si alojas PostHog tú mismo, asegúrate de que el servidor acepta las solicitudes POST de Adapty en /capture. Una configuración correcta no garantiza que este acceso exista: Adapty usa un endpoint diferente para verificar la validez de tu clave.

access_level_updated aparece como fallido en el Event Feed

access_level_updated es un evento exclusivo de webhooks. Adapty nunca lo envía a esta integración. Sin embargo, Adapty registra un resultado para cada integración habilitada, y un evento no compatible se muestra como un error.

Un usuario aparece como varias personas en PostHog

PostHog no puede deshacer la mayoría de las divisiones a posteriori — consulta Hacer coincidir el ID de Adapty con el de PostHog.

Por qué divergen los IDs

Cada evento que Adapty envía incluye un distinct_id del perfil de Adapty del usuario — consulta Prioridad de Distinct ID. Adapty lee ese valor en el momento de enviar el evento, no cuando tu app llama a setIntegrationIdentifier. Si el distinct_id de un evento de Adapty difiere del distinct_id interno del instalado de la app, PostHog atribuye ambos tipos de eventos a dos personas distintas.

Tres situaciones provocan este desajuste:

1. Tu app nunca llama a setIntegrationIdentifier en una de las plataformas. Adapty recurre al Customer User ID o al ID de perfil anónimo. Compruébalo en todas las plataformas en las que publiques.
2. La llamada a setIntegrationIdentifier ocurre demasiado tarde. Los eventos de suscripción que ocurren antes de la llamada llevan el ID de respaldo.
3. El ID que envías a PostHog con identify() difiere del que estableces como identificador de integración. Adapty conserva el valor que pasaste por última vez y nunca lo actualiza por su cuenta. El método reset() de PostHog asigna un nuevo ID anónimo, lo que deja a Adapty con el anterior — así que llama a setIntegrationIdentifier de nuevo después de cada reset().

Corrige los tres problemas y PostHog registrará a una sola persona por usuario a partir de entonces.

Fusiona los IDs de usuario divergentes en la primera llamada a identify()

Tu app tiene una sola oportunidad para reconciliar los IDs divergentes: su primera llamada al método identify() de PostHog. PostHog fusiona los eventos de la instalación de la app con la persona que indiques en esa llamada, así que usa el ID que envía Adapty — consulta Vincula el ID de Adapty con el de PostHog. Tras esa llamada, PostHog considera la instalación de la app como identificada y rechaza fusionar dos personas ya identificadas.

Comprueba si hay una fusión rechazada

Para confirmar que PostHog registró un usuario como dos personas, abre Data management > Ingestion warnings en PostHog y busca el error Refused to merge an already identified user.

PostHog también bloquea las fusiones cuando el ID es uno de sus valores reservados; consulta Hacer coincidir el ID de Adapty con el de PostHog para ver la lista.

Reparar una división existente

Ni identify() ni alias() pueden recuperar una división una vez que la ventana de fusión se ha cerrado. Solo $merge_dangerously de PostHog puede forzar la fusión. PostHog lo documenta como irreversible, sin salvaguardas, y pensado como una recuperación puntual de problemas de implementación.

Se envía como un evento, no como una configuración, y nombra a dos personas. La dirección decide cuál sobrevive:

Decide qué lado sobrevive antes de enviar nada. La persona de Adapty contiene el historial de suscripciones, y la persona de tu app contiene el comportamiento in-app. Prueba con un único usuario y verifica el resultado antes de hacer cualquier reparación masiva. El artículo How to merge users de PostHog incluye el payload para cada uno de sus SDKs.

Los ingresos en PostHog no coinciden con Adapty Analytics

Adapty y PostHog procesan los mismos eventos de forma diferente. Estas diferencias explican prácticamente cualquier discrepancia.

• Cada evento de Adapty incluye tres importes de ingresos, uno por cada opción de Cómo se deben enviar los datos de ingresos. Así se corresponden con las propiedades de PostHog:

Comparar entre filas produce una diferencia igual a la comisión, los impuestos o ambos. Adapty envía las seis propiedades en cada evento, independientemente de cómo esté configurado Report user’s currency.

• Adapty cuenta cada evento de ingresos en un período; un insight de PostHog solo cuenta los eventos que añades. Si omites subscription_renewed, perderás la mayor parte de los ingresos de cualquier app establecida.

• El rango de fechas de Adapty cubre todo el último día; un filtro timestamp se detiene en el instante que le indiques. El rango 1 jul – 15 jul de Adapty incluye todos los eventos hasta el 15 jul a las 23:59:59. En PostHog, timestamp < 2026-07-15 elimina ese día completo — usa timestamp < 2026-07-16.

• Adapty Analytics separa el sandbox de la producción; PostHog los mezcla. Filtra por properties.environment = 'Production' — consulta Mantener los datos de sandbox fuera de producción.

• Adapty usa la zona horaria de informes de tu app; PostHog recibe UTC. Las integraciones siempre reciben marcas de tiempo en UTC, independientemente de lo que configures en App Settings. Una compra a las 23:30 UTC del 1 de julio aparece el 2 de julio en Adapty si tu zona horaria de informes es +02:00, mientras que en PostHog permanece el 1 de julio.

• Faltan eventos históricos en PostHog. Hay dos límites distintos que impiden que los eventos antiguos lleguen, por lo que las suscripciones y renovaciones anteriores solo llegan a Adapty Analytics. Los eventos capturados por tu propio SDK de PostHog no se ven afectados.

• Exclude historical events (Excluir eventos históricos), un interruptor en la página de integración de PostHog, está activado por defecto. Adapty no envía eventos con fecha anterior a la existencia del perfil, y el Event Feed marca cada uno como expirado. Los eventos de Adapty de un usuario comienzan, por tanto, en su primer lanzamiento de una versión con Adapty. Desactívalo para permitir el paso de eventos con fecha retroactiva a partir de ese momento.

  • No historical backfill (Sin relleno histórico) es una limitación permanente. Adapty envía los eventos a medida que los procesa y nunca recupera los eventos que procesó antes de que habilitaras la integración.

• Los eventos que desactivaste en la configuración de la integración nunca llegan a PostHog. Adapty Analytics sigue contándolos. Consulta la sección Events names en Configurar Adapty.

Los eventos aparecen en PostHog antes de que ocurran

Para las renovaciones y conversiones de prueba, Apple notifica a Adapty antes de que ocurra el evento. Adapty reenvía estos eventos de inmediato, con el timestamp futuro sin cambios. Adapty Analytics los retiene hasta que ese momento llegue, por lo que PostHog muestra eventos que Adapty aún no ha reportado. Ambos son correctos. Filtra por timestamp para excluirlos; consulta Timestamps de eventos con fechas futuras.

Sin datos de país o ciudad en los eventos de Adapty

Usa en su lugar las propiedades store_country y profile_country. Los valores $geoip_* propios de PostHog se quedan vacíos en los eventos de Adapty — consulta Propiedades de IP y ubicación.

Cómo distinguir a un suscriptor de un usuario gratuito

Los informes de eventos de Adapty no muestran el acceso actual del usuario. $set incluye únicamente email, first_name, last_name, birthday, gender y os. Las propiedades de evento que describen los niveles de acceso solo se rellenan en access_level_updated, y Adapty comparte ese evento exclusivamente con la integración de webhook.

Hay dos opciones:

• Deriva el estado en PostHog a partir del historial de eventos. Un usuario cuyo evento más reciente de Adapty sea subscription_started, subscription_renewed o trial_converted tiene acceso actualmente; uno cuyo evento más reciente sea subscription_expired, trial_expired o subscription_refunded no lo tiene.
• Usa la integración de webhooks para recibir access_level_updated y reenvíalo a PostHog por tu cuenta. La API de captura de PostHog espera su propio formato de payload, por lo que necesitarás un paso de transformación de tu parte: el payload del webhook de Adapty no se puede enviar directamente a PostHog sin modificaciones.

Las vistas de paywall no aparecen en PostHog

El SDK de Adapty captura las interacciones con paywall, flow y onboarding únicamente para Adapty Analytics. El servidor de Adapty reenvía los eventos de suscripción a las integraciones, pero estas interacciones no son eventos de suscripción. Los webhooks tampoco las incluyen. Captúralas con el SDK de PostHog en el lugar donde muestres el paywall.