Documentation AIDL de Google Play Billing

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.

Les abonnements saisonniers sont obsolètes depuis le 15 juin 2019. Google Play renvoie désormais BILLING_RESPONSE_RESULT_DEVELOPER_ERROR pour l'achat de tout nouvel abonnement saisonnier.

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.