Tipos de eventos y campos de webhook
Adapty envía webhooks en respuesta a eventos de suscripción. Esta sección define los tipos de eventos y los datos que contiene cada webhook.
Tipos de eventos de webhook
Puedes enviar todos los tipos de eventos a tu webhook o elegir solo algunos. Consulta nuestros Flujos de eventos para saber qué tipo de datos entrantes esperar y cómo construir tu lógica de negocio en torno a ellos. Puedes desactivar los tipos de eventos que no necesites cuando configures tu integración de Webhook. También puedes reemplazar los IDs de eventos predeterminados de Adapty por los tuyos propios si es necesario.
| Nombre del evento | Descripción |
|---|---|
| subscription_started | Se activa cuando un usuario activa una suscripción de pago sin período de prueba, es decir, se le cobra de inmediato. |
| subscription_active | Confirma que la suscripción sigue activa después del evento subscription_started. Debes definir cuántos días transcurren entre el inicio de la suscripción y esta comprobación. El evento llega si la suscripción sigue activa, incluido el caso en que el usuario haya entrado en un período de gracia. Si la suscripción terminó o el usuario desactivó la renovación automática, no llega nada y Adapty no vuelve a comprobar. Este evento solo sigue a suscripciones compradas sin prueba. Una prueba que se convierte envía trial_converted, que no inicia la comprobación. |
| subscription_renewed | Ocurre cuando se renueva una suscripción y se cobra al usuario. Este evento comienza a partir de la segunda facturación, ya sea una suscripción con o sin período de prueba. |
| subscription_renewal_cancelled | Un usuario ha desactivado la renovación automática de la suscripción. El usuario conserva el acceso a las funciones premium hasta el final del período de suscripción de pago. |
| subscription_renewal_reactivated | Se activa cuando un usuario reactiva la renovación automática de la suscripción. |
| subscription_expired | Se activa cuando una suscripción termina definitivamente tras ser cancelada. Por ejemplo, si un usuario cancela una suscripción el 12 de diciembre pero esta permanece activa hasta el 31 de diciembre, el evento se registra el 31 de diciembre cuando expira. |
| subscription_paused | Ocurre cuando un usuario activa la pausa de suscripción (solo Android). |
| subscription_deferred | Se activa cuando extiendes la suscripción de un usuario sin coste: mediante un aplazamiento a través de la API de Google Play Developer, o una extensión de fecha de renovación a través de la App Store Server API. El usuario conserva el acceso a las funciones premium hasta la fecha de renovación extendida. |
| non_subscription_purchase | Cualquier compra que no sea una suscripción, como acceso de por vida o productos consumibles como monedas del juego. |
| trial_started | Se activa cuando un usuario activa una suscripción de prueba. |
| trial_active | Confirma que la prueba sigue activa después del evento trial_started. Debes definir cuántos días transcurren entre el inicio de la prueba y esta comprobación. El evento llega si la prueba sigue en curso. Si la prueba terminó, se convirtió o el usuario desactivó la renovación automática, no llega nada y Adapty no vuelve a comprobar. |
| trial_converted | Ocurre cuando finaliza una prueba y se cobra al usuario (primera compra). Por ejemplo, si un usuario tiene una prueba hasta el 14 de enero pero se le cobra el 7 de enero, este evento se registra el 7 de enero. |
| trial_renewal_cancelled | Un usuario desactivó la renovación automática de la suscripción durante el período de prueba. El usuario conserva el acceso a las funciones premium hasta que finalice la prueba, pero no se le cobrará ni iniciará una suscripción. |
| trial_renewal_reactivated | Ocurre cuando un usuario reactiva la renovación automática de la suscripción durante el período de prueba. |
| trial_expired | Se activa cuando una prueba termina sin convertirse en suscripción. |
| entered_grace_period | Ocurre cuando falla un intento de pago y el usuario entra en un período de gracia (si está habilitado). El usuario conserva el acceso premium durante este tiempo. |
| billing_issue_detected | Se activa cuando ocurre un problema de facturación durante un intento de cobro (por ejemplo, saldo insuficiente en la tarjeta). |
| subscription_refunded | Se activa cuando se reembolsa una suscripción (por ejemplo, por parte del soporte de Apple). |
| non_subscription_purchase_refunded | Se activa cuando se reembolsa una compra que no es una suscripción. |
| access_level_updated | Ocurre cuando se actualiza el nivel de acceso de un usuario. |
subscription_renewal_reactivated lleva el ID del producto anterior — el que estaba activo cuando el usuario canceló — incluso si el usuario reactivó la suscripción comprando un producto diferente. Apple mantiene el mismo original_transaction_id a lo largo de la cadena cancelación → reactivación, por lo que este evento refleja el producto original. El nuevo producto aparece en el siguiente evento subscription_renewed, cuando comienza la facturación del nuevo producto.
En Google Play, Adapty puede enviar un evento subscription_started con todos los campos monetarios establecidos en cero — por ejemplo, cuando Google reemplaza una suscripción por otra o cuando la suscripción comienza con una fase sin cargo. No contabilices estos eventos como ingresos. Cuando Google reemplaza una suscripción, emite un nuevo token de compra, por lo que Adapty reporta la transacción pagada bajo un store_transaction_id diferente.
Estructura de los eventos de webhook
Adapty solo te enviará los eventos que hayas seleccionado en la sección Events names de la página Integrations -> Webhooks.
Los eventos del webhook se serializan en JSON. El cuerpo de la solicitud POST enviada a tu servidor contendrá el evento serializado dentro de la estructura que se muestra a continuación. Todos los eventos siguen la misma estructura, aunque sus campos varían según el tipo de evento, el store y tu configuración específica. Los atributos de usuario son los atributos de usuario personalizados que hayas configurado, por lo que contienen lo que tú hayas definido. Los campos de datos de atribución también son iguales para todos los tipos de eventos; sin embargo, la lista de atribuciones dependerá de las fuentes de atribución que uses en tu app. A continuación puedes ver un ejemplo de evento:
{
"profile_id": "00000000-0000-0000-0000-000000000000",
"customer_user_id": "UserIdInYourSystem",
"idfv": "00000000-0000-0000-0000-000000000000",
"idfa": "00000000-0000-0000-0000-000000000000",
"advertising_id": "00000000-0000-0000-0000-000000000000",
"profile_install_datetime": "2000-01-31T00:00:00.000000+0000",
"user_agent": "ExampleUserAgent/1.0 (Device; OS Version) Browser/Engine",
"email": "john.doe@company.com",
"event_type": "subscription_started",
"event_datetime": "2000-01-31T00:00:00.000000+0000",
"event_properties": {
"store": "play_store",
"currency": "USD",
"price_usd": 4.99,
"profile_id": "00000000-0000-0000-0000-000000000000",
"cohort_name": "All Users",
"environment": "Production",
"price_local": 4.99,
"original_price_usd": 4.99,
"original_price_local": 4.99,
"discount_amount_usd": 0,
"discount_amount_local": 0,
"base_plan_id": "b1",
"developer_id": "onboarding_placement",
"ab_test_id": "00000000-0000-0000-0000-000000000000",
"ab_test_name": "onboarding_ab_test",
"ab_test_revision": 1,
"ab_test_variant_id": "00000000-0000-0000-0000-000000000000",
"ab_test_variant_name": "Variant B",
"paywall_name": "UsedPaywall",
"proceeds_usd": 4.2315,
"variation_id": "00000000-0000-0000-0000-000000000000",
"purchase_date": "2024-11-15T10:45:36.181000+0000",
"store_country": "AR",
"event_datetime": "2000-01-31T00:00:00.000000+0000",
"proceeds_local": 4.2415,
"tax_amount_usd": 0,
"transaction_id": "0000000000000000",
"net_revenue_usd": 4.2415,
"profile_country": "AR",
"paywall_revision": "1",
"profile_event_id": "00000000-0000-0000-0000-000000000000",
"tax_amount_local": 0,
"net_revenue_local": 4.2415,
"vendor_product_id": "onemonth_no_trial",
"profile_ip_address": "10.10.1.1",
"consecutive_payments": 1,
"rate_after_first_year": false,
"original_purchase_date": "2000-01-31T00:00:00.000000+0000",
"original_transaction_id": "0000000000000000",
"subscription_expires_at": "2000-01-31T00:00:00.000000+0000",
"profile_has_access_level": true,
"profile_total_revenue_usd": 4.99,
"promotional_offer_id": null,
"store_offer_category": null,
"store_offer_discount_type": null
},
"event_api_version": 1,
"profiles_sharing_access_level": [{"profile_id": "00000000-0000-0000-0000-000000000000", "customer_user_id": "UserIdInYourSystem"}],
"attributions": {
"appsflyer": {
"ad_set": "Keywords 1.12",
"status": "non_organic",
"channel": "Google Ads",
"ad_group": null,
"campaign": "Social media influencers - Rest of the world",
"creative": null,
"created_at": "2000-01-31T00:00:00.000000+0000"
}
},
"user_attributes": {"Favourite_color": "Violet", "Pet_name": "Fluffy"},
"integration_ids": {"firebase_app_instance_id": "val1", "branch_id": "val2", "one_signal_player_id": "val3"},
"play_store_purchase_token": {
"product_id": "product_123",
"purchase_token": "token_abc_123",
"is_subscription": true
}
}
Campos del evento
Los parámetros de evento son los mismos para todos los tipos de evento.
| Campo | Tipo | Descripción |
|---|---|---|
| advertising_id | UUID | ID de publicidad (solo Android). |
| attributions | JSON | Datos de atribución. Se incluye si Send Attribution está habilitado en los ajustes del Webhook. |
| customer_user_id | String | ID de usuario de tu app (UUID, email u otro ID) si lo has definido en el código de tu app al identificar usuarios. Si no identificas usuarios en el código de la app o este usuario en concreto es anónimo (no ha iniciado sesión), este campo es null. |
| String | Email del usuario si lo has definido mediante el método updateProfile del SDK de Adapty o al crear/actualizar perfiles a través de la API del servidor. Si no pasas el valor email al SDK o al método de la API, este campo es null. | |
| event_api_version | Integer | Versión de la API de Adapty (actual: 1). |
| event_datetime | ISO 8601 | La hora efectiva (de negocio) del evento, como la fecha de compra para una compra o la fecha de expiración para una expiración — no cuando Adapty recibió o envió el evento. Formato ISO 8601 (p. ej., 2020-07-10T15:00:00.000000+0000). Consulta la nota a continuación sobre el orden. |
| event_properties | JSON | Propiedades del evento. |
| event_type | String | Nombre del evento en formato Adapty. Consulta Tipos de eventos de Webhook para ver la lista completa. |
| idfa | UUID | ID de publicidad (solo Apple). IDFA en el perfil en el Adapty Dashboard. Puede ser null si no está disponible debido a restricciones de seguimiento, modo infantil o ajustes de privacidad. |
| idfv | UUID | Identificador para proveedores (IDFV), único por desarrollador. IDFV en el perfil en el Adapty Dashboard. |
| integration_ids | JSON | IDs de integración del usuario si los has definido mediante el método setIntegrationIdentifier del SDK de Adapty o al crear/actualizar perfiles a través de la API del servidor. null si no están disponibles o las integraciones están deshabilitadas. |
| play_store_purchase_token | JSON | Token de compra de Play Store, incluido si Send Play Store purchase token está habilitado en los ajustes del Webhook. |
| profile_id | UUID | ID de perfil generado automáticamente por Adapty para cada perfil. Un mismo ID de Apple/Google puede estar asociado a diferentes IDs de perfil si no identificas usuarios o permites compras antes del inicio de sesión. Más información sobre cómo funciona Adapty con perfiles padre/heredero. |
| profile_install_datetime | ISO 8601 | Marca de tiempo de instalación en formato ISO 8601 (p. ej., 2020-07-10T15:00:00.000000+0000). |
| profiles_sharing_access_level | JSON | Lista de usuarios que comparten el nivel de acceso excluyendo el perfil de usuario actual. Si el uso compartido de niveles de acceso está habilitado en tu app, esta lista incluye otros perfiles que se han usado con el mismo ID de Apple/Google. Formato:
|
| user_agent | String | User-agent del navegador del dispositivo. |
| user_attributes | JSON | Datos personalizados que puedes definir para enriquecer los perfiles de usuario con información específica de la app. Se usan habitualmente para registrar preferencias del usuario (p. ej., tema, idioma) o indicadores de comportamiento (onboarding completado, uso de funcionalidades). Con formato de pares clave-valor donde las claves son cadenas y los valores pueden ser cadenas o números (p. ej., {"Favourite_color": "Violet", "Pet_name": "Fluffy"}). Puedes definir atributos personalizados manualmente en el Adapty Dashboard para perfiles individuales, de forma programática mediante el método updateProfile del SDK de Adapty, o a través de la API del servidor al crear/actualizar perfiles. Se incluye si Send User Attributes está habilitado en los ajustes del Webhook. Aunque los valores de atributos personalizados en el código de la app para móvil pueden definirse como floats o strings, los atributos recibidos a través de la API del servidor o importación histórica pueden llegar en distintos formatos. En ese caso, los valores booleanos y enteros se convertirán a floats. |
event_datetime refleja cuándo ocurrió un evento en el ciclo de vida de la suscripción, no cuándo Adapty lo procesó o entregó. Por este motivo, varios eventos pueden compartir el mismo event_datetime o llegar fuera de orden cronológico. Por ejemplo, un evento subscription_expired puede tener un event_datetime anterior al de un evento subscription_renewal_cancelled que Adapty entrega antes que él. No uses event_datetime para ordenar eventos. En su lugar, ordénalos por tu propio tiempo de recepción y elimina duplicados usando profile_event_id o los IDs de transacción.
Atribuciones
Para enviar los datos de atribución, activa la opción Send Attribution en la página Integrations -> Webhooks. Si has activado el envío de datos de atribución y tienes configuradas las integraciones de atribución, los datos a continuación se enviarán con el evento para cada fuente. Los mismos datos de atribución se envían a todos los tipos de eventos.
{
"attributions": {
"appsflyer": {
"ad_set": "sample_ad_set_123",
"status": "non_organic",
"channel": "sample_channel",
"ad_group": "sample_ad_group_456",
"campaign": "sample_ios_campaign",
"creative": "sample_creative_789",
"created_at": "2000-01-31T00:00:00.000000+0000",
"network_user_id": "0000000000000-0000000"
}
}
}
| Nombre del campo | Tipo de campo | Descripción |
|---|---|---|
| ad_set | String | Conjunto de anuncios de atribución. |
| status | String | Puede ser organic, non_organic, o unknown. |
| channel | String | Nombre del canal de marketing. |
| ad_group | String | Grupo de anuncios de atribución. |
| campaign | String | Nombre de la campaña de marketing. |
| creative | String | Palabra clave creativa de atribución. |
| created_at | Fecha ISO 8601 | Fecha y hora de creación del registro de atribución. |
| network_user_id | String | ID asignado al usuario por la fuente de atribución. |
IDs de integración
Los siguientes IDs de integración se utilizan actualmente en los eventos:
adjust_device_idairbridge_device_idamplitude_device_idamplitude_user_idappmetrica_device_idappmetrica_profile_idappsflyer_idbranch_idfacebook_anonymous_idfirebase_app_instance_idmixpanel_user_idpushwoosh_hwidone_signal_player_idone_signal_subscription_idtenjin_analytics_installation_idposthog_distinct_user_idsingular_sdid
Token de compra de Play Store
Este campo incluye todos los datos necesarios para revalidar una compra si es preciso. Solo se envía si la opción Send Play Store purchase token está habilitada en la configuración de la integración de Webhook.
| Campo | Tipo | Descripción |
|---|---|---|
| product_id | String | El identificador único del producto (SKU) comprado en Play Store. |
| purchase_token | String | Token generado por Google Play para identificar de forma única esta transacción de compra. |
| is_subscription | Boolean | Indica si el producto comprado es una suscripción (true) o una compra única (false). |
Propiedades de eventos
Las propiedades de los eventos pueden variar según el tipo de evento e incluso entre eventos del mismo tipo. Por ejemplo, un evento originado en el App Store no incluirá propiedades específicas de Android como base_plan_id.
El evento Nivel de acceso actualizado tiene propiedades específicas, por lo que le hemos dedicado una sección aparte. Del mismo modo, hemos separado las Propiedades adicionales de eventos fiscales y de ingresos, ya que son exclusivas de ciertos tipos de eventos.
Para la mayoría de los tipos de eventos
Las propiedades de los eventos son consistentes para la mayoría de los tipos de eventos (excepto para el evento Access Level Updated, que se describe en su propia sección). A continuación se muestra una tabla completa con las propiedades e indicaciones sobre si pertenecen a eventos específicos.
Adapty convierte otras divisas a USD utilizando el tipo de cambio de currencylayer.com (actualizado cada 8 horas). El tipo se fija en el momento de la transacción — los cambios futuros no afectan al resultado de la conversión.
| Campo | Tipo | Descripción |
|---|---|---|
| ab_test_id | UUID | ID de la prueba A/B de Adapty en la que se originó la transacción. En una prueba A/B multiplacement, el ID de la prueba multiplacement es el mismo en todos los placements. Consulta Campos de flow y prueba A/B. |
| ab_test_name | String | Nombre de la prueba A/B de Adapty en la que se originó la transacción. En una prueba A/B multiplacement, es el nombre de la prueba en un placement concreto, con el formato <nombre del test> child-N, donde N es el número de placement, no el de la variante. Para agrupar una prueba multiplacement entre placements, usa ab_test_id y toma su nombre de ab_test_parent_name. |
| ab_test_parent_name | String | Nombre de la prueba A/B multiplacement en la que se originó la transacción. Solo está presente en pruebas A/B multiplacement. |
| ab_test_revision | Integer | Revisión de la prueba A/B en la que se originó la transacción. |
| ab_test_variant_id | UUID | ID de la variante de la prueba A/B en la que se originó la transacción. En una prueba A/B de paywall normal, coincide con variation_id. En una prueba A/B de flow, coincide con flow_variation_id. En una prueba A/B multiplacement, es el mismo para la variante en todos los placements. Úsalo para dividir transacciones por variante de prueba. |
| ab_test_variant_name | String | Nombre de la variante de la prueba A/B. En una prueba A/B multiplacement, el nombre de la variante según la configuración de la prueba. En otras pruebas, el nombre de la variante, o el nombre del paywall o del flow cuando la variante no tiene nombre. Aparece junto con ab_test_variant_id. |
| base_plan_id | String | ID del plan base en Google Play Store o ID de precio en Stripe. |
| cancellation_reason | String | Posibles motivos de cancelación: Está presente en los siguientes tipos de evento: subscription_cancelled, subscription_refunded y trial_cancelled. |
| cohort_name | String | El nombre de la audiencia que determinó qué paywall se mostró al usuario. |
| consecutive_payments | Integer | El número de períodos que un usuario lleva suscrito sin interrupciones. Incluye el período actual. |
| currency | String | Moneda local. null en trial_started a menos que esté habilitado Send trial price. Consulta Propiedades adicionales de eventos de impuestos e ingresos. |
| developer_id | String | El ID del placement en el que se originó la transacción. |
| discount_amount_local | Float | El descuento aplicado a la transacción: el precio estándar menos el importe realmente cobrado, antes de la comisión de Apple/Google, en moneda local. 0 para una compra a precio completo. Para una prueba gratuita, equivale al precio estándar completo (original_price_local), ya que no se cobra nada. null cuando se aplicó una oferta pero se desconoce el precio estándar (consulta original_price_local). Siempre null para las ofertas pay-up-front de App Store: el único cargo anticipado cubre varios períodos de facturación, por lo que no puede compararse con el precio estándar por período. |
| discount_amount_usd | Float | El valor de discount_amount_local en USD. |
| environment | String | Los valores posibles son Sandbox o Production. |
| event_datetime | ISO 8601 date | La fecha y hora del evento. Igual que en el nivel raíz del evento. |
| flow_id | UUID | ID del flow en el que se originó la transacción. Presente en toda transacción realizada en un flow, esté o no en una prueba A/B. |
| flow_name | String | Nombre del flow en el que se originó la transacción. Aparece junto con flow_id. |
| flow_variation_id | UUID | ID de la variante del flow en este placement. El mismo valor que el SDK devuelve a la app como flow.variationId. Aparece junto con flow_id. |
| original_price_local | Float | El precio estándar del producto sin descuento, antes de la comisión de Apple/Google, en moneda local. En las suscripciones, es el precio de renovación. Equivale a price_local para una compra a precio completo y siempre es igual a price_local para compras únicas, ya que los stores no reportan un precio estándar separado para ellas. null para una compra con descuento cuando el store no reporta un precio estándar fiable (por ejemplo, si la renovación automática está desactivada, la renovación aún lleva una oferta o hay un cambio de producto pendiente). |
| original_price_usd | Float | Igual que original_price_local, en USD. |
| original_purchase_date | ISO 8601 date | Para suscripciones recurrentes, la compra original es la primera transacción de la cadena; su ID, denominado ID de transacción original, vincula la cadena de renovaciones. Las transacciones posteriores son extensiones de ella. La fecha de compra original es la fecha y hora de esa primera transacción. |
| original_transaction_id | String | Para suscripciones recurrentes, es el ID de transacción original que vincula la cadena de renovaciones. La transacción original es la primera de la cadena; las posteriores son extensiones de ella. Si no hay extensiones, |
| paywall_name | String | Nombre del paywall en el que se originó la transacción. En un flow, este es el ID de la pantalla del paywall dentro del flow (scr_...), no un nombre. El nombre del flow está en flow_name. |
| paywall_revision | String | Revisión del paywall en el que se originó la transacción. El valor predeterminado es 1. |
| price_local | Float | El importe cobrado por la transacción antes de la comisión de Apple/Google, en moneda local. null en trial_started, ya que no se cobra nada, a menos que esté habilitado Send trial price. |
| price_usd | Float | El importe cobrado por la transacción antes de la comisión de Apple/Google, en USD. null en trial_started, ya que no se cobra nada, a menos que esté habilitado Send trial price. |
| profile_country | String | Determinado por Adapty según la IP del perfil. |
| profile_event_id | UUID | ID de evento único que se puede usar para deduplicación. |
| profile_has_access_level | Boolean | Booleano que indica si el perfil tiene un nivel de acceso activo. |
| profile_id | UUID | ID de perfil generado por Adapty. Igual que en el nivel raíz del evento. |
| profile_ip_address | String | IP del perfil (puede ser IPv4 o IPv6, con preferencia por IPv4 cuando esté disponible). null si Collect users’ IP addresses está deshabilitado en la configuración de la app. |
| profile_total_revenue_usd | Float | Ingresos totales del perfil con los reembolsos descontados. |
| promotional_offer_id | String | El ID de Adapty de la oferta promocional utilizada. Este ID lo estableces tú al crear una oferta en el dashboard. |
| purchase_date | ISO 8601 date | La fecha y hora de la compra del producto. |
| rate_after_first_year | Boolean | Booleano que indica que la suscripción cumple los requisitos para una tasa de comisión reducida (normalmente el 15 %) tras un año de renovación continua. Las tasas de comisión varían según la elegibilidad del programa y el país. Consulta Comisión del store e impuestos para más detalles. |
| store | String | Store donde se compró el producto. Valores estándar: app_store, play_store, stripe, paddle. Si estableces transacciones de store personalizadas mediante la API del servidor, se usa el valor del parámetro store. |
| store_country | String | El país que nos envía el app store. |
| store_offer_category | String | Categoría de oferta aplicada. Los valores posibles son introductory, promotional, winback. |
| store_offer_discount_type | String | Tipo de oferta aplicada. Los valores posibles son free_trial, pay_as_you_go y pay_up_front. |
| store_offer_number_of_periods | Integer | Número de períodos de facturación base que descuenta una oferta (1 o más). Solo está presente cuando se aplica una oferta. null para las ofertas pay-up-front de App Store y cuando el store no reporta la duración de la oferta. |
| subscription_expires_at | ISO 8601 date | La fecha de vencimiento de la suscripción. En eventos de reembolso, problema de facturación, período de gracia y nivel de acceso, contiene la fecha de cancelación o la fecha de fin del período de gracia cuando corresponda. En eventos de compra y renovación, contiene la fecha de vencimiento regular de la suscripción. |
| transaction_id | String | Identificador único de una transacción. |
| trial_duration | String | Duración del período de prueba en días. Se envía en el formato ” days”, por ejemplo, “7 days”. Solo está presente en los tipos de evento relacionados con la prueba: trial_started, trial_converted, trial_cancelled. |
| variation_id | UUID | ID único del paywall donde se realizó la compra. En un flow, es el ID de la pantalla del paywall dentro del flow, no el de la variante de la prueba A/B. Cada versión publicada del flow recibe nuevos IDs de pantalla, por lo que Adapty envía una variante con diferentes valores de variation_id a lo largo del tiempo. Para dividir transacciones por variante de prueba, usa ab_test_variant_id. |
| vendor_product_id | String | ID del producto en Apple App Store, Google Play Store o Stripe. Para un plan de compromiso de 12 meses, el valor es Si se concedió el acceso sin una transacción real en el store,
|
Campos de flow y prueba A/B
Los campos de flow y prueba A/B indican de qué flow, prueba A/B y variante proviene una transacción. Funcionan con todos los tipos de prueba A/B: pruebas A/B de paywall y flow regulares, y pruebas A/B de placement cruzado en paywalls y en flows.
Adapty envía estos campos en los eventos de una transacción realizada en un placement, los mismos eventos que incluyen developer_id y variation_id. Las renovaciones, reembolsos, cancelaciones y otros eventos de suscripción llevan el mismo flow, prueba A/B y variante que la compra original, incluso después de que la prueba A/B haya finalizado. Cuando un campo no tiene valor, el evento no lo incluye: estos campos nunca están vacíos ni son null.
| Fuente de transacción | flow_id, flow_name, flow_variation_id | ab_test_id | ab_test_variant_id, ab_test_variant_name | ab_test_parent_name |
|---|---|---|---|---|
| Prueba A/B de paywall regular | — | ID de prueba A/B | Coincide con variation_id | — |
| Paywall fuera de una prueba A/B | — | — | — | — |
| Prueba A/B de flow | ✅ | ID de prueba A/B | Coincide con flow_variation_id | — |
| Flow fuera de una prueba A/B | ✅ | — | — | — |
| Prueba A/B multiplacement en paywalls | — | ID de prueba multiplacement | Compartido por todos los placements | ✅ |
| Prueba A/B multiplacement en flows | ✅, con la variante de flow en este placement | ID de prueba multiplacement | Compartido por todos los placements | ✅ |
| No es un placement | — | — | — | — |
Por ejemplo, para una compra en la variante A en el segundo placement de una prueba A/B entre placements con flows, Adapty envía:
{
"variation_id": "<paywall screen ID on this placement>",
"ab_test_name": "Onboarding test child-1",
"paywall_name": "scr_a1b2c3d4",
"flow_id": "<flow ID>",
"flow_name": "Onboarding X",
"flow_variation_id": "<variant A on this placement>",
"ab_test_id": "<crossplacement test ID>",
"ab_test_variant_id": "<variant A, shared by all placements>",
"ab_test_variant_name": "A",
"ab_test_parent_name": "Onboarding test"
}
Para crear informes sobre estos campos, agrupa las transacciones por los IDs (ab_test_id, ab_test_variant_id, flow_id) y usa los nombres como etiquetas. Adapty toma los nombres en el momento en que envía el evento, por lo que si renombras una prueba, variante o flow, los eventos posteriores llevarán el nuevo nombre. Los eventos ya enviados no se reenvían ni se actualizan.
El ID de variante compartido de una prueba A/B entre placements coincide con el ID de variante de un solo placement, normalmente el primero. Para relacionar un evento con la variante que el SDK devolvió en un placement concreto, usa flow_variation_id o variation_id.
En una prueba A/B entre placements donde el mismo flow aparece en más de una variante, la compra por sí sola no indica en qué variante estaba el usuario. Adapty obtiene la variante del registro de asignación del usuario. Si ese registro no está disponible, Adapty envía flow_id, flow_name y ab_test_id, pero no flow_variation_id, ab_test_variant_id ni ab_test_variant_name. Esto ocurre cuando el usuario compra justo después de ver el flow, antes de que el registro se guarde, y también para las renovaciones que llegan después de que el registro ha expirado. El Adapty Dashboard cuenta esas transacciones en la primera variante, por lo que los datos de tu integración pueden diferir del dashboard.
Propiedades adicionales de impuestos e ingresos en eventos
Las propiedades de evento relacionadas con impuestos e ingresos que se muestran a continuación son campos adicionales que solo aplican a ciertos tipos de eventos. Esto significa que los tipos de eventos indicados incluyen las Propiedades de evento para la mayoría de los tipos de eventos, junto con los campos extra que se listan a continuación.
Tipos de eventos que tienen las propiedades de impuestos e ingresos:
subscription_renewedsubscription_initial_purchase(también denominadosubscription_started— mismo evento)subscription_refundednon_subscription_purchasenon_subscription_purchase_refundedtrial_startedtrial_converted
| Campo | Tipo | Descripción |
|---|---|---|
| net_revenue_local | Float | Ingresos netos (ingresos tras el recorte de Apple/Google e impuestos) en moneda local. |
| net_revenue_usd | Float | Ingresos netos (ingresos tras el recorte de Apple/Google e impuestos) en USD. |
| proceeds_local | Float | price_local tras el recorte de Apple/Google. |
| proceeds_usd | Float | price_usd tras el recorte de Apple/Google. |
| tax_amount_local | Float | Impuesto estimado incluido en price_local. 0 para Stripe y Paddle, incluso cuando el usuario pagó impuestos. |
| tax_amount_usd | Float | Impuesto estimado incluido en price_usd. 0 para Stripe y Paddle, incluso cuando el usuario pagó impuestos. |
Para los ingresos netos, usa net_revenue_* directamente. A menos que tax_amount_* sea 0, proceeds_* menos tax_amount_* da una cantidad menor. Por ejemplo, con un precio de 12, una comisión del 30% y una tasa impositiva del 20%, Adapty calcula:
proceeds_*=price_*× (1 − comisión) = 12 × 0.7 = 8.40tax_amount_*=price_*× tasa impositiva ÷ (1 + tasa impositiva) = 12 × 0.2 ÷ 1.2 = 2.00net_revenue_*=proceeds_*÷ (1 + tasa impositiva) = 8.40 ÷ 1.2 = 7.00
Una prueba gratuita no cobra nada, por lo que en trial_started los campos de precio (price_*, proceeds_*, net_revenue_*, tax_amount_*) y currency son null por defecto. Para recibirlos, activa Send trial price en los ajustes de webhook. Adapty los calcula a partir del precio de la suscripción multiplicado por Trial price percentage y envía currency. Estos valores describen la suscripción, no un cobro, así que no incluyas trial_started en los totales de ingresos.
Ejemplo de payload de non_subscription_purchase
non_subscription_purchase sigue la misma estructura que los eventos de suscripción, pero refleja una compra única o consumible. Los campos exclusivos de suscripción no aplican: cancellation_reason, will_renew, is_in_grace_period, is_refund, is_lifetime y trial_duration están ausentes. subscription_expires_at está presente pero con valor null. Los campos de impuestos e ingresos (net_revenue_*, proceeds_*, tax_amount_*) están incluidos.
Ejemplo de payload (haz clic para expandir)
{
"profile_id": "00000000-0000-0000-0000-000000000000",
"customer_user_id": "UserIdInYourSystem",
"event_type": "non_subscription_purchase",
"event_datetime": "2000-01-31T00:00:00.000000+0000",
"event_properties": {
"store": "app_store",
"currency": "USD",
"price_usd": 4.99,
"price_local": 4.99,
"original_price_usd": 4.99,
"original_price_local": 4.99,
"discount_amount_usd": 0,
"discount_amount_local": 0,
"proceeds_usd": 4.2415,
"proceeds_local": 4.2415,
"net_revenue_usd": 4.2415,
"net_revenue_local": 4.2415,
"tax_amount_usd": 0,
"tax_amount_local": 0,
"profile_id": "00000000-0000-0000-0000-000000000000",
"environment": "Production",
"vendor_product_id": "100coins",
"transaction_id": "0000000000000000",
"original_transaction_id": "0000000000000000",
"purchase_date": "2024-11-15T10:45:36.181000+0000",
"original_purchase_date": "2024-11-15T10:45:36.181000+0000",
"subscription_expires_at": null,
"store_country": "US",
"profile_country": "US",
"profile_ip_address": "10.10.1.1",
"profile_has_access_level": false,
"profile_total_revenue_usd": 4.99,
"consecutive_payments": 1,
"rate_after_first_year": false,
"profile_event_id": "00000000-0000-0000-0000-000000000000"
},
"event_api_version": 1
} Para el evento Access Level Updated
El evento Access Level Updated es un evento de webhook específico que se genera únicamente cuando la integración de Webhook está activa y este tipo de evento está habilitado. Si está habilitado, se envía al Webhook configurado y aparece en el Event Feed. Si no está habilitado, el evento no se creará.
Si has habilitado el uso compartido de niveles de acceso, el evento access level updated se enviará para todos los perfiles que compartan el nivel de acceso.
Usa este evento para actualizar el nivel de acceso del usuario en tu base de datos, conceder o revocar funciones premium en tu backend y mantener el acceso sincronizado entre dispositivos o plataformas.
| Propiedad | Tipo | Descripción |
|---|---|---|
| ab_test_id | UUID | ID de la prueba A/B donde se originó la transacción. Consulta Campos de flow y prueba A/B. |
| ab_test_name | String | Nombre de la prueba A/B donde se originó la transacción. Para una prueba A/B entre placements, el nombre de la prueba en un placement (<test name> child-N). |
| ab_test_parent_name | String | Nombre de la prueba A/B entre placements. Solo está presente en pruebas A/B entre placements. |
| ab_test_variant_id | UUID | ID de la variante de la prueba A/B donde se originó la transacción. |
| ab_test_variant_name | String | Nombre de la variante de la prueba A/B. |
| access_level_id | String | El ID del nivel de acceso. |
| activated_at | ISO 8601 date | Fecha y hora en que se activó el acceso por última vez. |
| active_introductory_offer_type | String | Tipo de oferta introductoria aplicada. Los valores posibles son free_trial, pay_as_you_go y pay_up_front. |
| active_promotional_offer_id | String | ID de la oferta promocional indicada en la sección de productos del Adapty Dashboard. |
| active_promotional_offer_type | String | Tipo de oferta promocional aplicada. Los valores posibles son free_trial, pay_as_you_go y pay_up_front. |
| base_plan_id | String | ID del plan base en Google Play Store o ID de precio en Stripe. |
| billing_issue_detected_at | ISO 8601 date | Fecha y hora del problema de facturación. |
| cancellation_reason | String | Motivos posibles de cancelación: voluntarily_cancelled, billing_error, price_increase, product_was_not_available, refund, cancelled_by_developer, new_subscription_replace, upgraded, unknown, adapty_revoked. |
| cohort_name | String | Nombre de la audiencia a la que pertenece el perfil. |
| currency | String | Moneda local (por defecto USD). |
| developer_id | String | El ID del placement donde se originó la transacción. |
| environment | String | Los valores posibles son Sandbox o Production. |
| event_datetime | ISO 8601 date | La fecha y hora del evento. |
| expires_at | ISO 8601 date | Fecha y hora en que expira el acceso. Adapty calcula Durante un período de gracia, contiene el final del período de gracia; tras un reembolso o cancelación, contiene la fecha de cancelación. No existe un campo separado para el final del período de gracia. |
| flow_id | UUID | ID del flow donde se originó la transacción. |
| flow_name | String | Nombre del flow donde se originó la transacción. |
| flow_variation_id | UUID | ID de la variante del flow en este placement, igual que flow.variationId en el SDK. |
| is_active | Boolean | Booleano que indica si el nivel de acceso está activo. Se calcula a partir de expires_at (junto con starts_at e is_lifetime) cuando se genera el evento. |
| is_in_grace_period | Boolean | Booleano que indica si el perfil está en el período de gracia. Mientras sea true, expires_at contiene el final del período de gracia. |
| is_lifetime | Boolean | Booleano que indica si el nivel de acceso es de por vida. |
| is_refund | Boolean | Booleano que indica si la transacción es un reembolso. |
| original_purchase_date | ISO 8601 date | En suscripciones recurrentes, la compra original es la primera transacción de la cadena; su ID, llamado ID de transacción original, enlaza la cadena de renovaciones. Las transacciones posteriores son extensiones de ella. La fecha de compra original es la fecha y hora de esa primera transacción. |
| original_transaction_id | String | En suscripciones recurrentes, este es el ID de transacción original que enlaza la cadena de renovaciones. La transacción original es la primera de la cadena; las transacciones posteriores son extensiones de ella. Si no hay extensiones, |
| paywall_name | String | Nombre del paywall donde se originó la transacción. En un flow, el ID de la pantalla del paywall (scr_...). |
| paywall_revision | String | Revisión del paywall donde se originó la transacción. El valor por defecto es 1. |
| profile_country | String | Determinado por Adapty a partir de la IP del perfil. |
| profile_event_id | UUID | ID de evento único que puede usarse para deduplicación. |
| profile_has_access_level | Boolean | Booleano que indica si el perfil tiene un nivel de acceso activo. |
| profile_id | UUID | ID de perfil de usuario interno de Adapty. |
| profile_ip_address | String | IP del perfil (puede ser IPv4 o IPv6; se prefiere IPv4 cuando está disponible). null si Collect users’ IP addresses está desactivado en los ajustes de la app. |
| profile_total_revenue_usd | Float | Ingresos totales del perfil, incluidos los reembolsos. |
| purchase_date | ISO 8601 date | La fecha y hora de la compra del producto. |
| renewed_at | ISO 8601 date | Fecha y hora en que comenzó más recientemente el período actual de acceso de pago. Hasta la primera renovación, coincide con activated_at. |
| starts_at | ISO 8601 date | Fecha y hora en que comienza el nivel de acceso. |
| store | String | Store donde se compró el producto. Valores estándar: app_store, play_store, stripe, paddle. Si configuras transacciones de store personalizadas mediante la API del servidor, se utiliza el valor del parámetro store. |
| store_country | String | País enviado a Adapty por el store. |
| subscription_expires_at | ISO 8601 date | La fecha de expiración de la suscripción. En este evento contiene el mismo valor que expires_at: durante un período de gracia, el final del período de gracia; tras un reembolso o cancelación, la fecha de cancelación. |
| transaction_id | String | Identificador único de una transacción. |
| trial_duration | String | Duración de un período de prueba en días (p. ej., “7 days”). |
| variation_id | UUID | Identificador de una variante, utilizado para atribuir compras a este paywall. En un flow, el ID de la pantalla del paywall dentro del flow, no la variante de la prueba A/B. |
| vendor_product_id | String | ID del producto en el store (Apple/Google/Stripe). Para un plan de compromiso de 12 meses, el valor es Si el acceso fue concedido sin una transacción real en el store,
|
| will_renew | Boolean | Indica si el nivel de acceso de pago se renovará. |
Ten en cuenta que esta estructura puede crecer con el tiempo, ya que nosotros o los terceros con los que trabajamos podemos añadir nuevos datos. Asegúrate de que el código que la procesa sea lo suficientemente robusto y se base en campos específicos en lugar de depender de la estructura completa.