Types d'événements webhook et champs
Adapty envoie des webhooks en réponse aux événements d’abonnement. Cette section définit ces types d’événements et les données contenues dans chaque webhook.
Types d’événements webhook
Vous pouvez envoyer tous les types d’événements à votre webhook ou n’en choisir que certains. Consultez nos Flux d’événements pour savoir quel type de données entrantes attendre et comment construire votre logique métier autour de ces données. Vous pouvez désactiver les types d’événements dont vous n’avez pas besoin lors de la configuration de votre intégration Webhook. Vous pouvez également y remplacer les ID d’événements Adapty par défaut par les vôtres si nécessaire.
| Nom de l’événement | Description |
|---|---|
| subscription_started | Déclenché lorsqu’un utilisateur active un abonnement payant sans période d’essai, c’est-à-dire qu’il est débité immédiatement. |
| subscription_active | Confirme que l’abonnement est toujours actif après l’événement subscription_started. Vous devez définir le nombre de jours entre le début de l’abonnement et cette vérification. L’événement arrive si l’abonnement est toujours actif, y compris lorsque l’utilisateur est entré dans un délai de grâce. Si l’abonnement a pris fin entretemps ou si l’utilisateur a désactivé le renouvellement automatique, rien n’arrive et Adapty ne vérifie plus. Cet événement ne suit que les abonnements achetés sans essai. Un essai qui se convertit envoie trial_converted, qui ne déclenche pas cette vérification. |
| subscription_renewed | Se produit lorsqu’un abonnement est renouvelé et que l’utilisateur est débité. Cet événement commence à partir du deuxième débit, qu’il s’agisse d’un abonnement avec ou sans essai. |
| subscription_renewal_cancelled | Un utilisateur a désactivé le renouvellement automatique de son abonnement. L’utilisateur conserve l’accès aux fonctionnalités premium jusqu’à la fin de la période d’abonnement payée. |
| subscription_renewal_reactivated | Déclenché lorsqu’un utilisateur réactive le renouvellement automatique de son abonnement. |
| subscription_expired | Déclenché lorsqu’un abonnement se termine complètement après avoir été annulé. Par exemple, si un utilisateur annule son abonnement le 12 décembre mais qu’il reste actif jusqu’au 31 décembre, l’événement est enregistré le 31 décembre à l’expiration de l’abonnement. |
| subscription_paused | Se produit lorsqu’un utilisateur active la pause d’abonnement (Android uniquement). |
| subscription_deferred | Déclenché lorsque vous prolongez l’abonnement d’un utilisateur sans frais : un report via l’API Google Play Developer, ou une extension de date de renouvellement via l’App Store Server API. L’utilisateur conserve l’accès aux fonctionnalités premium jusqu’à la date de renouvellement prolongée. |
| non_subscription_purchase | Tout achat hors abonnement, tel qu’un accès à vie ou des produits consommables comme des pièces de jeu. |
| trial_started | Déclenché lorsqu’un utilisateur active un abonnement d’essai. |
| trial_active | Confirme que l’essai est toujours actif après l’événement trial_started. Vous devez définir le nombre de jours entre le début de l’essai et cette vérification. L’événement arrive si l’essai est toujours en cours. Si l’essai a pris fin ou s’est converti entretemps, ou si l’utilisateur a désactivé le renouvellement automatique, rien n’arrive et Adapty ne vérifie plus. |
| trial_converted | Se produit lorsqu’un essai se termine et que l’utilisateur est débité (premier achat). Par exemple, si un utilisateur a un essai jusqu’au 14 janvier mais est débité le 7 janvier, cet événement est enregistré le 7 janvier. |
| trial_renewal_cancelled | Un utilisateur a désactivé le renouvellement automatique de l’abonnement pendant la période d’essai. L’utilisateur conserve l’accès aux fonctionnalités premium jusqu’à la fin de l’essai, mais ne sera pas débité et ne démarrera pas d’abonnement. |
| trial_renewal_reactivated | Se produit lorsqu’un utilisateur réactive le renouvellement automatique de l’abonnement pendant la période d’essai. |
| trial_expired | Déclenché lorsqu’un essai se termine sans se convertir en abonnement. |
| entered_grace_period | Se produit lorsqu’une tentative de paiement échoue et que l’utilisateur entre dans un délai de grâce (si activé). L’utilisateur conserve l’accès premium pendant cette période. |
| billing_issue_detected | Déclenché lorsqu’un problème de facturation survient lors d’une tentative de débit (par exemple, solde de carte insuffisant). |
| subscription_refunded | Déclenché lorsqu’un abonnement est remboursé (par exemple, par le support Apple). |
| non_subscription_purchase_refunded | Déclenché lorsqu’un achat hors abonnement est remboursé. |
| access_level_updated | Se produit lorsque le niveau d’accès d’un utilisateur est mis à jour. |
subscription_renewal_reactivated contient l’identifiant du produit précédent — celui qui était actif au moment où l’utilisateur a annulé — même si l’utilisateur a ensuite réactivé son abonnement en achetant un produit différent. Apple conserve le même original_transaction_id tout au long de la chaîne annulation → réactivation, de sorte que cet événement reflète le produit d’origine. Le nouveau produit apparaît dans le prochain événement subscription_renewed, lorsque la facturation du nouveau produit commence.
Sur Google Play, Adapty peut envoyer un événement subscription_started avec tous les champs monétaires à zéro — par exemple, lorsque Google remplace un abonnement par un autre ou lorsque l’abonnement débute par une phase sans frais. Ne comptez pas ces événements comme du chiffre d’affaires. Lorsque Google remplace un abonnement, il émet un nouveau token d’achat, de sorte qu’Adapty rapporte la transaction payante sous un store_transaction_id différent.
Structure des événements webhook
Adapty vous enverra uniquement les événements que vous avez sélectionnés dans la section Events names de la page Integrations -> Webhooks.
Les événements webhook sont sérialisés en JSON. Le corps d’une requête POST envoyée à votre serveur contiendra l’événement sérialisé dans la structure ci-dessous. Tous les événements suivent la même structure, mais leurs champs varient selon le type d’événement, le store et votre configuration spécifique. Les attributs utilisateur correspondent aux attributs utilisateur personnalisés que vous avez définis, ils contiennent donc ce que vous avez configuré. Les champs de données d’attribution sont identiques pour tous les types d’événements, mais la liste des attributions dépend des sources d’attribution que vous utilisez dans votre application mobile. Voici un exemple d’événement :
{
"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
}
}
Champs d’événement
Les paramètres d’événement sont identiques pour tous les types d’événements.
| Champ | Type | Description |
|---|---|---|
| advertising_id | UUID | Advertising ID (Android uniquement). |
| attributions | JSON | Données d’attribution. Inclus si Send Attribution est activé dans les paramètres du Webhook. |
| customer_user_id | String | ID utilisateur de votre application (UUID, e-mail ou autre identifiant) si vous l’avez défini dans le code de votre application lors de l’identification des utilisateurs. Si vous n’identifiez pas les utilisateurs dans le code de l’application ou si cet utilisateur est anonyme (non connecté), ce champ vaut null. |
| String | E-mail de l’utilisateur si vous l’avez défini via la méthode updateProfile du SDK Adapty ou lors de la création/mise à jour de profils via l’API server-side. Si vous ne transmettez pas la valeur email au SDK ou à la méthode API, ce champ vaut null. | |
| event_api_version | Integer | Version de l’API Adapty (actuelle : 1). |
| event_datetime | ISO 8601 | L’heure effective (métier) de l’événement — par exemple la date d’achat pour un achat ou la date d’expiration pour une expiration — et non le moment où Adapty a reçu ou envoyé l’événement. Format ISO 8601 (ex. : 2020-07-10T15:00:00.000000+0000). Voir la note ci-dessous sur l’ordre des événements. |
| event_properties | JSON | Propriétés de l’événement. |
| event_type | String | Nom de l’événement au format Adapty. Consultez les types d’événements Webhook pour la liste complète. |
| idfa | UUID | Advertising ID (Apple uniquement). IDFA dans le profil sur l’Adapty Dashboard. Peut être null si indisponible en raison de restrictions de suivi, du mode enfant ou des paramètres de confidentialité. |
| idfv | UUID | Identifier for Vendors (IDFV), unique par développeur. IDFV dans le profil sur l’Adapty Dashboard. |
| integration_ids | JSON | IDs d’intégration utilisateur si vous les avez définis via la méthode setIntegrationIdentifier du SDK Adapty ou lors de la création/mise à jour de profils via l’API server-side. Vaut null si indisponible ou si les intégrations sont désactivées. |
| play_store_purchase_token | JSON | Token d’achat Play Store, inclus si Send Play Store purchase token est activé dans les paramètres du Webhook. |
| profile_id | UUID | ID de profil généré automatiquement par Adapty pour chaque profil. Un même identifiant Apple/Google peut être associé à différents IDs de profil si vous n’identifiez pas les utilisateurs ou autorisez les achats avant la connexion. En savoir plus sur la façon dont Adapty gère les profils parent/héritier. |
| profile_install_datetime | ISO 8601 | Horodatage d’installation au format ISO 8601 (ex. : 2020-07-10T15:00:00.000000+0000). |
| profiles_sharing_access_level | JSON | Liste des utilisateurs partageant le niveau d’accès, à l’exclusion du profil utilisateur actuel. Si le partage des niveaux d’accès est activé pour votre application, cette liste inclut les autres profils associés au même identifiant Apple/Google. Format :
|
| user_agent | String | User-agent du navigateur de l’appareil. |
| user_attributes | JSON | Données personnalisées que vous pouvez définir pour enrichir les profils utilisateurs avec des informations propres à l’application. Généralement utilisées pour suivre les préférences (ex. : thème, langue) ou des indicateurs comportementaux (onboarding terminé, utilisation de fonctionnalités). Formatées sous forme de paires clé-valeur où les clés sont des chaînes et les valeurs peuvent être des chaînes ou des nombres (ex. : {"Favourite_color": "Violet", "Pet_name": "Fluffy"}). Vous pouvez définir des attributs personnalisés manuellement dans l’Adapty Dashboard pour des profils individuels, par programmation via la méthode updateProfile du SDK Adapty, ou via l’API server-side lors de la création/mise à jour de profils. Inclus si Send User Attributes est activé dans les paramètres du Webhook. Bien que les valeurs d’attributs personnalisés dans le code de l’application mobile puissent être définies en tant que flottants ou chaînes, les attributs reçus via l’API server-side ou une importation historique peuvent arriver dans des formats différents. Les valeurs booléennes et entières seront alors converties en flottants. |
event_datetime reflète le moment où un événement s’est produit dans le cycle de vie de l’abonnement, et non le moment où Adapty l’a traité ou transmis. Pour cette raison, des événements peuvent partager le même event_datetime ou arriver dans le désordre chronologique. Par exemple, un événement subscription_expired peut avoir un event_datetime antérieur à celui d’un événement subscription_renewal_cancelled qu’Adapty lui transmet avant. Ne vous fiez pas à event_datetime pour ordonner les événements. Ordonnez-les plutôt selon votre propre heure de réception, et dédoublonnez-les à l’aide de profile_event_id ou des identifiants de transaction.
Attributions
Pour envoyer les données d’attribution, activez l’option Send Attribution sur la page Integrations -> Webhooks. Si vous avez activé l’envoi des données d’attribution et configuré des intégrations d’attribution, les données ci-dessous seront envoyées avec l’événement pour chaque source. Les mêmes données d’attribution sont envoyées pour tous les types d’événements.
{
"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"
}
}
}
| Nom du champ | Type de champ | Description |
|---|---|---|
| ad_set | String | Ensemble d’annonces d’attribution. |
| status | String | Peut être organic, non_organic, ou unknown. |
| channel | String | Nom du canal marketing. |
| ad_group | String | Groupe d’annonces d’attribution. |
| campaign | String | Nom de la campagne marketing. |
| creative | String | Mot-clé créatif d’attribution. |
| created_at | ISO 8601 date | Date et heure de création de l’enregistrement d’attribution. |
| network_user_id | String | ID attribué à l’utilisateur par la source d’attribution. |
Identifiants d’intégration
Les identifiants d’intégration suivants sont désormais utilisés dans les événements :
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
Jeton d’achat Play Store
Ce champ contient toutes les données nécessaires pour revalider un achat, si besoin. Il n’est envoyé que si l’option Send Play Store purchase token est activée dans les paramètres de l’intégration Webhook.
| Field | Type | Description |
|---|---|---|
| product_id | String | L’identifiant unique du produit (SKU) acheté sur le Play Store. |
| purchase_token | String | Un token généré par Google Play pour identifier de manière unique cette transaction d’achat. |
| is_subscription | Boolean | Indique si le produit acheté est un abonnement (true) ou un achat unique (false). |
Propriétés des événements
Les propriétés des événements peuvent varier selon le type d’événement, et même entre des événements du même type. Par exemple, un événement provenant de l’App Store ne comportera pas les propriétés spécifiques à Android comme base_plan_id.
L’événement Niveau d’accès mis à jour possède des propriétés distinctes, c’est pourquoi nous lui avons consacré une section séparée. De même, nous avons séparé les Propriétés fiscales et de revenus supplémentaires, car elles sont spécifiques à certains types d’événements seulement.
Pour la plupart des types d’événements
Les propriétés d’événement sont cohérentes pour la plupart des types d’événements (à l’exception de l’événement Access Level Updated, décrit dans sa propre section). Voici un tableau complet des propriétés, indiquant celles qui s’appliquent à des événements spécifiques.
Adapty convertit les autres devises en USD au taux de change de currencylayer.com (actualisé toutes les 8 heures). Le taux est fixé au moment de la transaction — les variations ultérieures n’affectent pas le résultat de la conversion.
| Champ | Type | Description |
|---|---|---|
| ab_test_id | UUID | ID du test A/B Adapty d’où provient la transaction. Pour un test A/B cross-placement, c’est l’ID du test cross-placement, identique sur chaque placement. Voir Champs flow et test A/B. |
| ab_test_name | String | Nom du test A/B Adapty d’où provient la transaction. Pour un test A/B cross-placement, il s’agit du nom du test sur un placement, au format <test name> child-N, où N est le numéro du placement et non de la variante. Pour regrouper un test cross-placement sur tous les placements, utilisez ab_test_id et récupérez son nom depuis ab_test_parent_name. |
| ab_test_parent_name | String | Nom du test A/B cross-placement d’où provient la transaction. Présent uniquement pour les tests A/B cross-placement. |
| ab_test_revision | Integer | Révision du test A/B d’où provient la transaction. |
| ab_test_variant_id | UUID | ID de la variante du test A/B d’où provient la transaction. Dans un test A/B de paywall classique, correspond à variation_id. Dans un test A/B de flow, correspond à flow_variation_id. Dans un test A/B cross-placement, il est identique pour la variante sur chaque placement. Utilisez-le pour répartir les transactions par variante de test. |
| ab_test_variant_name | String | Nom de la variante du test A/B. Pour un test A/B cross-placement, nom de la variante défini dans les paramètres du test. Pour les autres tests, nom de la variante, ou nom du paywall ou du flow si la variante n’a pas de nom. Présent avec ab_test_variant_id. |
| base_plan_id | String | ID du plan de base sur le Google Play Store ou ID de prix sur Stripe. |
| cancellation_reason | String | Raisons possibles d’annulation : Présent dans les types d’événements suivants : subscription_cancelled, subscription_refunded et trial_cancelled. |
| cohort_name | String | Le nom de l’audience qui a déterminé quel paywall a été affiché à l’utilisateur. |
| consecutive_payments | Integer | Le nombre de périodes pendant lesquelles un utilisateur est abonné sans interruption. Inclut la période en cours. |
| currency | String | Devise locale. null dans trial_started sauf si Send trial price est activé. Voir Propriétés supplémentaires des événements de taxe et de revenus. |
| developer_id | String | L’ID du placement d’où provient la transaction. |
| discount_amount_local | Float | La remise appliquée à la transaction : le prix standard moins le montant réellement facturé, avant la commission Apple/Google, en devise locale. 0 pour un achat au prix plein. Pour un essai gratuit, égal au prix standard complet (original_price_local), puisque rien n’est facturé. null lorsqu’une offre a été appliquée mais que le prix standard est inconnu (voir original_price_local). Toujours null pour les offres pay-up-front de l’App Store : le paiement unique couvre plusieurs périodes de facturation et ne peut donc pas être comparé au prix standard par période. |
| discount_amount_usd | Float | La valeur de discount_amount_local en USD. |
| environment | String | Les valeurs possibles sont Sandbox ou Production. |
| event_datetime | ISO 8601 date | La date et l’heure de l’événement. Identique au niveau racine de l’événement. |
| flow_id | UUID | ID du flow d’où provient la transaction. Présent pour toute transaction effectuée dans un flow, qu’elle soit dans un test A/B ou non. |
| flow_name | String | Nom du flow d’où provient la transaction. Présent avec flow_id. |
| flow_variation_id | UUID | ID de la variante du flow sur ce placement. Valeur identique à celle que le SDK renvoie à l’application via flow.variationId. Présent avec flow_id. |
| original_price_local | Float | Le prix standard non remisé du produit avant la commission Apple/Google, en devise locale. Pour les abonnements, il s’agit du prix de renouvellement. Égal à price_local pour un achat au prix plein et toujours égal à price_local pour les achats uniques, car les stores ne communiquent pas de prix standard séparé pour ceux-ci. null pour un achat remisé lorsque le store ne fournit pas de prix standard fiable (par exemple, le renouvellement automatique est désactivé, le renouvellement porte encore une offre, ou un changement de produit est en attente). |
| original_price_usd | Float | Identique à original_price_local, en USD. |
| original_purchase_date | ISO 8601 date | Pour les abonnements récurrents, l’achat original est la première transaction de la chaîne, dont l’ID — appelé ID de transaction original — relie toute la chaîne de renouvellements ; les transactions suivantes en sont des prolongements. La date d’achat original est la date et l’heure de cette première transaction. |
| original_transaction_id | String | Pour les abonnements récurrents, il s’agit de l’ID de transaction original qui relie la chaîne de renouvellements. La transaction originale est la première de la chaîne ; les transactions suivantes en sont des prolongements. En l’absence de prolongements, |
| paywall_name | String | Nom du paywall d’où provient la transaction. Pour un flow, il s’agit de l’ID de l’écran paywall à l’intérieur du flow (scr_...) et non d’un nom. Le nom du flow se trouve dans flow_name. |
| paywall_revision | String | Révision du paywall d’où provient la transaction. La valeur par défaut est 1. |
| price_local | Float | Le montant facturé pour la transaction avant la commission Apple/Google, en devise locale. null dans trial_started, puisque rien n’est facturé, sauf si Send trial price est activé. |
| price_usd | Float | Le montant facturé pour la transaction avant la commission Apple/Google, en USD. null dans trial_started, puisque rien n’est facturé, sauf si Send trial price est activé. |
| profile_country | String | Déterminé par Adapty, sur la base de l’IP du profil. |
| profile_event_id | UUID | ID d’événement unique pouvant être utilisé pour la déduplication. |
| profile_has_access_level | Boolean | Booléen indiquant si le profil possède un niveau d’accès actif. |
| profile_id | UUID | ID de profil généré par Adapty. Identique au niveau racine de l’événement. |
| profile_ip_address | String | IP du profil (peut être IPv4 ou IPv6, avec préférence pour IPv4 si disponible). null si Collect users’ IP addresses est désactivé dans les paramètres de l’application. |
| profile_total_revenue_usd | Float | Revenus totaux du profil, remboursements déduits. |
| promotional_offer_id | String | L’ID Adapty de l’offre promotionnelle utilisée. Vous définissez cet ID lors de la création d’une offre dans le tableau de bord. |
| purchase_date | ISO 8601 date | La date et l’heure de l’achat du produit. |
| rate_after_first_year | Boolean | Booléen indiquant que l’abonnement est éligible à un taux de commission réduit (généralement 15 %) après un an de renouvellement continu. Les taux de commission varient selon l’éligibilité au programme et le pays. Voir Commission du store et taxes pour plus de détails. |
| store | String | Store où le produit a été acheté. Valeurs standard : app_store, play_store, stripe, paddle. Si vous configurez des transactions de store personnalisées via l’API côté serveur, la valeur du paramètre store est utilisée. |
| store_country | String | Le pays transmis par le store. |
| store_offer_category | String | Catégorie d’offre appliquée. Les valeurs possibles sont introductory, promotional, winback. |
| store_offer_discount_type | String | Type d’offre appliqué. Les valeurs possibles sont free_trial, pay_as_you_go et pay_up_front. |
| store_offer_number_of_periods | Integer | Nombre de périodes de facturation de base remisées par l’offre (1 ou plus). Présent uniquement lorsqu’une offre est appliquée. null pour les offres pay-up-front de l’App Store et lorsque le store ne communique pas la durée de l’offre. |
| subscription_expires_at | ISO 8601 date | La date d’expiration de l’abonnement. Dans les événements de remboursement, de problème de facturation, de délai de grâce et de niveau d’accès, contient la date d’annulation ou la date de fin du délai de grâce le cas échéant. Dans les événements d’achat et de renouvellement, contient la date d’expiration normale de l’abonnement. |
| transaction_id | String | Identifiant unique d’une transaction. |
| trial_duration | String | Durée de la période d’essai en jours. Envoyée au format ” days”, par exemple “7 days”. Présent uniquement dans les types d’événements liés aux essais : trial_started, trial_converted, trial_cancelled. |
| variation_id | UUID | ID unique du paywall où l’achat a été effectué. Pour un flow, il s’agit de l’ID de l’écran paywall à l’intérieur du flow, et non de la variante du test A/B. Chaque version publiée d’un flow reçoit de nouveaux ID d’écran, de sorte qu’Adapty envoie une seule variante avec des valeurs variation_id différentes au fil du temps. Pour répartir les transactions par variante de test, utilisez ab_test_variant_id. |
| vendor_product_id | String | ID du produit sur l’Apple App Store, le Google Play Store ou Stripe. Pour un engagement 12 mois, la valeur est Si l’accès a été accordé sans transaction réelle en store,
|
Champs du flow et du test A/B
Les champs du flow et du test A/B indiquent de quel flow, test A/B et variante provient une transaction. Ils fonctionnent pour tous les types de test A/B : tests A/B standard sur les paywalls et les flows, ainsi que les tests A/B inter-placements sur les paywalls et les flows.
Adapty envoie ces champs dans les événements d’une transaction effectuée sur un placement, les mêmes événements qui transportent developer_id et variation_id. Les renouvellements, remboursements, annulations et autres événements d’abonnement conservent le même flow, test A/B et variante que l’achat d’origine, même après l’arrêt du test A/B. Lorsqu’un champ n’a pas de valeur, l’événement ne l’inclut pas : ces champs ne sont jamais vides ni null.
| Source de transaction | flow_id, flow_name, flow_variation_id | ab_test_id | ab_test_variant_id, ab_test_variant_name | ab_test_parent_name |
|---|---|---|---|---|
| Test A/B de paywall classique | — | ID du test A/B | Correspond à variation_id | — |
| Paywall hors test A/B | — | — | — | — |
| Test A/B de flow | ✅ | ID du test A/B | Correspond à flow_variation_id | — |
| Flow hors test A/B | ✅ | — | — | — |
| Test A/B crossplacement sur des paywalls | — | ID du test crossplacement | Partagé par tous les placements | ✅ |
| Test A/B crossplacement sur des flows | ✅, avec la variante du flow sur ce placement | ID du test crossplacement | Partagé par tous les placements | ✅ |
| Hors placement | — | — | — | — |
Par exemple, pour un achat dans la variante A sur le deuxième placement d’un test A/B multiplacements sur des flows, Adapty envoie :
{
"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"
}
Pour créer des rapports sur ces champs, regroupez les transactions par identifiants (ab_test_id, ab_test_variant_id, flow_id) et utilisez les noms comme libellés. Adapty récupère les noms au moment où il envoie l’événement, donc si vous renommez un test, une variante ou un flow, les événements ultérieurs porteront le nouveau nom. Les événements déjà envoyés ne sont ni renvoyés ni mis à jour.
L’identifiant de variante partagé d’un test A/B multi-placement ne correspond à l’identifiant de variante que sur un seul placement, généralement le premier. Pour associer un événement à la variante renvoyée par le SDK sur un placement spécifique, utilisez flow_variation_id ou variation_id.
Dans un test A/B multi-placement où le même flow apparaît dans plusieurs variantes, l’achat seul ne permet pas de déterminer dans quelle variante se trouvait l’utilisateur. Adapty récupère la variante depuis l’enregistrement d’affectation de l’utilisateur. Si cet enregistrement n’est pas disponible, Adapty envoie flow_id, flow_name et ab_test_id, mais pas flow_variation_id, ab_test_variant_id ni ab_test_variant_name. Cela se produit lorsque l’utilisateur achète juste après avoir vu le flow, avant que l’enregistrement soit sauvegardé, et pour les renouvellements qui interviennent après l’expiration de l’enregistrement. L’Adapty Dashboard comptabilise ces transactions dans la première variante, ce qui peut créer des écarts entre vos données d’intégration et le tableau de bord.
Propriétés d’événement supplémentaires liées aux taxes et aux revenus
Les propriétés d’événement liées aux taxes et aux revenus ci-dessous sont des champs supplémentaires qui s’appliquent uniquement à certains types d’événements. Cela signifie que les types d’événements listés incluent les Propriétés d’événement pour la plupart des types d’événements, ainsi que les champs supplémentaires listés ci-dessous.
Types d’événements ayant les propriétés d’événement liées aux taxes et aux revenus :
subscription_renewedsubscription_initial_purchase(également appelésubscription_started— même événement)subscription_refundednon_subscription_purchasenon_subscription_purchase_refundedtrial_startedtrial_converted
| Champ | Type | Description |
|---|---|---|
| net_revenue_local | Float | Revenu net (revenu après commission Apple/Google et taxes) en devise locale. |
| net_revenue_usd | Float | Revenu net (revenu après commission Apple/Google et taxes) en USD. |
| proceeds_local | Float | price_local après commission Apple/Google. |
| proceeds_usd | Float | price_usd après commission Apple/Google. |
| tax_amount_local | Float | Taxe estimée incluse dans price_local. 0 pour Stripe et Paddle, même si l’utilisateur a payé des taxes. |
| tax_amount_usd | Float | Taxe estimée incluse dans price_usd. 0 pour Stripe et Paddle, même si l’utilisateur a payé des taxes. |
Pour le revenu net, utilisez directement net_revenue_*. Sauf si tax_amount_* est 0, proceeds_* moins tax_amount_* donne un montant inférieur. Par exemple, avec un prix de 12, une commission de 30 % et un taux de taxe de 20 %, Adapty calcule :
proceeds_*=price_*× (1 − commission) = 12 × 0.7 = 8.40tax_amount_*=price_*× taux de taxe ÷ (1 + taux de taxe) = 12 × 0.2 ÷ 1.2 = 2.00net_revenue_*=proceeds_*÷ (1 + taux de taxe) = 8.40 ÷ 1.2 = 7.00
Une période d’essai gratuit ne facture rien, donc dans trial_started, les champs de prix (price_*, proceeds_*, net_revenue_*, tax_amount_*) et currency sont null par défaut. Pour les recevoir, activez Send trial price dans les paramètres du webhook. Adapty les calcule alors à partir du prix de l’abonnement multiplié par Trial price percentage, et envoie currency. Ces valeurs décrivent l’abonnement, pas un débit, donc n’incluez pas trial_started dans les totaux de revenus.
Exemple de payload non_subscription_purchase
non_subscription_purchase suit la même structure que les événements d’abonnement, mais reflète un achat unique ou consommable. Les champs propres aux abonnements ne s’appliquent pas : cancellation_reason, will_renew, is_in_grace_period, is_refund, is_lifetime et trial_duration sont absents. subscription_expires_at est présent mais vaut null. Les champs de taxes et revenus (net_revenue_*, proceeds_*, tax_amount_*) sont inclus.
Exemple de payload (cliquer pour développer)
{
"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
} Pour l’événement Access Level Updated
L’événement Access Level Updated est un événement webhook spécifique, généré uniquement lorsque l’intégration Webhook est active et que ce type d’événement est activé. S’il est activé, il est envoyé au Webhook configuré et apparaît dans l’Event Feed. S’il n’est pas activé, l’événement ne sera pas créé.
Si vous avez activé le partage des niveaux d’accès, l’événement access level updated sera envoyé pour tous les profils partageant le niveau d’accès.
Utilisez cet événement pour mettre à jour le niveau d’accès de l’utilisateur dans votre base de données, accorder ou révoquer les fonctionnalités premium sur votre backend, et synchroniser les accès sur tous les appareils ou plateformes.
| Propriété | Type | Description |
|---|---|---|
| ab_test_id | UUID | ID du test A/B dont est issue la transaction. Voir Champs flow et test A/B. |
| ab_test_name | String | Nom du test A/B dont est issue la transaction. Pour un test A/B multi-placement, nom du test sur un placement (<test name> child-N). |
| ab_test_parent_name | String | Nom du test A/B multi-placement. Présent uniquement pour les tests A/B multi-placements. |
| ab_test_variant_id | UUID | ID de la variante du test A/B dont est issue la transaction. |
| ab_test_variant_name | String | Nom de la variante du test A/B. |
| access_level_id | String | L’ID du niveau d’accès. |
| activated_at | ISO 8601 date | Date et heure de la dernière activation de l’accès. |
| active_introductory_offer_type | String | Type d’offre de lancement appliquée. Valeurs possibles : free_trial, pay_as_you_go et pay_up_front. |
| active_promotional_offer_id | String | ID de l’offre promotionnelle tel qu’indiqué dans la section Produit de l’Adapty Dashboard |
| active_promotional_offer_type | String | Type d’offre promotionnelle appliquée. Valeurs possibles : free_trial, pay_as_you_go et pay_up_front. |
| base_plan_id | String | ID du plan de base dans le Google Play Store ou ID de prix dans Stripe. |
| billing_issue_detected_at | ISO 8601 date | Date et heure du problème de facturation. |
| cancellation_reason | String | Raisons possibles d’annulation : voluntarily_cancelled, billing_error, price_increase, product_was_not_available, refund, cancelled_by_developer, new_subscription_replace, upgraded, unknown, adapty_revoked. |
| cohort_name | String | Nom de l’audience à laquelle appartient le profil. |
| currency | String | Devise locale (USD par défaut). |
| developer_id | String | L’ID du placement dont est issue la transaction. |
| environment | String | Valeurs possibles : Sandbox ou Production. |
| event_datetime | ISO 8601 date | La date et l’heure de l’événement. |
| expires_at | ISO 8601 date | Date et heure d’expiration de l’accès. Adapty calcule Pendant un délai de grâce, ce champ contient la fin du délai de grâce ; après un remboursement ou une annulation, il contient la date d’annulation. Il n’existe pas de champ distinct pour la fin du délai de grâce. |
| flow_id | UUID | ID du flow dont est issue la transaction. |
| flow_name | String | Nom du flow dont est issue la transaction. |
| flow_variation_id | UUID | ID de la variante du flow sur ce placement, identique à flow.variationId dans le SDK. |
| is_active | Boolean | Booléen indiquant si le niveau d’accès est actif. Calculé à partir de expires_at (avec starts_at et is_lifetime) lors de la génération de l’événement. |
| is_in_grace_period | Boolean | Booléen indiquant si le profil est en délai de grâce. Quand true, expires_at contient la fin du délai de grâce. |
| is_lifetime | Boolean | Booléen indiquant si le niveau d’accès est à vie. |
| is_refund | Boolean | Booléen indiquant si la transaction est un remboursement. |
| original_purchase_date | ISO 8601 date | Pour les abonnements récurrents, l’achat original est la première transaction de la chaîne, dont l’ID — appelé ID de transaction original — relie la chaîne de renouvellements ; les transactions ultérieures en sont des extensions. La date d’achat original est la date et l’heure de cette première transaction. |
| original_transaction_id | String | Pour les abonnements récurrents, il s’agit de l’ID de transaction original qui relie la chaîne de renouvellements. La transaction originale est la première de la chaîne ; les transactions ultérieures en sont des extensions. Sans extensions, |
| paywall_name | String | Nom du paywall dont est issue la transaction. Pour un flow, l’ID de l’écran paywall (scr_...). |
| paywall_revision | String | Révision du paywall dont est issue la transaction. La valeur par défaut est 1. |
| profile_country | String | Déterminé par Adapty, d’après l’IP du profil. |
| profile_event_id | UUID | ID d’événement unique utilisable pour la déduplication. |
| profile_has_access_level | Boolean | Booléen indiquant si le profil dispose d’un niveau d’accès actif. |
| profile_id | UUID | ID de profil utilisateur interne Adapty. |
| profile_ip_address | String | IP du profil (IPv4 ou IPv6, IPv4 privilégiée si disponible). null si Collect users’ IP addresses est désactivé dans les paramètres de l’app. |
| profile_total_revenue_usd | Float | Revenu total du profil, remboursements inclus. |
| purchase_date | ISO 8601 date | La date et l’heure d’achat du produit. |
| renewed_at | ISO 8601 date | Date et heure du début de la période d’accès payant en cours. Avant le premier renouvellement, cette valeur correspond à activated_at. |
| starts_at | ISO 8601 date | Date et heure de début du niveau d’accès. |
| store | String | Store où le produit a été acheté. Valeurs standard : app_store, play_store, stripe, paddle. Si vous configurez des transactions de store personnalisées via l’API côté serveur, la valeur du paramètre store est utilisée. |
| store_country | String | Pays transmis à Adapty par le store. |
| subscription_expires_at | ISO 8601 date | La date d’expiration de l’abonnement. Dans cet événement, elle contient la même valeur que expires_at : pendant un délai de grâce, la fin du délai de grâce ; après un remboursement ou une annulation, la date d’annulation. |
| transaction_id | String | Identifiant unique d’une transaction. |
| trial_duration | String | Durée de la période d’essai en jours (ex. : « 7 days »). |
| variation_id | UUID | Identifiant d’une variante, utilisé pour attribuer les achats à ce paywall. Pour un flow, l’ID de l’écran paywall dans le flow, et non la variante du test A/B. |
| vendor_product_id | String | ID du produit dans le store (Apple/Google/Stripe). Pour un plan d’engagement de 12 mois, la valeur est Si l’accès a été accordé sans transaction réelle dans le store,
|
| will_renew | Boolean | Indique si le niveau d’accès payant sera renouvelé. |
Notez que cette structure peut évoluer dans le temps — de nouvelles données pouvant être introduites par nous ou par les tiers avec lesquels nous travaillons. Assurez-vous que votre code qui la traite est suffisamment robuste et repose sur des champs spécifiques plutôt que sur la structure entière.