Integración inicial con Paddle

Adapty admite flujos de suscripción web2app rastreando pagos y suscripciones web realizados a través de Paddle.

Esta integración cubre las compras iniciadas desde la web y las sincroniza con el acceso a la app móvil y los análisis, junto con las compras in-app de los stores. Es útil en los siguientes escenarios:

  • Recopilar datos de suscripción tanto de compras in-app como de compras en el sitio web en un único sistema
  • Conceder acceso a funciones de pago en tu aplicación móvil a usuarios que compraron en tu sitio web
  • Ver análisis y datos de suscripción de todos los canales de venta en un solo dashboard

Apple ahora permite que las aplicaciones de la App Store de EE. UU. incluyan enlaces a sistemas de pago externos, aunque es posible que las aplicaciones aún necesiten ofrecer compras in-app junto con las opciones externas. Consulta las directrices actuales de la App Store para tu región y categoría de aplicación.

Esta integración se centra en el seguimiento y la sincronización de compras web de Paddle. Si necesitas enviar usuarios desde la app a un checkout web, usa los paywalls web de Adapty.

Para configurar la integración con Paddle, sigue estos pasos:

1. Conectar Paddle con Adapty

La integración utiliza webhooks para enviar datos de suscripción desde Paddle a Adapty. Para conectar tus cuentas de Adapty y Paddle, necesitarás:

  1. Proporcionar tus claves API de Paddle.
  2. Añadir la URL del webhook de Adapty a Paddle.

Los pasos a continuación se aplican tanto a Producción como a Test. Puedes configurar ambos simultáneamente. Los enlaces proporcionados corresponden al entorno de Producción — para obtener los enlaces del entorno de Test, simplemente añade sandbox- al principio de cada URL. Por ejemplo, usa https://sandbox-vendors.paddle.com/authentication-v2 en lugar de https://vendors.paddle.com/authentication-v2.

1.1. Obtén y añade las claves API de Paddle

  1. En Paddle, ve a Developer Tools → Authentication y haz clic en New API key.
paddle-new-key.webp
  1. Dale un nombre a la clave y establece la fecha de expiración. Para que la clave API funcione con Adapty, necesitas concederle el permiso Read para todas las entidades. Haz clic en Save.
paddle-key.webp
  1. Haz clic en Copy key.
copy-paddle-key.webp
  1. En Adapty, ve a App Settings → Paddle y pega la clave en la sección Paddle API key.

Si estableciste una fecha de vencimiento para tu clave de API de Paddle, debes generar manualmente una nueva clave y actualizarla en Adapty antes de que expire. La integración dejará de funcionar sin previo aviso cuando la clave caduque, y los usuarios no podrán realizar compras.

paddle-api-keys-adapty.webp

1.2. Añadir eventos que se enviarán a Adapty

  1. Copia la Webhook URL de la misma página de Paddle en Adapty.
  2. En Paddle, ve a Developer Tools → Notifications y haz clic en New destination para añadir un webhook.
paddle-webhook.webp

  1. Introduce un nombre descriptivo para el webhook. Te recomendamos incluir “Adapty” en él para que puedas encontrarlo fácilmente cuando lo necesites.

  2. Pega la Webhook URL de Adapty en el campo URL. Asegúrate de usar el webhook para el entorno correcto.

  3. Establece Notification type en Webhook.

paddle-create-webhook.webp
  1. Selecciona los siguientes eventos:

  • subscription.created

    • subscription.updated

    • transaction.created

    • transaction.updated

    • adjustment.created

    • adjustment.updated

paddle_events.png
  1. Haz clic en Save destination para finalizar la configuración del webhook.

1.3. Obtener y añadir la clave secreta del webhook

  1. En la ventana Notifications, haz clic en los tres puntos junto al webhook que acabas de crear y selecciona Edit destination.
  2. Aparecerá un nuevo campo llamado Secret key en el panel Edit destination. Cópialo.
paddle-webhook-secret-key-copy.webp
  1. En Adapty, ve a App Settings → Paddle y pega la clave en el campo Notification secret key. Esta clave se usa para verificar los datos del webhook en Adapty.
paddle-webhook-secret-key.webp

1.4. Vincula los clientes de Paddle con los perfiles de Adapty

Adapty necesita vincular cada compra a un perfil de cliente para que pueda usarse en tu app. De forma predeterminada, los perfiles se crean automáticamente cuando Adapty recibe webhooks de Paddle. Puedes elegir qué valor usar como customer_user_id en Adapty:

  1. Predeterminado y recomendado: El customer_user_id que pasas en el campo custom_data (ver documentación de Paddle)
  2. El email del objeto Paddle Customer (ver documentación de Paddle)
  3. El ID de cliente de Paddle en formato ctm-... (ver documentación de Paddle)
  4. No crear perfiles. Elige esta opción si quieres tener mayor control sobre los perfiles de tus clientes y gestionarlos tú mismo. Puedes configurar qué valor usar en el campo Profile creation behavior en App Settings → Paddle.
paddle-users.webp

2. Añade productos de Paddle a Adapty

Asegúrate de añadir tus productos de Paddle al Adapty Dashboard o de agregar un ID de producto de Paddle a tus productos existentes. Adapty solo registra eventos para transacciones vinculadas a estos productos. Si omites este paso, no se crearán eventos de transacción.

Paddle funciona en Adapty igual que App Store y Google Play: es otra plataforma donde vendes productos digitales. Para configurarlo, añade los valores de product_id y price_id correspondientes de Paddle en la sección Products de Adapty. En Paddle, los IDs de producto tienen el formato pro_... y los IDs de precio pri_.... Los encontrarás en tu catálogo de productos de Paddle una vez que abras un producto específico:

paddle-product-price.webp

Una vez añadidos tus productos, el siguiente paso es asegurarte de que Adapty pueda vincular la compra al usuario correcto.

3. Dar acceso a los usuarios en el móvil

Para asegurarte de que los usuarios que compran en la web obtengan acceso en el móvil, llama a Adapty.activate() o Adapty.identify() usando el mismo customer_user_id que pasaste al realizar la compra. Consulta Identificar usuarios para más detalles.

4. Probar tu integración

Una vez que todo esté configurado, puedes probar tu integración. Las transacciones realizadas en el entorno de Test de Paddle aparecerán como Test en Adapty. Las transacciones del entorno de Producción aparecerán como Production.

Tu integración ya está completa. Los usuarios pueden comprar suscripciones en tu sitio web y acceder automáticamente a las funciones premium en tu aplicación móvil, mientras tú haces seguimiento de todos los análisis de suscripciones desde tu Adapty Dashboard unificado.

Consideraciones importantes

  • En las analíticas de Adapty, los importes de las transacciones incluyen impuestos y comisiones de Paddle, lo que difiere del dashboard de Paddle, donde los importes se muestran después de impuestos y comisiones. Esto significa que las cifras que ves en Adapty serán más altas que las de tu dashboard de Paddle.
  • A diferencia de otros stores, los reembolsos en Paddle solo afectan a la transacción específica que se reembolsa y no cancelan automáticamente la suscripción. La suscripción seguirá activa a menos que se cancele de forma explícita.
  • También puedes incluir variation_id en el campo custom_data para atribuir compras a instancias de paywall específicas. Adapty procesará estos datos desde los webhooks y los incluirá en las analíticas.

Al trabajar con períodos de prueba de pago en Paddle, necesitas crear dos productos en Adapty:

  1. Crea un producto que no sea suscripción y vincúlalo al precio de Paddle que cobra por el período de prueba.
  2. Luego crea un producto de suscripción (mensual, semanal, etc.) y vincúlalo al precio de Paddle que tiene el componente de prueba gratuita.

Desde el punto de vista de Paddle, se trata de un único producto con dos precios en una sola transacción: un precio para el cargo del período de prueba (p. ej., $0,99) y otro precio para la prueba gratuita ($0,00). Desde la perspectiva de Adapty, esto genera dos eventos separados: una compra única por el pago de la prueba y un evento de inicio de prueba para el producto de suscripción.

Por ejemplo, cuando un usuario inicia una prueba de pago de $0,99 para una suscripción de $9,99/mes, Paddle crea una sola transacción con ambos precios, mientras que Adapty lo procesa como una compra única de $0,99 (pago inmediato) y un evento de inicio de prueba a $0,00 (suscripción futura a $9,99/mes).

Cuando los usuarios cancelan una prueba de pago, recibirás los eventos Trial expired y Trial renewal canceled.

Saca más partido a tus datos de Paddle

Para que tus eventos de Paddle funcionen con las integraciones, tus usuarios deben haber iniciado sesión en la app con su cuenta de App Store/Google Play al menos una vez.

Una vez que te integres con Paddle, Adapty está listo para ofrecer información de inmediato. Para aprovechar al máximo tus datos de Paddle, puedes configurar integraciones adicionales de Adapty para reenviar eventos de Paddle, centralizando todos tus análisis de suscripciones en un único Adapty Dashboard.

Integraciones que puedes usar para reenviar y analizar tus eventos de Paddle:

Limitaciones actuales

  • Cancelaciones: Paddle tiene dos opciones de cancelación de suscripción:

    1. Cancelación inmediata: La suscripción se cancela de inmediato.

    2. Cancelación al final del período: La suscripción se cancela al final del período de facturación actual (similar a las suscripciones in-app en los stores).

  • Reembolsos: Adapty registra los reembolsos totales y parciales.

  • Período de gracia: Por defecto, Paddle aplica un período de gracia fijo de 30 días para problemas de facturación, durante el cual la suscripción permanece activa. Puedes personalizar la duración del período de gracia y la acción al final del mismo (pausar o cancelar la suscripción). Pruebas: Si el cobro falla al finalizar una prueba, el estado de la suscripción cambia a past_due. En producción, Paddle Retain aplica una ventana de gestión de impagos para intentar recuperar el pago antes de cancelar o pausar la suscripción. En sandbox, Retain no está disponible, por lo que no se realizan reintentos de pago y la suscripción permanece en past_due indefinidamente.

Ver también: