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 eventoDescripción
subscription_startedSe activa cuando un usuario activa una suscripción de pago sin período de prueba, es decir, se le cobra de inmediato.
subscription_activeConfirma 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_renewedOcurre 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_cancelledUn 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_reactivatedSe activa cuando un usuario reactiva la renovación automática de la suscripción.
subscription_expiredSe 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_pausedOcurre cuando un usuario activa la pausa de suscripción (solo Android).
subscription_deferredSe 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_purchaseCualquier compra que no sea una suscripción, como acceso de por vida o productos consumibles como monedas del juego.
trial_startedSe activa cuando un usuario activa una suscripción de prueba.
trial_activeConfirma 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_convertedOcurre 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_cancelledUn 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_reactivatedOcurre cuando un usuario reactiva la renovación automática de la suscripción durante el período de prueba.
trial_expiredSe activa cuando una prueba termina sin convertirse en suscripción.
entered_grace_periodOcurre 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_detectedSe activa cuando ocurre un problema de facturación durante un intento de cobro (por ejemplo, saldo insuficiente en la tarjeta).
subscription_refundedSe activa cuando se reembolsa una suscripción (por ejemplo, por parte del soporte de Apple).
non_subscription_purchase_refundedSe activa cuando se reembolsa una compra que no es una suscripción.
access_level_updatedOcurre cuando se actualiza el nivel de acceso de un usuario.
Note

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.

Note

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.

CampoTipoDescripción
advertising_idUUIDID de publicidad (solo Android).
attributionsJSONDatos de atribución. Se incluye si Send Attribution está habilitado en los ajustes del Webhook.
customer_user_idStringID 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.
emailStringEmail 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_versionIntegerVersión de la API de Adapty (actual: 1).
event_datetimeISO 8601La 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_propertiesJSONPropiedades del evento.
event_typeStringNombre del evento en formato Adapty. Consulta Tipos de eventos de Webhook para ver la lista completa.
idfaUUIDID 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.
idfvUUIDIdentificador para proveedores (IDFV), único por desarrollador. IDFV en el perfil en el Adapty Dashboard.
integration_idsJSONIDs 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_tokenJSONToken de compra de Play Store, incluido si Send Play Store purchase token está habilitado en los ajustes del Webhook.
profile_idUUIDID 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_datetimeISO 8601Marca de tiempo de instalación en formato ISO 8601 (p. ej., 2020-07-10T15:00:00.000000+0000).
profiles_sharing_access_levelJSONLista 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:
  • profile_id: (UUID) ID de Adapty
  • customer_user_id: (String) Customer User ID si se ha proporcionado
user_agentStringUser-agent del navegador del dispositivo.
user_attributesJSONDatos 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.

Note

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 campoTipo de campoDescripción
ad_setStringConjunto de anuncios de atribución.
statusStringPuede ser organic, non_organic, o unknown.
channelStringNombre del canal de marketing.
ad_groupStringGrupo de anuncios de atribución.
campaignStringNombre de la campaña de marketing.
creativeStringPalabra clave creativa de atribución.
created_atFecha ISO 8601Fecha y hora de creación del registro de atribución.
network_user_idStringID 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_id
  • airbridge_device_id
  • amplitude_device_id
  • amplitude_user_id
  • appmetrica_device_id
  • appmetrica_profile_id
  • appsflyer_id
  • branch_id
  • facebook_anonymous_id
  • firebase_app_instance_id
  • mixpanel_user_id
  • pushwoosh_hwid
  • one_signal_player_id
  • one_signal_subscription_id
  • tenjin_analytics_installation_id
  • posthog_distinct_user_id
  • singular_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.

CampoTipoDescripción
product_idStringEl identificador único del producto (SKU) comprado en Play Store.
purchase_tokenStringToken generado por Google Play para identificar de forma única esta transacción de compra.
is_subscriptionBooleanIndica 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.

Note

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.

CampoTipoDescripción
ab_test_idUUIDID 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_nameStringNombre 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_nameStringNombre de la prueba A/B multiplacement en la que se originó la transacción. Solo está presente en pruebas A/B multiplacement.
ab_test_revisionIntegerRevisión de la prueba A/B en la que se originó la transacción.
ab_test_variant_idUUIDID 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_nameStringNombre 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_idStringID del plan base en Google Play Store o ID de precio en Stripe.
cancellation_reasonString

Posibles motivos de cancelación: voluntarily_cancelled, billing_error, price_increase, product_was_not_available, refund, cancelled_by_developer, new_subscription_replace, upgraded, unknown, adapty_revoked.

Está presente en los siguientes tipos de evento:

subscription_cancelled, subscription_refunded y trial_cancelled.
cohort_nameStringEl nombre de la audiencia que determinó qué paywall se mostró al usuario.
consecutive_paymentsIntegerEl número de períodos que un usuario lleva suscrito sin interrupciones. Incluye el período actual.
currencyStringMoneda local. null en trial_started a menos que esté habilitado Send trial price. Consulta Propiedades adicionales de eventos de impuestos e ingresos.
developer_idStringEl ID del placement en el que se originó la transacción.
discount_amount_localFloatEl 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_usdFloatEl valor de discount_amount_local en USD.
environmentStringLos valores posibles son Sandbox o Production.
event_datetimeISO 8601 dateLa fecha y hora del evento. Igual que en el nivel raíz del evento.
flow_idUUIDID 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_nameStringNombre del flow en el que se originó la transacción. Aparece junto con flow_id.
flow_variation_idUUIDID 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_localFloatEl 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_usdFloatIgual que original_price_local, en USD.
original_purchase_dateISO 8601 datePara 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_idString

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, original_transaction_id coincide con store_transaction_id.

paywall_nameStringNombre 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_revisionStringRevisión del paywall en el que se originó la transacción. El valor predeterminado es 1.
price_localFloatEl 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_usdFloatEl 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_countryStringDeterminado por Adapty según la IP del perfil.
profile_event_idUUIDID de evento único que se puede usar para deduplicación.
profile_has_access_levelBooleanBooleano que indica si el perfil tiene un nivel de acceso activo.
profile_idUUIDID de perfil generado por Adapty. Igual que en el nivel raíz del evento.
profile_ip_addressStringIP 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_usdFloatIngresos totales del perfil con los reembolsos descontados.
promotional_offer_idStringEl ID de Adapty de la oferta promocional utilizada. Este ID lo estableces tú al crear una oferta en el dashboard.
purchase_dateISO 8601 dateLa fecha y hora de la compra del producto.
rate_after_first_yearBooleanBooleano 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.
storeStringStore 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_countryStringEl país que nos envía el app store.
store_offer_categoryStringCategoría de oferta aplicada. Los valores posibles son introductory, promotional, winback.
store_offer_discount_typeStringTipo de oferta aplicada. Los valores posibles son free_trial, pay_as_you_go y pay_up_front.
store_offer_number_of_periodsIntegerNú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_atISO 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_idStringIdentificador único de una transacción.
trial_durationStringDuració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_idUUIDID ú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_idString

ID del producto en Apple App Store, Google Play Store o Stripe.

Para un plan de compromiso de 12 meses, el valor es <product_id>:monthly.

Si se concedió el acceso sin una transacción real en el store, vendor_product_id será uno de los siguientes:

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ónflow_id, flow_name, flow_variation_idab_test_idab_test_variant_id, ab_test_variant_nameab_test_parent_name
Prueba A/B de paywall regular—ID de prueba A/BCoincide con variation_id—
Paywall fuera de una prueba A/B————
Prueba A/B de flow✅ID de prueba A/BCoincide con flow_variation_id—
Flow fuera de una prueba A/B✅———
Prueba A/B multiplacement en paywalls—ID de prueba multiplacementCompartido por todos los placements✅
Prueba A/B multiplacement en flows✅, con la variante de flow en este placementID de prueba multiplacementCompartido 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.

Note

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.

Warning

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_renewed
  • subscription_initial_purchase (también denominado subscription_started — mismo evento)
  • subscription_refunded
  • non_subscription_purchase
  • non_subscription_purchase_refunded
  • trial_started
  • trial_converted
CampoTipoDescripción
net_revenue_localFloatIngresos netos (ingresos tras el recorte de Apple/Google e impuestos) en moneda local.
net_revenue_usdFloatIngresos netos (ingresos tras el recorte de Apple/Google e impuestos) en USD.
proceeds_localFloatprice_local tras el recorte de Apple/Google.
proceeds_usdFloatprice_usd tras el recorte de Apple/Google.
tax_amount_localFloatImpuesto estimado incluido en price_local. 0 para Stripe y Paddle, incluso cuando el usuario pagó impuestos.
tax_amount_usdFloatImpuesto 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.40
  • tax_amount_* = price_* × tasa impositiva ÷ (1 + tasa impositiva) = 12 × 0.2 ÷ 1.2 = 2.00
  • net_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.

Tip

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.

PropiedadTipoDescripción
ab_test_idUUIDID de la prueba A/B donde se originó la transacción. Consulta Campos de flow y prueba A/B.
ab_test_nameStringNombre 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_nameStringNombre de la prueba A/B entre placements. Solo está presente en pruebas A/B entre placements.
ab_test_variant_idUUIDID de la variante de la prueba A/B donde se originó la transacción.
ab_test_variant_nameStringNombre de la variante de la prueba A/B.
access_level_idStringEl ID del nivel de acceso.
activated_atISO 8601 dateFecha y hora en que se activó el acceso por última vez.
active_introductory_offer_typeStringTipo de oferta introductoria aplicada. Los valores posibles son free_trial, pay_as_you_go y pay_up_front.
active_promotional_offer_idStringID de la oferta promocional indicada en la sección de productos del Adapty Dashboard.
active_promotional_offer_typeStringTipo de oferta promocional aplicada. Los valores posibles son free_trial, pay_as_you_go y pay_up_front.
base_plan_idStringID del plan base en Google Play Store o ID de precio en Stripe.
billing_issue_detected_atISO 8601 dateFecha y hora del problema de facturación.
cancellation_reasonStringMotivos 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_nameStringNombre de la audiencia a la que pertenece el perfil.
currencyStringMoneda local (por defecto USD).
developer_idStringEl ID del placement donde se originó la transacción.
environmentStringLos valores posibles son Sandbox o Production.
event_datetimeISO 8601 dateLa fecha y hora del evento.
expires_atISO 8601 date

Fecha y hora en que expira el acceso. Adapty calcula is_active a partir de este campo.

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_idUUIDID del flow donde se originó la transacción.
flow_nameStringNombre del flow donde se originó la transacción.
flow_variation_idUUIDID de la variante del flow en este placement, igual que flow.variationId en el SDK.
is_activeBooleanBooleano 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_periodBooleanBooleano 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_lifetimeBooleanBooleano que indica si el nivel de acceso es de por vida.
is_refundBooleanBooleano que indica si la transacción es un reembolso.
original_purchase_dateISO 8601 dateEn 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_idString

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, original_transaction_id coincide con store_transaction_id.

El identificador de transacción de la compra original.
paywall_nameStringNombre del paywall donde se originó la transacción. En un flow, el ID de la pantalla del paywall (scr_...).
paywall_revisionStringRevisión del paywall donde se originó la transacción. El valor por defecto es 1.
profile_countryStringDeterminado por Adapty a partir de la IP del perfil.
profile_event_idUUIDID de evento único que puede usarse para deduplicación.
profile_has_access_levelBooleanBooleano que indica si el perfil tiene un nivel de acceso activo.
profile_idUUIDID de perfil de usuario interno de Adapty.
profile_ip_addressStringIP 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_usdFloatIngresos totales del perfil, incluidos los reembolsos.
purchase_dateISO 8601 dateLa fecha y hora de la compra del producto.
renewed_atISO 8601 dateFecha 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_atISO 8601 dateFecha y hora en que comienza el nivel de acceso.
storeStringStore 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_countryStringPaís enviado a Adapty por el store.
subscription_expires_atISO 8601 dateLa 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_idStringIdentificador único de una transacción.
trial_durationStringDuración de un período de prueba en días (p. ej., “7 days”).
variation_idUUIDIdentificador 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_idString

ID del producto en el store (Apple/Google/Stripe).

Para un plan de compromiso de 12 meses, el valor es <product_id>:monthly.

Si el acceso fue concedido sin una transacción real en el store, vendor_product_id será uno de los siguientes:

will_renewBooleanIndica si el nivel de acceso de pago se renovará.
Warning

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.