Intégration initiale avec Paddle

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

Cette intégration couvre les achats initiés sur le web et les synchronise avec l’accès à l’application mobile et les analytics, aux côtés des achats intégrés depuis les stores.

Elle est utile dans les cas suivants :

Centraliser les données d’abonnement des achats intégrés et des achats effectués sur votre site web dans un seul système
Accorder l’accès aux fonctionnalités payantes de votre application mobile aux utilisateurs qui ont acheté sur votre site web
Consulter les analytics et les données d’abonnement de tous vos 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, même si les applications peuvent encore être tenues de proposer des achats intégrés en parallèle. Consultez les directives App Store en vigueur pour votre région et catégorie d’application.

Note

Cette intégration porte sur le suivi et la synchronisation des achats web Paddle. Si vous devez rediriger des utilisateurs depuis 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 devrez :

Fournir vos clés API Paddle.
Ajouter l’URL webhook d’Adapty dans 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 au lieu de https://vendors.paddle.com/authentication-v2.

1.1. Obtenir et ajouter les clés API Paddle

Dans Paddle, allez dans 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, allez dans App Settings → Paddle et collez la clé dans la section Paddle API key.

Warning

Si vous avez défini 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 son expiration. L’intégration cessera de fonctionner sans avertissement à l’expiration de la clé, et les utilisateurs ne pourront plus effectuer d’achats.

1.2. Ajouter les événements à envoyer à Adapty

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

Saisissez un nom descriptif pour le webhook. Nous recommandons d’y inclure « Adapty » afin de le retrouver facilement si nécessaire.
Collez l’URL Webhook d’Adapty dans le champ URL. Veillez à 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, allez dans App Settings → Paddle et collez la clé dans le champ Notification secret key. Cette clé est utilisée pour vérifier les données webhook dans Adapty.

1.4. Associer les clients Paddle aux profils Adapty

Adapty doit lier chaque achat à un profil client pour pouvoir l’utiliser dans votre application. Par défaut, les profils sont créés automatiquement lorsqu’Adapty reçoit des webhooks de Paddle. Vous pouvez choisir quelle valeur utiliser comme customer_user_id dans Adapty :

Par défaut et recommandé : Le customer_user_id que vous transmettez 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 clients 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’ajouter un identifiant de produit Paddle à vos produits existants. Adapty ne suit que les événements pour les transactions liées à ces produits. Si vous sautez cette étape, aucun événement de transaction ne sera créé.

Paddle fonctionne dans Adapty comme l’App Store et Google Play — c’est 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 associer l’achat au bon utilisateur.

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

Pour que les utilisateurs qui achètent sur le web bénéficient de l’accès sur mobile, appelez Adapty.activate() ou Adapty.identify() avec le même customer_user_id que celui utilisé lors de l’achat. Consultez Identification des utilisateurs pour plus de détails.

4. Tester votre intégration

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

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

Considérations importantes

Dans les analytics d’Adapty, les montants des transactions incluent les taxes et les frais Paddle, ce qui diffère du tableau de bord Paddle où les montants sont affichés après taxes et frais. Les chiffres que vous verrez 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 spécifique remboursée et n’annulent pas automatiquement l’abonnement. L’abonnement restera actif à moins d’être 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 analytics.

Essais payants

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

Créez un produit non-abonnement et associez-le au prix Paddle qui facture la période d’essai.
Créez ensuite un produit d’abonnement (Mensuel/Hebdomadaire/etc.) et associez-le au prix Paddle qui comporte la composante d’essai gratuit.

Du point de vue de Paddle, il s’agit d’un seul produit avec deux prix dans une seule transaction — un prix pour la facturation de l’essai (par exemple, 0,99 $) et un autre 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, lorsqu’un utilisateur commence un essai payant à 0,99 $ pour un abonnement à 9,99 $/mois, Paddle crée une 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 $ (futur abonnement à 9,99 $/mois).

Note

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

Exploitez davantage 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 intégré à Paddle, Adapty est prêt à fournir des insights immédiatement. Pour tirer le meilleur parti de vos données Paddle, vous pouvez configurer des intégrations Adapty supplémentaires pour transférer les événements Paddle — en centralisant toutes vos analytics d’abonnement dans un seul Adapty Dashboard.

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

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 (similaire aux 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 après son expiration (suspension ou annulation de l’abonnement).

Essais : Si le prélèvement échoue après la fin d’un essai, le statut de l’abonnement passe à past_due. En production, Paddle Retain applique une fenêtre de relance pour tenter de récupérer le paiement avant d’annuler ou de suspendre l’abonnement. 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 via l’API server-side