Documentation AIDL de Google Play Billing

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Avertissement : l'AIDL est désormais obsolète et sera supprimé dans une prochaine version. Pour implémenter des fonctionnalités de facturation pour Google Play, utilisez la Bibliothèque Google Play Billing.

Cette documentation fournit des informations techniques de référence sur l'utilisation de l'AIDL de Google Play Billing.

Codes de réponse du serveur

Le tableau suivant répertorie tous les codes de réponse du serveur envoyés par Google Play à votre application. Google Play envoie le code de réponse de manière synchrone en tant qu'entier mappé sur la clé RESPONSE_CODE de la réponse Bundle. Votre application doit gérer tous ces codes de réponse.

Tableau 1. Récapitulatif des codes de réponse pour les appels AIDL de Google Play Billing.

Code de réponse Valeur Description
BILLING_RESPONSE_RESULT_OK 0 Opération réussie
BILLING_RESPONSE_RESULT_USER_CANCELED 1 L'utilisateur a appuyé sur Retour ou a annulé une boîte de dialogue
BILLING_RESPONSE_RESULT_SERVICE_UNAVAILABLE 2 La connexion réseau est interrompue
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE 3 La version de l'AIDL de Google Play Billing n'est pas compatible avec le type demandé
BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE 4 Le produit demandé n'est pas disponible à l'achat
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR 5 Arguments non valides fournis à l'API. Cette erreur peut également indiquer que l'application n'a pas été correctement signée ou configurée pour la facturation, ou qu'elle ne dispose pas des autorisations nécessaires dans son fichier manifeste.
BILLING_RESPONSE_RESULT_ERROR 6 Erreur fatale lors de l'action de l'API
BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED 7 Échec de l'achat, car vous possédez déjà cet article
BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED 8 Échec de l'utilisation, car vous ne possédez pas cet article

Documentation AIDL de Google Play Billing – Assistance

Cette section décrit les méthodes permettant d'obtenir des informations sur les types d'assistance de facturation disponibles pour votre application.

La méthode isBillingSupported()

Cette méthode indique si :

  • la version d'AIDL indiquée est compatible avec votre application ;
  • la facturation Google Play est disponible dans le pays de l'utilisateur ;
  • le système de facturation de Google Play est activé dans votre package d'application ;
  • votre application peut utiliser le type d'élément donné pour la facturation.

Tableau 2. Paramètres de isBillingSupported().

Clé Type Description
apiVersion int Le numéro de version de l'AIDL de Google Play Billing utilisé par votre application.
packageName String Le nom du package de l'application qui appelle cette méthode.
type String La valeur doit être inapp pour un produit intégré ou subs pour les abonnements.

Cette méthode est disponible dans les versions 3 et ultérieures de l'AIDL de Google Play Billing.

La méthode isBillingSupportedExtraParams()

Cette méthode est identique à isBillingSupported(), sauf que vous pouvez transmettre un quatrième argument, un Bundle, pouvant contenir des paramètres supplémentaires.

Tableau 3. Paramètres de isBillingSupportedExtraParams().

Clé Type Description
apiVersion int Le numéro de version de l'AIDL de Google Play Billing utilisé par votre application.
packageName String Le nom du package de l'application qui appelle cette méthode.
type String La valeur doit être inapp pour un produit intégré ou subs pour les abonnements.
extraParams Bundle

Ensemble de paramètres supplémentaires qui précisent le type de système de facturation de Google Play pris en charge par l'application.

Ce bundle peut contenir une clé facultative appelée vr ayant une valeur booléenne. Cet indicateur permet de spécifier si cette application est compatible avec un parcours d'achat en réalité virtuelle (RV).

Cette méthode est disponible dans les versions 7 et ultérieures de l'AIDL de Google Play Billing.

Documentation AIDL de Google Play Billing - Informations détaillées

L'AIDL de Google Play Billing est défini dans le fichier IInAppBillingService.aidl, inclus dans la version 3 de l'application exemple.

La méthode getSkuDetails()

Utilisez la méthode getSkuDetails() afin d'obtenir les informations détaillées sur le produit selon une liste d'identifiants de produits correspondants.

Tableau 4. Paramètres de GetSkuDetails().

Clé Type Description
apiVersion int Le numéro de version de l'AIDL de Google Play Billing utilisé par votre application.
packageName String Le nom du package de l'application qui appelle cette méthode.
type String Type des éléments intégrés ("inapp" pour les achats uniques et "subs" pour les abonnements).
skusBundle Bundle Bundle contenant une StringArrayList de codes SKU ayant une clé ITEM_ID_LIST.

Si la méthode getSkuDetails() réussit, Google Play envoie une réponse Bundle. Les résultats de la requête sont stockés dans le Bundle à l'intérieur d'une chaîne ArrayList mappée sur la clé DETAILS_LIST. Chaque chaîne de la liste des détails contient les informations détaillées d'un seul produit au format JSON. Les champs de la chaîne JSON contenant les informations détaillées sur le produit sont présentés dans le tableau 5.

Tableau 5. Description des champs JSON contenant les informations détaillées sur les articles renvoyés par une requête getSkuDetails().

Clé Description
productId L'identifiant du produit.
type La valeur doit être inapp pour un produit intégré ou subs pour les abonnements.
price Prix formaté de l'article, dont le symbole de la devise. Le prix n'inclut pas les taxes.
price_amount_micros Prix en micro-unités, où 1 000 000 de micro-unités équivaut à une unité de la devise. Par exemple, si le prix (price) équivaut à "€7.99", price_amount_micros (montant du prix en micro-unités) est donc de "7990000". Cette valeur représente le prix arrondi localisé pour une devise spécifique.
price_currency_code Code de représentation des devises ISO 4217 pour price. Par exemple, si price est exprimé en livres sterling, le price_currency_code (code de représentation du prix) est "GBP".
title Titre du produit.
description Description du produit.
subscriptionPeriod Période d'abonnement, spécifiée selon le format ISO 8601. Par exemple, P1W équivaut à une semaine, P1M à un mois, P3M à trois mois, P6M à six mois, et P1Y à un an.

Remarque : Clé renvoyée uniquement pour les abonnements.

freeTrialPeriod Période d'essai configurée dans la Google Play Console, spécifiée au format ISO 8601. Par exemple, P7D équivaut à sept jours. Pour en savoir plus sur l'éligibilité à l'essai gratuit, consultez la section Abonnements intégrés.

Remarque : Clé renvoyée uniquement pour les abonnements avec période d'essai.

introductoryPrice Prix découverte formaté d'un abonnement, avec le symbole de sa devise (par exemple, €3.99). Le prix ne comprend pas les taxes.

Remarque : Clé renvoyée uniquement pour les abonnements avec période d'essai.

introductoryPriceAmountMicros Prix de lancement en micro-unités. La devise est identique à price_currency_code.

Remarque : Clé renvoyée uniquement pour les abonnements avec période d'essai.

introductoryPricePeriod La période de facturation du prix découverte, spécifiée au format ISO 8601.

Remarque : Clé renvoyée uniquement pour les abonnements avec période d'essai.

introductoryPriceCycles Nombre de périodes de facturation de l'abonnement pour lesquelles l'utilisateur bénéficiera du prix découverte, par exemple : 3.

Remarque : Clé renvoyée uniquement pour les abonnements avec période d'essai.

La méthode getBuyIntent()

Cette méthode renvoie un de code de réponse sous la forme d'un entier mappé à la clé RESPONSE_CODE, ainsi qu'un PendingIntent pour lancer le parcours d'achat pour l'élément intégré mappé à la clé BUY_INTENT, comme décrit dans la section Implémenter Google Play Billing. Lorsque Google Play reçoit PendingIntent, une réponse Intent avec les données pour ce bon de commande est envoyée. Les données renvoyées dans la réponse Intent sont présentées dans le tableau 6.

Remarque : Au lieu d'utiliser cette méthode, nous vous recommandons d'utiliser getBuyIntentExtraParams(), qui fournit des fonctionnalités supplémentaires.

Tableau 6. Données de réponse d'une demande d'achat de Google Play.

Clé Description
RESPONSE_CODE La valeur est de 0 si l'achat a abouti, autrement "error" (erreur) s'affiche.
INAPP_PURCHASE_DATA Une chaîne au format JSON, contenant des détails sur le bon de commande. Reportez-vous au tableau 7 pour obtenir une description des champs JSON.
INAPP_DATA_SIGNATURE Chaîne contenant la signature des données d'achat, signées avec la clé privée du développeur. La signature des données utilise le schéma RSASSA-PKCS1-v1_5.

Le tableau 7 décrit les champs JSON renvoyés dans les données de réponse pour un bon de commande.

Tableau 7. Descriptions des champs JSON pour INAPP_PURCHASE_DATA.

Champ Description
autoRenewing Indique si l'abonnement est renouvelé automatiquement. Si true (vrai), l'abonnement est actif et sera automatiquement renouvelé à la prochaine date de facturation. Si false (faux), cela signifie que l'utilisateur a résilié l'abonnement. L'utilisateur a accès au contenu de l'abonnement jusqu'à la prochaine date de facturation, date à laquelle il n'y aura plus accès, sauf s'il réactive le renouvellement automatique (ou s'il renouvelle l'abonnement manuellement, comme décrit dans la section Renouvellement manuel). Si vous offrez un délai de grâce, cette valeur reste définie sur true pour tous les abonnements tant que le délai de grâce n'est pas expiré. La prochaine date de facturation est prolongée de façon dynamique tous les jours jusqu'à la fin du délai de grâce ou jusqu'à ce que l'utilisateur corrige son mode de paiement.
orderId Un identifiant unique pour la transaction. Cet identifiant correspond à l'ID de commande Google Payments.
packageName Le package d'application d'où provient l'achat.
productId Le code produit de l'article. Chaque article dispose d'un ID produit que vous devez spécifier dans la fiche produit de l'application sur la Google Play Console.
purchaseTime L'heure à laquelle le produit a été acheté, en millisecondes écoulées depuis l'epoch (1er janvier 1970).
purchaseState L'état de l'achat de la commande, qui renvoie toujours 0 (acheté).
developerPayload Une chaîne spécifiée par le développeur contenant des informations supplémentaires sur une commande. Vous pouvez spécifier une valeur pour ce champ lorsque vous effectuez une requête getBuyIntent.
purchaseToken Un jeton qui identifie de manière unique un achat pour une paire utilisateur et un article précis.

La méthode consumePurchase()

Utilise l'achat correspondant au jeton d'achat donné. Cet article sera supprimé de toutes les réponses suivantes pour getPurchases(), et autorisera le rachat des articles ayant le même code SKU.

Tableau 8. Paramètres consumePurchase().

Clé Type Description
apiVersion int Le numéro de version de l'AIDL de Google Play Billing utilisé par votre application.
packageName String Le nom du package de l'application qui appelle cette méthode.
purchaseToken String Jeton dans les informations d'achat au format JSON qui identifie l'achat à utiliser.

Cette méthode renvoie RESULT_OK(0), pour indiquer que l'utilisation a réussi, et des codes de réponse appropriés en cas d'échec.

La méthode getBuyIntentToReplaceSkus().

Cette méthode permet de faire passer un abonnement à un niveau supérieur ou inférieur. La méthode ressemble à getBuyIntent(), à ceci près qu'une liste contenant exactement un code SKU déjà acheté doit être remplacée par le code SKU acheté. Lorsque l'utilisateur finalise l'achat, Google Play remplace l'ancien code SKU et crédite l'utilisateur à hauteur de la valeur non utilisée de son abonnement, au prorata. Google Play applique ce crédit au nouvel abonnement et ne commence à facturer le nouvel abonnement à l'utilisateur qu'une fois le crédit utilisé.

Remarque : Au lieu d'utiliser cette méthode, nous vous recommandons d'utiliser getBuyIntentExtraParams(), qui fournit des fonctionnalités supplémentaires.

Cette méthode a été ajoutée à la version 5 de l'AIDL de Google Play Billing. Pour vérifier que la méthode est renseignée, envoyez la requête AIDL suivante : isBillingSupported.

Remarque : Vous ne pouvez utiliser cette méthode que pour l'achat d'abonnements. Si le paramètre type transmis est différent de "subs", la méthode renvoie BILLING_RESPONSE_RESULT_DEVELOPER_ERROR. En outre, les codes SKU transmis peuvent ne pas inclure les codes SKU pour les abonnements saisonniers.

Cette méthode renvoie un code de réponse sous la forme d'un entier mappé à la clé RESPONSE_CODE, ainsi qu'un PendingIntent pour lancer le parcours d'achat pour l'abonnement intégré mappé à la clé BUY_INTENT. Lorsque Google Play reçoit PendingIntent, une réponse Intent avec les données pour ce bon de commande est envoyée. Les données renvoyées dans la réponse Intent sont présentées dans le tableau 9.

Tableau 9. Données de réponse d'une demande d'achat de la version 5 de l'AIDL de Google Play Billing.

Clé Description
RESPONSE_CODE La valeur est 0 si l'achat aboutit. Contient un code d'erreur si l'achat échoue.
INAPP_PURCHASE_DATA Une chaîne au format JSON, contenant des détails sur le bon de commande. Reportez-vous au tableau 6 pour obtenir une description des champs JSON.
INAPP_DATA_SIGNATURE Chaîne contenant la signature des données d'achat signées par le développeur avec sa clé privée. La signature des données utilise le schéma RSASSA-PKCS1-v1_5.

La méthode getBuyIntentExtraParams()

Cette méthode lance une demande d'achat. Cette méthode est une variante de la méthode getBuyIntent() et nécessite un paramètre extraParams supplémentaire. Ce paramètre est un Bundle de clés et de valeurs facultatives qui affectent le fonctionnement de la méthode, comme indiqué dans le tableau 10.

Tableau 10. Paramètres supplémentaires de getBuyIntentExtraParams().

Clé Type Description
skusToReplace List<String> Une liste facultative contenant un seul code SKU à partir duquel l'utilisateur fait passer son abonnement au niveau supérieur ou inférieur. Transmettez ce champ si l'achat fait passer l'abonnement existant au niveau supérieur ou inférieur. Le code SKU spécifié est remplacé par le code SKU acheté par l'utilisateur. Google Play remplace le code SKU spécifié au début du prochain cycle de facturation.
replaceSkusProration boolean

Indique si l'utilisateur doit être crédité pour une durée inutilisée de son abonnement pour les codes SKU qu'il met à niveau ou rétrograde. Si ce champ est défini sur "true" (vrai), Google Play remplace les anciens codes SKU et crédite l'utilisateur à hauteur de la valeur non utilisée de son abonnement, au prorata. Google Play applique ce crédit au nouvel abonnement et ne commence à facturer le nouvel abonnement à l'utilisateur qu'une fois le crédit utilisé.

Si vous définissez ce champ sur "false" (faux), l'utilisateur ne reçoit pas de crédit pour la durée d'abonnement inutilisée, et la date de récurrence ne change pas.

La valeur par défaut est "true" (vrai). Ignoré si vous ne transmettez pas skusToReplace.

accountId String

Chaîne obscurcie facultative, associée au compte de l'utilisateur dans votre application. Si vous transmettez cette valeur, Google Play peut l'utiliser pour détecter une activité irrégulière, comme plusieurs appareils effectuant des achats sur le même compte dans un court laps de temps, par exemple.

Ce champ ressemble à developerId (ID de développeur) dans la mesure où il représente un seul utilisateur, mais notez que si vous possédez plusieurs applications, un même utilisateur peut avoir un accountId (ID de compte) différent pour chaque application, tandis que developerId doit identifier seul utilisateur sur toutes vos applications.

N'utilisez pas votre ID de développeur Google Play Console ni l'ID Google de l'utilisateur pour ce champ. De plus, ce champ ne doit pas contenir l'ID de l'utilisateur en texte clair. Nous vous recommandons d'utiliser un hachage à sens unique pour générer une chaîne à partir de l'ID de l'utilisateur et de stocker la chaîne hachée dans ce champ.

developerId String

Chaîne obscurcie facultative et associée au seul compte de l'utilisateur dans toutes vos applications. Ce champ ressemble à accountId dans la mesure où il représente un seul utilisateur. Cependant, ce champ doit être identique dans toutes vos applications pour un même utilisateur, alors que accountId peut différer selon les applications.

N'utilisez pas votre ID de développeur Google Play Console ni l'ID Google de l'utilisateur pour ce champ. De plus, ce champ ne doit pas contenir l'ID de l'utilisateur en texte clair. Nous vous recommandons d'utiliser un hachage à sens unique pour générer une chaîne à partir de l'ID de l'utilisateur et de stocker la chaîne hachée dans ce champ.

vr boolean

Indique si l'intent fourni représente le début d'un parcours d'achat en réalité virtuelle (RV).

Remarque : Pour que ce paramètre supplémentaire ait un effet sur votre application, vous devez utiliser la version 7 de l'AIDL de Google Play Billing ou une API plus récente.

Cette méthode est disponible dans les versions 6 et ultérieures de l'AIDL de Google Play Billing.

La méthode getPurchases()

Cette méthode renvoie les produits actuellement non consommés par l'utilisateur, y compris les articles achetés et les articles acquis en utilisant un code promotionnel. Le tableau 11 liste les données de réponse renvoyées dans le Bundle.

Tableau 11. Données de réponse d'une requête getPurchases.

Clé Description
RESPONSE_CODE La valeur est 0 si la requête a abouti, sinon "error" (erreur) s'affiche.
INAPP_PURCHASE_ITEM_LIST StringArrayList contenant la liste des ID de produits achetés depuis cette application.
INAPP_PURCHASE_DATA_LIST StringArrayList contenant les détails des achats effectués depuis cette application. Reportez-vous au tableau 13 pour obtenir la liste détaillée des informations stockées dans chaque élément de la liste.
INAPP_DATA_SIGNATURE_LIST StringArrayList contenant les signatures des achats effectués depuis cette application.
INAPP_CONTINUATION_TOKEN Chaîne contenant un jeton de continuation permettant de récupérer le prochain ensemble de produits intégrés appartenant à l'utilisateur. Ce paramètre n'est défini par le service Google Play que si l'utilisateur possède un nombre conséquent d'applications. Lorsqu'un jeton de continuation est présent dans la réponse, vous devez effectuer un autre appel à getPurchases et transmettre le jeton de continuation que vous avez reçu. L'appel getPurchases qui s'en suit renvoie plus d'achats et éventuellement un autre jeton de continuation.

La méthode getPurchaseHistory()

Cette méthode renvoie l'achat le plus récent effectué par l'utilisateur pour chaque code SKU, même si cet achat a expiré, a été annulé ou a été consommé. Le tableau 12 liste les données de réponse renvoyées dans le Bundle.

Tableau 12. Données de réponse d'une requête getPurchaseHistory.

Clé Description
RESPONSE_CODE La valeur est 0 si la requête a abouti, sinon "error" (erreur) s'affiche.
INAPP_PURCHASE_ITEM_LIST StringArrayList contenant la liste des ID de produits achetés depuis cette application.
INAPP_PURCHASE_DATA_LIST StringArrayList contenant les détails des achats récents effectués depuis cette application. Reportez-vous au tableau 6 pour obtenir la liste détaillée des informations stockées dans chaque élément INAPP_PURCHASE_DATA de la liste.
INAPP_DATA_SIGNATURE_LIST StringArrayList contenant les signatures des achats effectués depuis cette application.
INAPP_CONTINUATION_TOKEN Chaîne contenant un jeton de continuation permettant de récupérer le prochain ensemble de produits intégrés appartenant à l'utilisateur. Ce paramètre n'est défini par le service Google Play que si l'utilisateur possède un nombre conséquent d'applications. Lorsqu'un jeton de continuation est présent dans la réponse, vous devez effectuer un autre appel à getPurchases et transmettre le jeton de continuation que vous avez reçu. L'appel getPurchases qui s'en suit renvoie plus d'achats et éventuellement un autre jeton de continuation.

Tableau 13. Descriptions des champs JSON pour l'historique des achats renvoyés par getPurchaseHistory().

Champ Description
productId Le code produit de l'article. Chaque article dispose d'un ID produit que vous devez spécifier dans la fiche produit de l'application sur la Google Play Console.
purchaseTime L'heure à laquelle le produit a été acheté, en millisecondes écoulées depuis l'epoch (1er janvier 1970).
developerPayload Une chaîne spécifiée par le développeur contenant des informations supplémentaires sur une commande. Vous pouvez spécifier une valeur pour ce champ lorsque vous effectuez une requête getBuyIntent.
purchaseToken Un jeton qui identifie de manière unique un achat pour une paire utilisateur et un article précis.

Remarque : La méthode getPurchaseHistory() engendre des coûts plus élevés que getPurchases(), car elle nécessite un appel au serveur Google Play. Utilisez getPurchases() si vous n'avez pas réellement besoin de l'historique des achats de l'utilisateur.

Cette méthode est disponible dans les versions 6 et ultérieures de l'AIDL de Google Play Billing.