Intégration initiale avec Paddle

Adapty prend en charge les flows web2app en suivant les paiements et abonnements web effectués via Paddle.

Cette intégration couvre les achats initiés depuis le web et les synchronise avec l’accès à l’application mobile et les analytics, en complément des achats intégrés depuis les stores.

Cela s’avère utile dans les scénarios suivants :

Collecter les données d’abonnement provenant à la fois des achats intégrés et des achats effectués sur le site web dans un seul système
Accorder l’accès aux fonctionnalités payantes de votre application mobile aux utilisateurs ayant acheté sur votre site web
Consulter les analyses et les données d’abonnement de tous les canaux de vente dans un seul tableau de bord

Note

Apple autorise désormais les applications de l’App Store américain à inclure des liens vers des systèmes de paiement externes, bien que les applications puissent encore avoir besoin de proposer des achats intégrés en parallèle des options externes. Consultez les directives App Store en vigueur pour votre région et votre catégorie d’application.

Note

Cette intégration porte sur le suivi et la synchronisation des achats web Paddle. Si vous souhaitez rediriger les utilisateurs de l’application vers une page de paiement web, utilisez les paywalls web d’Adapty.

Pour configurer l’intégration Paddle, suivez ces étapes :

1. Connecter Paddle à Adapty

L’intégration utilise des webhooks pour envoyer les données d’abonnement de Paddle vers Adapty. Pour connecter vos comptes Adapty et Paddle, vous devez :

Fournir vos clés API Paddle.
Ajouter l’URL du webhook Adapty à Paddle.

Note

Les étapes ci-dessous s’appliquent à la fois à la Production et au Test. Vous pouvez configurer les deux simultanément. Les liens fournis correspondent à l’environnement de Production — pour obtenir les liens de l’environnement de Test, ajoutez simplement sandbox- au début de chaque URL. Par exemple, utilisez https://sandbox-vendors.paddle.com/authentication-v2 à la place de https://vendors.paddle.com/authentication-v2.

1.1. Obtenir et ajouter les clés API Paddle

Dans Paddle, rendez-vous sur Developer Tools → Authentication et cliquez sur New API key.

Donnez un nom à la clé et définissez sa date d’expiration. Pour que la clé API fonctionne avec Adapty, vous devez lui accorder la permission Read pour toutes les entités. Cliquez sur Save.

Cliquez sur Copy key.

Dans Adapty, rendez-vous dans App Settings → Paddle et collez la clé dans la section Paddle API key.

Warning

Si vous définissez une date d’expiration pour votre clé API Paddle, vous devez générer manuellement une nouvelle clé et la mettre à jour dans Adapty avant l’expiration. L’intégration cessera de fonctionner sans avertissement lorsque la clé expirera, et les utilisateurs ne pourront pas effectuer d’achats.

1.2. Ajouter les événements qui seront envoyés à Adapty

Copiez l’Webhook URL depuis la même page Paddle dans Adapty.
Dans Paddle, accédez à Developer Tools → Notifications et cliquez sur New destination pour ajouter un webhook.

Saisissez un nom descriptif pour le webhook. Nous recommandons d’inclure « Adapty » dedans, pour le retrouver facilement si besoin.
Collez l’Webhook URL d’Adapty dans le champ URL. Assurez-vous d’utiliser le webhook correspondant au bon environnement.
Définissez le Notification type sur Webhook.

Sélectionnez les événements suivants :

subscription.created
- subscription.updated
- transaction.created
- transaction.updated
- adjustment.created
- adjustment.updated

Cliquez sur Save destination pour finaliser la configuration du webhook.

1.3. Récupérer et ajouter la clé secrète du webhook

Dans la fenêtre Notifications, cliquez sur les trois points à côté du webhook que vous venez de créer et sélectionnez Edit destination.
Un nouveau champ appelé Secret key apparaîtra dans le panneau Edit destination. Copiez-le.

Dans Adapty, accédez à App Settings → Paddle et collez la clé dans le champ Notification secret key. Cette clé est utilisée pour vérifier les données de webhook dans Adapty.

1.4. Associer les clients Paddle aux profils Adapty

Adapty doit lier chaque achat à un profil client pour qu’il puisse être utilisé dans votre application. Par défaut, les profils sont créés automatiquement lorsque Adapty reçoit des webhooks de Paddle. Vous pouvez choisir la valeur à utiliser comme customer_user_id dans Adapty :

Par défaut et recommandé : Le customer_user_id que vous passez dans le champ custom_data (voir la documentation Paddle)
L’email de l’objet Paddle Customer (voir la documentation Paddle)
L’identifiant Paddle Customer au format ctm-... (voir la documentation Paddle)
Ne pas créer de profils. Choisissez cette option si vous souhaitez avoir plus de contrôle sur vos profils client et les gérer vous-même.

Vous pouvez configurer la valeur à utiliser dans le champ Profile creation behavior dans App Settings → Paddle.

2. Ajouter les produits Paddle à Adapty

Warning

Assurez-vous d’ajouter vos produits Paddle à l’Adapty Dashboard ou d’associer un identifiant de produit Paddle à vos produits existants. Adapty ne suit les événements que pour les transactions liées à ces produits. Si vous sautez cette étape, aucun événement de transaction ne sera créé.

Paddle fonctionne dans Adapty exactement comme l’App Store et Google Play — c’est simplement une autre plateforme sur laquelle vous vendez des produits numériques. Pour le configurer, ajoutez les valeurs product_id et price_id correspondantes depuis Paddle dans la section Products d’Adapty.

Dans Paddle, les identifiants de produit ressemblent à pro_... et les identifiants de prix à pri_.... Vous les trouverez dans votre catalogue de produits Paddle en ouvrant un produit spécifique :

Une fois vos produits ajoutés, l’étape suivante consiste à s’assurer qu’Adapty peut relier l’achat au bon utilisateur.

3. Accorder l’accès aux utilisateurs sur mobile

Pour que les utilisateurs qui achètent sur le web obtiennent un accès sur mobile, appelez Adapty.activate() ou Adapty.identify() en utilisant le même customer_user_id que celui transmis lors de l’achat. Consultez Identifier les utilisateurs pour en savoir plus.

4. Testez votre intégration

Une fois tout configuré, vous pouvez tester votre intégration. Les transactions effectuées dans l’environnement Test de Paddle apparaîtront comme Test dans Adapty. Les transactions de l’environnement Production apparaîtront comme Production.

Votre intégration est maintenant terminée. Les utilisateurs peuvent acheter des abonnements sur votre site web et accéder automatiquement aux fonctionnalités premium dans votre application mobile, pendant que vous suivez toutes les analyses d’abonnements depuis votre tableau de bord Adapty unifié.

Considérations importantes

Dans les analyses d’Adapty, les montants des transactions incluent les taxes et les frais Paddle, contrairement au tableau de bord Paddle où les montants sont affichés après déduction des taxes et frais. Les chiffres affichés dans Adapty seront donc plus élevés que ceux de votre tableau de bord Paddle.
Contrairement aux autres stores, les remboursements dans Paddle n’affectent que la transaction concernée et n’annulent pas automatiquement l’abonnement. L’abonnement reste actif sauf s’il est explicitement annulé.
Vous pouvez également inclure variation_id dans le champ custom_data pour attribuer les achats à des instances de paywall spécifiques. Adapty traitera ces données depuis les webhooks et les inclura dans les analyses.

Essais payants

Lorsque vous utilisez des essais payants dans Paddle, vous devez créer deux produits dans Adapty :

Créez un produit non-abonnement et liez-le au prix Paddle qui facture la période d’essai.
Créez ensuite un produit d’abonnement (mensuel/hebdomadaire/etc.) et liez-le au prix Paddle qui comporte le composant d’essai gratuit.

Du point de vue de Paddle, il s’agit d’un seul produit avec deux prix dans une même transaction : un prix pour la facturation de l’essai (par exemple, 0,99 $) et un autre prix pour l’essai gratuit (0,00 $).

Du point de vue d’Adapty, cela crée deux événements distincts : un achat unique pour le paiement de l’essai et un événement de démarrage d’essai pour le produit d’abonnement.

Par exemple, quand un utilisateur commence un essai payant à 0,99 $ pour un abonnement à 9,99 $/mois, Paddle crée une seule transaction avec les deux prix, tandis qu’Adapty traite cela comme un achat unique de 0,99 $ (paiement immédiat) et un événement de démarrage d’essai à 0,00 $ (abonnement futur à 9,99 $/mois).

Note

Lorsque des utilisateurs annulent un essai payant, vous recevez les événements Trial expired et Trial renewal canceled.

Tirez le meilleur parti de vos données Paddle

Important

Pour que vos événements Paddle fonctionnent avec les intégrations, vos utilisateurs doivent s’être connectés à l’application avec leur compte App Store/Google Play au moins une fois.

Une fois l’intégration Paddle effectuée, Adapty est prêt à vous fournir des insights immédiatement. Pour exploiter au maximum vos données Paddle, vous pouvez configurer des intégrations Adapty supplémentaires afin de transférer les événements Paddle — et centraliser toutes vos analyses d’abonnements dans un seul Adapty Dashboard.

Intégrations disponibles pour transmettre et analyser vos événements Paddle :

Amplitude, Firebase / Google Analytics et Mixpanel conservent des identifiants distincts par plateforme. Renseignez les champs Paddle sur la page d’intégration — les événements Paddle n’utilisent pas vos identifiants iOS ou Android.

Limitations actuelles

Annulations : Paddle propose deux options d’annulation d’abonnement :
1. Annulation immédiate : L’abonnement est annulé immédiatement.
2. Annulation en fin de période : L’abonnement est annulé à la fin de la période de facturation en cours (comme les abonnements intégrés sur les stores).
Remboursements : Adapty suit les remboursements complets et partiels.
Délai de grâce : Par défaut, Paddle applique un délai de grâce fixe de 30 jours pour les problèmes de facturation, pendant lequel l’abonnement reste actif. Vous pouvez personnaliser la durée du délai de grâce et l’action à effectuer à son terme (suspension ou annulation de l’abonnement).

Essais : Si la collecte du paiement échoue après la fin d’un essai, le statut de l’abonnement passe à past_due. En production, Retain de Paddle applique une fenêtre de relance pour tenter de récupérer le paiement avant que l’abonnement ne soit annulé ou mis en pause. En sandbox, Retain n’est pas disponible, donc aucune nouvelle tentative de paiement n’est effectuée et l’abonnement reste past_due indéfiniment.

Voir aussi :

Valider un achat dans Paddle, obtenir un niveau d’accès et importer l’historique des transactions depuis Paddle avec l’API côté serveur