Découvrez les API serveur de l’App Store pour les achats intégrés

Bonjour, je suis Riyaz, ingénieur dans l’équipe serveur de l’App Store. Cette séance couvrira les API du serveur de l’App Store pour les achats intégrés. Je présenterai nos mises à jour, conçues pour rationaliser et améliorer les responsabilités de votre serveur d’apps. Commençons par explorer certaines responsabilités clés de votre serveur d’apps. Cette séance couvrira trois responsabilités essentielles.

En premier, la gestion des achats intégrés. Il s’agit d’associer les données de transaction à vos comptes clients pour que votre app fournisse du contenu et des services de façon fluide.

Ensuite, la signature des demandes. Il s’agit de générer une signature pour autoriser les demandes de votre serveur auprès de l’App Store.

Enfin, la participation aux décisions de remboursement. En partageant les données de consommation sur les achats, votre serveur peut aider l’App Store à mieux gérer les remboursements. Il s’agit là de quelques-unes des responsabilités cruciales gérées par votre serveur d’apps. Ensuite, nous verrons comment les mises à jour de l’API du serveur de l’App Store renforcent ces responsabilités. Il y a beaucoup à voir, alors entrons dans le vif du sujet. Tout d’abord, j’aborderai les mises à jour des ID de transaction pour améliorer la gestion des achats intégrés. Ensuite, j’examinerai les améliorations visant à simplifier les demandes de signature sur votre serveur. Enfin, j’évoquerai votre participation simplifiée aux processus de remboursement.

Entrons dans les détails, en commençant par la gestion des achats intégrés. La gestion des achats intégrés commence par une gestion efficace des comptes clients sur votre système.

En général, vous attribuez à chaque client un ID de compte unique sur votre système, créant ainsi un lien clair entre leurs comptes et les transactions de l’App Store. Cette association est cruciale pour fournir le bon contenu ou personnaliser l’expérience utilisateur. L’App Store fournit des données sur les achats intégrés via trois structures de données clés : AppTransaction, JWSTransaction et JWSRenewalInfo.

Commençons par JWSTransaction. Nous verrons les autres plus tard.

Lorsqu’un client effectue un achat intégré, l’App Store fournit un objet de transaction signé. Sur le serveur, JWSTransaction affiche cette transaction signée, que vous pouvez vérifier et décoder à l’aide de la bibliothèque du serveur de l’App Store.

Voici un exemple de signedTransactionInfo décodé.

Les premiers champs contiennent des infos importantes sur l’app et le type de produit intégré. Ensuite viennent les métadonnées sur l’achat, dont la quantité, le prix et la devise. Si un client utilise une offre, la structure JWSTransaction inclut des champs pour offerType, offerIdentifier et offerDiscountType. Nous avons récemment ajouté le nouveau champ offerPeriod, qui indique la durée de l’offre utilisée, au format de durée ISO 8601. Ce champ figure également dans JWSRenewalInfo et indique la durée de l’offre valable au moment du renouvellement de l’abonnement.

Ensuite, il y a les identifiants de transaction. transactionId est l’ID unique d’une transaction de type achat intégré, restauration ou renouvellement d’abonnement. Dans cet exemple, c’est l’ID de transaction du renouvellement d’abonnement.

originalTransactionId est l’ID de transaction de l’achat d’origine. Il vous aide à identifier précisément les abonnements à renouvellement automatique, car il perdure d’un renouvellement à l’autre.

Enfin, appAccountToken, qui est un UUID défini par vous dans votre app via StoreKit lorsqu’un client effectue un achat intégré. Ce champ vous permet d’associer l’achat au compte du client dans votre système. Pour faciliter l’obtention d’appAccountToken lors des renouvellements, ce champ a été inclus dans JWSRenewalInfo. Vous pourrez ainsi facilement associer vos comptes clients à leurs transactions récentes de renouvellement d’abonnement. Je vous explique comment cela fonctionne. Vous commencez par générer un UUID sur votre serveur, et associez cette valeur à votre compte client. Ensuite, votre serveur transmet cette valeur à votre app créée avec StoreKit. pour définir l’appAccountToken au moment de l’achat intégré. Nous conseillons d’utiliser le même appAccountToken pour tous les achats intégrés d’un compte client donné. Le serveur de l’App Store renvoie cette valeur appAccountToken dans les infos de transaction et de renouvellement JWS. Auparavant, vous pouviez définir l’appAccountToken lors d’achats effectués dans l’app. Mais les clients peuvent aussi faire des achats en dehors de votre app, en utilisant des codes d’offre ou lors des achats promotionnels dans l’App Store. Pour définir plus facilement l’appAccountToken en pareil cas, nous avons un nouveau point de terminaison de serveur. Utilisez le point de terminaison Définir le jeton de compte d’app pour définir/mettre à jour un appAccountToken pour une transaction. Ce point de terminaison s’applique à tous types de produits. Cela inclut les achats ponctuels passés (produits consommables, non-consommables et sans abonnements renouvelables), ainsi que le dernier achat de chaque abonnement à renouvellement automatique. Pour les abonnements à renouvellement automatique, l’appAccountToken défini avec ce point est transféré aux renouvellements futurs, y compris les mises à niveau amont et aval.

Le point de terminaison Définir le jeton de compte d’app est utile quand un client effectue une transaction hors de votre app, comme l’utilisation d’un code d’offre. Auparavant, il n’y avait aucun moyen de définir le champ appAccountToken pour ces achats, puisque StoreKit n’était pas utilisé. En outre, vous pouvez corriger les incohérences en liant l’appAccountToken aux comptes clients, notamment quand la propriété du compte change dans votre système. Voyons le point de terminaison, qui fait partie de l’API du serveur de l’App Store.

Voici comment utiliser le point de terminaison Définir le jeton de compte d’app. Indiquez le TransactionId d’origine dans le chemin d’accès. Cette valeur identifie soit la transaction d’achat unique, soit l’abonnement pour lequel vous souhaitez définir l’appAccountToken.

Dans le corps de la demande, définissez une valeur UUID pour l’appAccountToken. L’appAccountToken fourni avec le point de terminaison Définir le jeton de compte d’app remplace tout appAccountToken précédent défini pour cette transaction. L’appAccountToken, et d’autres ID de transaction comme transactionId et originalTransactionId, permettent d’associer des comptes clients aux transactions de l’App Store. Voici un bref aperçu de ces identifiants. L’App Store est la source de transactionId et originalTransactionId, tandis que vous êtes responsable de la création et de l’association de l’appAccountToken à une transaction de l’App Store. Le transactionId est utile pour identifier un événement d’achat spécifique. L’originalTransactionId est idéal pour gérer le cycle de vie des abonnements à renouvellement automatique dans un seul groupe d’abonnements et pour vérifier l’état des abonnements. L’appAccountToken est utile pour associerles infos de compte d’un client à son achat intégré. Si votre app prend en charge le partage familial, notez que l’appAccountToken est indisponible pour les transactions de ce type. Le transactionId et l’originalTransactionId sont tous deux présents dans JWSTransaction et JWSRenewalInfo. L’appAccountToken n’est disponible que s’il est défini pour un achat à l’aide de StoreKit ou du nouveau point de terminaison Définir le jeton de compte d’app.

Quand un client télécharge votre app, l’objet AppTransaction devient disponible via StoreKit et représente des infos de téléchargement importantes de l’app. Le transactionId, l’originalTransactionId et l’appAccountToken étant spécifiques à un achat intégré, ils ne sont pas inclus dans l’objet AppTransaction. Parfois, il faut néanmoins identifier le téléchargement d’une app, notamment pour débloquer du contenu lors de son installation. Nous avons donc ajouté un champ appelé appTransactionId à l’objet AppTransaction pour vous aider dans ce cas. L’appTransactionId est un identifiant global unique pour chaque compte Apple par app. Pour le partage familial, chaque membre de la famille reçoit un appTransactionId unique. L’appTransactionId est statique pour un compte Apple et une app donnés, pour tous les nouveaux téléchargements, remboursements, rachats ou modifications du Store. L’appTransactionId est également inclus avec tous les achats intégrés effectués par le client dans votre app. Vous disposez ainsi de plus de flexibilité pour associer vos comptes clients aux transactions de l’App Store. Je vous explique comment cela fonctionne. Voici une façon d’utiliser l’appTransactionId pour associer vos comptes clients aux transactions de l’App Store. Tout d’abord, lorsqu’un client télécharge votre app, associez le compte client de votre système à l’appTransactionId présent dans l’objet AppTransaction. Pour obtenir un objet AppTransaction sur votre serveur, envoyez ces infos depuis votre app. Lorsqu’un client effectue un achat intégré, JWSTransaction et JWSRenewalInfo incluent le même appTransactionId. Vous pouvez l’associer une fois et l’utiliser pour tous les objets de transaction de l’App Store. Puisque l’appTransactionId figure dans tous les objets de transaction de l’App Store, il débloque certains cas d’utilisation utiles pour votre app, comme vérifier si deux achats d’abonnement différents appartiennent au même compte client. Par exemple, supposons que votre app gère deux produits d’abonnement : une newsletter sportive mensuelle et un abonnement annuel saisonnier aux matchs en direct. Comment déterminer si un compte client a accès aux deux abonnements ?

Même si chaque abonnement a un transactionId et un originalTransactionId distincts, ils partagent le même appTransactionId. Ce champ permet d’activer les personnalisations intégrées au lancement, comme la restauration des achats intégrés. De plus, appTransactionId s’utilise comme ID de transaction pour les points de terminaison clés de l’API du serveur de l’App Store, comme Obtenir l’historique des transactions, Obtenir les états des abonnements, etc. Aujourd’hui, je partage un nouveau point de terminaison pour obtenir l’objet AppTransaction via un point de terminaison de serveur. Avec le point de terminaison Obtenir les infos de transaction de l’app, vous récupérez les infos de téléchargement d’app directement sur votre serveur, sans utiliser l’appareil. L’objet AppTransaction s’utilise pour vérifier les infos de téléchargement importantes de l’app (version, plate-forme et environnement de l’app). Vous pouvez ainsi comprendre les performances de votre app avec les changements de modèle commercial. Sachez-le, ce point de terminaison ne renvoie pas d’infos sur l’appareil, comme la vérification de l’appareil. Pour ce faire, continuez à vous appuyer sur l’objet AppTransaction obtenu à partir de votre app. Voyons ensuite le point de terminaison, faisant partie de l’API du serveur de l’App Store.

Voici comment utiliser le point de terminaison Obtenir les infos de transaction de l’app. Tout ID de transaction (originalTransactionId, transactionId ou appTransactionId) est utilisable dans le chemin d’accès. La réponse contient signedAppTransactionInfo de JWS. Vous pouvez utiliser la bibliothèque du serveur de l’App Store pour décoder signedAppTransactionInfo. Le point de terminaison Obtenir les infos de transaction de l’app sera disponible en fin d’année. Comparons maintenant l’appTransactionId avec d’autres ID de transaction précédemment présentés. L’App Store génère l’appTransactionId, comme il le fait pour le transactionId et l’originalTransactionId.

Vous pouvez utiliser l’appTransactionId pour identifier de manière unique les téléchargements d’app et leur associer les achats ultérieurs du client. L’appTransactionId est identique pour tous les objets de transaction de l’App Store. Vous pouvez utiliser l’appTransactionId pour les transactions avec partage familial, si votre app le prend en charge. Nous conseillons d’utiliser l’appTransactionId, car il fournit une solution d’identification pour tous vos besoins. Il simplifie la gestion des achats intégrés et leur association aux comptes clients sur votre serveur. Examinons maintenant quelques améliorations clés des demandes de signature. Il faut d’abord créer une chaîne JWS (JSON Web Signature) sur votre serveur. Vous signez ensuite ces infos à l’aide d’une clé privée, téléchargée depuis App Store Connect.

Vous envoyez alors cette chaîne à votre app créée avec StoreKit pour appeler les fonctions exigeant une signature.

StoreKit envoie ensuite la chaîne de signature signée au serveur de l’App Store. Avant, et selon le cas d’utilisation, les signatures s’effectuaient dans différents formats, comme l’exigeait le serveur de l’App Store. Désormais, les demandes de signature de tous les cas d’utilisation suivent le format JWS. En résumé, ce format s’utilise dans les appels StoreKit qui le nécessitent, y compris les fonctions comme la création de signatures d’offres promotionnelles. Vous pouvez donc signer des offres promotionnelles avec le format de signature JWS. Cette nouvelle méthode de signature est une alternative à la méthode précédente. Pour faciliter les offres de lancement, nous avons récemment adopté une nouvelle signature d’offre de lancement JWS. Cette fonctionnalité permet de définir une éligibilité personnalisée pour les offres de lancement par transaction et utilisateur, et ainsi de mieux contrôler le nombre de ces offres utilisées par un client sur l’App Store. Vous pouvez aussi envoyer des demandes intégrées JWS signées via l’API Advanced Commerce. Pour plus d’infos, consultez notre documentation pour les développeurs. Créons maintenant la signature d’offre promotionnelle JWS sur votre serveur. Avec la signature d’offre promotionnelle et StoreKit, conservez les abonnés actuels ou anciens sur votre app. Voici comment créer une signature d’offre promotionnelle à l’aide de la bibliothèque du serveur de l’App Store. J’utilise Java pour cet exemple. Tout d’abord, j’instancie la classe PromotionalOfferV2SignatureCreator avec une clé privée, keyId, issuerId et bundleId pour mon app. Vous pouvez trouver key, keyId et issuerId dans App Store Connect.

Ces valeurs s’utilisent pour la signature, ce qui empêche les clients d’utiliser des offres promotionnelles sans l’accord du développeur.

Ensuite, je spécifie transactionId. Ici, vous pouvez fournir n’importe quel ID de transaction appartenant au client, y compris appTransactionId.

Fournissez transactionId, si vous souhaitez limiter l’offre à un client spécifique, sinon, ignorez ce champ.

Ensuite, je fournis un productId et un offerId. J’ai préconfiguré l’offre représentée par cet ID dans App Store Connect.

Enfin, je transmets productId, offerId et transactionId à la fonction createSignature. Notez que la nouvelle signature est plus simple que l’ancienne, car elle a moins d’entrées. Vous pouvez simplifier les demandes de signature dans plusieurs cas, en utilisant le format de signature JWS unifié. Même après avoir fait une offre, les clients peuvent se dédire et demander un remboursement en raison de facteurs indépendants de votre volonté, comme un problème de facturation ou un achat accidentel. Dans de tels cas, voyons comment participer au processus décisionnel de remboursement. Tout d’abord, voici quelques avantages. Essayez de participer à ce processus, car vous connaissez le degré de consommation des produits par vos clients. Par exemple, lorsque vous gérez des produits consommables sur votre app, vous gérez déjà les soldes de consommables des clients sur votre serveur. Cela peut renforcer la satisfaction client après la demande de remboursement.

Lorsqu’un client demande un remboursement, l’App Store envoie une notification CONSUMPTION_REQUEST à votre serveur. Pour faciliter la décision de remboursement, vous pouvez répondre à cette notification via le point de terminaison Envoyer les infos de consommation.

Je suis ravi de partager un nouveau point de terminaison Envoyer les infos de consommation V2.

À la base, le point de terminaison est plus simple à intégrer, car nous avons beaucoup réduit le nombre d’entrées fournies par rapport à la version précédente. Le nouveau point gère également la préférence de remboursement au prorata pour mieux identifier la consommation partielle d’un produit. Si la version précédente de ce point ne gérait que les produits consommables et avec abonnements à renouvellement automatique, la nouvelle s’étend à tous les produits, dont les non-consommables et ceux avec abonnements non-renouvelables.

Si vous avez déjà utilisé le point de terminaison V1, notez qu’il est obsolète, mais qu’il continuera à accepter les demandes. Si vous n’avez pas utilisé le point Envoyer les infos de consommation, nous vous conseillons d’utiliser le point V2 récent avec la bibliothèque du serveur de l’App Store. Voyons comment utiliser le point Envoyer les infos de consommation V2. Supposons qu’un client ait demandé le remboursement d’un achat consommable et qu’une notification CONSUMPTION_REQUEST ait été envoyée à votre serveur. Voici un exemple de réponse à la notification avec le point de terminaison Envoyer les infos de consommation V2.

Vous fournissez le transactionId dans le chemin d’accès, indiqué dans la notification CONSUMPTION_REQUEST.

Le nouveau point de terminaison accepte cinq champs de saisie, contre douze dans la version précédente. Sur les cinq champs de saisie, trois sont obligatoires et deux sont facultatifs. Nous avons réduit les champs pour simplifier votre participation aux décisions de remboursement. Définissez le champ customerConsented sur true si le client a accepté d’envoyer à l’App Store les données de consommation liées à sa demande de remboursement, y compris celles fournies dans le corps de ConsumptionRequestV2. Si tel n’est pas le cas, ne répondez pas à la notification CONSUMPTION_REQUEST. Si le point de terminaison est appelé avec le champ défini sur false, la demande est rejetée. Utilisez sampleContentProvided pour indiquer si vous avez fourni un exemple de contenu avant que le client n’achète le produit. Utilisez DELIVERED comme deliveryStatus si vous avez bien livré le contenu au client. Sinon, utilisez un statut UNDELIVERED approprié.

Vous pouvez indiquer en option votre préférence de remboursement. Le remboursement au prorata avec la valeur GRANT_PRORATED est maintenant possible, en plus du remboursement complet ou nul, déjà pris en charge. Si vous ne souhaitez pas fournir de préférence, ne définissez pas ce champ. Le consumptionPercentage indique la consommation du produit en millième de pourcent.

Ici, une valeur de 25 000 représente une consommation de 25 % du produit consommable. Le point de terminaison Envoyer les infos de consommation V2 sera disponible en fin d’année. Découvrons la nouvelle option de remboursement au prorata du dernier point de terminaison V2. Envisagez une préférence de remboursement au prorata quand le client peut partiellement consommer le produit.

Cette préférence vous permet d’indiquer la consommation, ce qui aide l’App Store à accorder un montant de remboursement approprié.

Spécifiez consumptionPercentage lorsque vous indiquez une préférence de remboursement au prorata pour les produits consommables, non-consommables et sans renouvellement d’abonnement. Cela permet à l’App Store d’accorder un remboursement approprié précis. Notez que l’App Store calcule pour vous le consumptionPercentage des abonnements à renouvellement automatique, en utilisant le temps restant sur l’abonnement du client. Les données de consommation envoyées aident l’App Store à décider du remboursement (intégral, au pro rata ou refusé). Vous êtes informé de la décision à l’aide d’une notification REFUND ou REFUND_DECLINED. Si vous recevez une notification REFUND_DECLINED, aucune action n’est requise. Cependant, vous êtes responsable de la prise de mesures appropriées lorsque vous recevez une notification REFUND. Voici un exemple de notification REFUND. Vous pouvez déterminer le montant d’un remboursement accordé par l’App Store à l’aide du nouveau champ refundPercentage. Dans ce cas, le remboursement est de 75 %. Vous pouvez prendre les mesures appropriées pour le produit consommé.

Avec ce champ, n’oubliez pas qu’App Store Connect est votre référence pour toutes les questions financières et comptables. Vous pouvez aussi comprendre le type de révocation à l’aide du nouveau champ revocationType. Ce champ peut être REFUND_FULL, REFUND_PRORATED ou FAMILY_REVOKE. Il s’agit d’un remboursement de consommable, les valeurs sont donc REFUND_FULL et REFUND_PRORATED. En cas de remboursement intégral ou de révocation familiale, vous révoquez immédiatement l’accès au contenu sur votre serveur. Pour REFUND_PRORATED, révoquez le pourcentage remboursé du contenu. Voyons maintenant comment gérer une notification de remboursement au prorata sur votre serveur. Dans le cas d’un produit consommable, non consommable ou sans renouvellement d’abonnement, vous utilisez le champ refundPercentage pour calculer et révoquer le montant proportionnel de contenu du compte du client. Par exemple, si le client a acheté une monnaie virtuelle, vous pouvez réduire son solde du montant remboursé. Pour les abonnements à renouvellement automatique, gérez les remboursements au prorata comme les remboursements complets. Vérifiez l’état actuel de l’abonnement et prenez les mesures appropriées. J’espère que vous utiliserez le nouveau point de terminaison Envoyer les infos de consommation V2 lors du processus de remboursement, car il est plus efficace que jamais. Nous avons vu beaucoup de choses aujourd’hui ! Récapitulons rapidement. Je vous ai montré divers ID de transaction, dont l’identifiant à guichet unique appTransactionId. Ensuite, j’ai exploré le format de signature unifié JWS. Enfin, je vous ai montré la simplicité des décisions de remboursement. Avant de vous quitter, laissez-moi évoquer certaines étapes utiles. Si vous avez déjà contribué à la bibliothèque open source du serveur de l’App Store, merci ! Sinon, veuillez consulter notre page GitHub pour savoir comment contribuer et soutenir la communauté de l’App Store. Avec l’arrivée de nouvelles fonctionnalités, nous aimerions avoir de vos nouvelles. Veuillez envoyer vos demandes de fonctionnalités et commentaires à l’équipe serveur de l’App Store via l’Assistant d’évaluation. Pour en savoir plus sur les mises à jour apportées à StoreKit, consultez la séance « What’s new in StoreKit and In-App Purchase » de la WWDC25. Consultez également « Explore App Store server APIs for In-App Purchase » de la WWDC24 pour plus d’infos sur le serveur de l’App Store. Merci de votre attention et à bientôt !