Cette page a été traduite par l'API Cloud Translation.

Implémenter Play Billing dans votre PWA

Si votre PWA est listée sur Google Play et que vous souhaitez la monétiser en vendant des produits ou des abonnements intégrés, le Règlement Play vous demandera d'implémenter Play Billing. Vous devrez implémenter deux API dans votre PWA : l'API Digital Goods et l'API Payment Request.

API Digital Goods

L'API Digital Goods est une interface entre votre application et Google Play. Il vous permet de récupérer les produits numériques et les informations que vous avez saisies pour vos produits intégrés et vos abonnements dans la Play Console, ainsi que les achats existants effectués par un utilisateur. Si vous n'avez pas encore ajouté de produits ni d'abonnements intégrés à l'application dans la Play Console, veillez à suivre la configuration de la Play Console pour Google Play Billing.

Le 30 novembre 2021, ChromeOS 96 a été publié avec l'implémentation de l'API Digital Goods 2.0.

La phase d'évaluation de la première version de l'API Digital Goods s'est terminée le 30 janvier 2022. Elle est donc désormais obsolète et seule la version 2 de l'API est disponible.

Le 23 juin 2022, ChromeOS 103 a été publié avec l'implémentation de l'API Digital Goods 2.1. Cette version n'inclut aucune modification majeure. Elle ne contient que de nouvelles méthodes et des champs supplémentaires : listPurchaseHistory() et itemType.

S'inscrire à la version d'évaluation

Remarque : L'API Digital Goods est actuellement disponible via un Origin Trial, un mécanisme qui permet aux développeurs d'accéder en avant-première aux nouvelles API Web. Vous devrez vous inscrire à l'origin trial de l'API Digital Goods v2 et demander un jeton que vous devrez fournir sur toutes les pages de votre origine.

Lorsque vous vous inscrivez à l'origin trial, une date de validité s'affiche. Il s'agit de la date jusqu'à laquelle votre jeton est garanti de fonctionner. N'oubliez pas de renouveler vos jetons à l'approche de cette date pour continuer à participer à l'essai. Les API proposées en version d'évaluation (Origin Trial) sont susceptibles d'être modifiées. Veillez donc à vous tenir informé des dernières modifications apportées aux versions d'évaluation auxquelles vous participez. En cas de problème, consultez la documentation de l'API Digital Goods.

API Payment Request

L'API Payment Request gère la transaction de paiement proprement dite lorsqu'un achat est effectué. Il utilise les informations sur l'article fournies par l'API Digital Goods pour effectuer l'achat via l'application à l'aide du mode de paiement approprié, qui est Google Play Billing dans notre cas.

Détecter la fonctionnalité Digital Goods API

Vous pouvez vérifier si vous avez correctement activé l'API sur votre site Web via l'évaluation de l'origine en recherchant la méthode getDigitalGoodsService dans l'objet window.

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
} else {
  console.log('DigitalGoodsService is not available.');
  // Use another payment method
}

Se connecter au service Google Play Billing

L'API Digital Goods a été conçue pour être compatible avec différents navigateurs et boutiques numériques, de la même manière que l'API Payment Request est indépendante du navigateur et peut être utilisée avec différents fournisseurs de services de paiement. Pour obtenir une instance du service associée à Google Play Billing, transmettez la chaîne "https://play.google.com/billing" comme mode de paiement à getDigitalGoodsService().

Si la méthode génère une erreur, cela signifie que le mode de paiement Google Play Billing n'est pas disponible (par exemple, l'utilisateur accède à votre PWA via le navigateur). Vous devez plutôt proposer un autre mode de paiement pour les transactions.

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
  try {
    const service = await window.getDigitalGoodsService('https://play.google.com/billing');
    // Google Play Billing service is available
  } catch (error) {
    // Google Play Billing service is not available. Use another payment flow.
  }
}

Obtenir les détails d'un élément

Une fois le service de biens numériques connecté à Google Play, vous pouvez utiliser l'API pour récupérer des informations sur les produits et les achats.

La méthode getDetails() vous permet d'obtenir des informations sur les éléments que vous avez configurés dans la Play Console. Des informations telles que le titre, la description et le prix du produit doivent être affichées dans l'UI de votre application pour que l'utilisateur sache ce qui est disponible à l'achat et à quel prix.

La méthode getDetails() aura besoin d'une liste d'ID d'articles correspondant aux ID produit des produits et abonnements intégrés à l'application que vous avez créés dans la Play Console.

const itemDetails = await service.getDetails(['product_1', 'product_2', 'product_3']);
for (const item of itemDetails) {
  // Display item information to user
  displayItem(item.title, item.description, item.price);
}

Pour obtenir le prix approprié pour les paramètres régionaux de l'utilisateur, vous devrez effectuer une mise en forme supplémentaire :

const localePrice = new Intl.NumberFormat(navigator.language, {
  style: 'currency',
  currency: item.price.currency,
}).format(item.price.value);

Remarque : L'API Digital Goods ne fournit pas de méthode permettant d'obtenir la liste des ID d'articles. Vous devrez plutôt les coder en dur dans votre client ou les récupérer depuis votre serveur backend. L'API Google Play Developer vous permet d'interroger la liste des ID d'articles depuis un backend. (Découvrez comment implémenter les principaux composants de Play Billing dans votre serveur backend.) Quelle que soit la solution choisie, assurez-vous que les ID d'article correspondent à ceux de la Play Console.

Dans la version 2.1 de l'API, l'un des champs renvoyés par getDetails() est itemType. Il s'agit d'une énumération dont la valeur est ”product” ou ”subscription” pour indiquer si l'élément correspondant est un produit intégré ou un abonnement, respectivement. Il peut être utile de pouvoir faire la différence entre les deux types de produits si vous devez appliquer des traitements différents à chaque type de produit. Par exemple, vous pouvez avoir une page spécifique pour les utilisateurs qui souhaitent s'abonner et une autre page pour les autres produits sans abonnement. Il est également utile pour connaître la ressource REST de l'API Google Play Developer à utiliser dans votre backend (purchases.products ou purchases.subscriptions).

Acheter un article

Une fois vos produits et leurs détails affichés à l'utilisateur, vous pouvez créer le flux d'achat avec l'API Payment Request. Lorsqu'elle est utilisée conjointement avec l'API Digital Goods, un seul paramètre d'entrée est requis : methodData.

Le système de facturation Play n'autorise l'achat que d'un seul article à la fois. Le prix et les détails de l'article sont déjà connus du serveur Play. Le paramètre details n'est donc pas nécessaire. Pour en savoir plus, consultez l'explication.

Utilisez le membre supportedMethods du paramètre methodData dans PaymentRequest pour identifier Google Play Billing comme mode de paiement avec la chaîne "https://play.google.com/billing". Ensuite, dans le membre data, transmettez l'ID de l'élément en tant que sku.

const paymentMethodData = [
  {
    supportedMethods: 'https://play.google.com/billing',
    data: {
      sku: item.itemId,
    },
  },
];

Créez ensuite la demande de paiement et appelez show() pour démarrer le processus de paiement :

const request = new PaymentRequest(paymentMethodData);
const paymentResponse = await request.show();

L'interface utilisateur d'achat Play s'affiche alors pour l'utilisateur, qui peut y consulter les informations détaillées sur le produit qu'il tente d'acheter. Il peut soit abandonner la transaction, soit procéder au paiement. Si l'utilisateur annule le paiement, la promesse renvoyée par show() sera rejetée avec une erreur. S'il effectue le paiement et finalise l'achat, la promesse est résolue avec un PaymentResponse. Un jeton d'achat est renvoyé dans la propriété details de la réponse de paiement.

Pour éviter toute fraude, il est essentiel de vérifier l'achat et le jeton d'achat sur votre serveur backend. Il est également conseillé de suivre les utilisateurs et les jetons d'achat associés. Découvrez comment implémenter la validation sur votre serveur backend.

Après avoir validé l'achat, appelez complete() sur la réponse de paiement pour terminer le processus de paiement et fermer l'UI de facturation. Vous pouvez également transmettre une chaîne result facultative pour indiquer l'état du processus de paiement. Il appartient au navigateur de fournir ou non une indication de ce résultat à l'utilisateur. Chrome ne crée aucun repère visible par l'utilisateur. Nous vous recommandons donc d'afficher vos propres messages d'erreur ou de réussite dans votre PWA.

/* Changes were recently made so that the PaymentResponse `details` property returns the purchase token as `purchaseToken` instead of `token`. Note that `token` will be deprecated at some point in the future. To ensure that your app won't be affected by this, make the change to `purchaseToken` in your client code and use the latest version of Bubblewrap (v1.13.5 and later) to update and generate a new app package to upload to the Play Console. */
const { purchaseToken } = paymentResponse.details;

let paymentComplete;
if (validatePurchaseOnBackend(purchaseToken)) {
  paymentComplete = await paymentResponse.complete('success');
  // Let user know their purchase transaction has successfully completed and been verified
} else {
  paymentComplete = await paymentResponse.complete('fail');
  // Let user know their purchase transaction failed to verify
}

Passer à un forfait supérieur ou inférieur

Ce parcours d'achat est le même pour les produits intégrés et les abonnements. Toutefois, pour les abonnements, Google Play propose des options d'achat supplémentaires que vous pouvez implémenter : passer à un forfait supérieur ou inférieur. Lorsque vous créez le data pour le mode de paiement, vous devez transmettre les éléments suivants pour lancer un processus de mise à niveau ou de rétrogradation :

sku : ID de l'article du nouvel abonnement vers lequel effectuer la mise à niveau ou le changement de forfait.
oldSku : ID de l'abonnement actuel de l'utilisateur.
purchaseToken : jeton d'achat de l'abonnement actuel de l'utilisateur. Comme indiqué précédemment, il est recommandé de suivre les jetons d'achat dans votre backend. Dans ce scénario et d'autres, vous devez également associer un utilisateur à ses achats et jetons d'achat actuels.
prorationMode : mode de facturation du nouvel abonnement lorsqu'il remplace l'abonnement actuel de l'utilisateur.

Mode de calcul au prorata	Description
immediateAndChargeProratedPrice	L'abonnement passe à un niveau supérieur immédiatement, et le cycle de facturation reste le même. La différence de prix pour la période restante est ensuite facturée à l'utilisateur.
immediateAndChargeFullPrice	L'abonnement passe au forfait supérieur ou inférieur, et l'utilisateur paie immédiatement le tarif complet du nouveau forfait. La valeur restante de l'abonnement précédent est calculée au prorata de la durée restante au moment du changement de forfait. Ce mode de prorata a été récemment ajouté à la version 4.0 de la Bibliothèque Google Play Billing. Elle est désormais disponible via Bubblewrap à partir de la version 1.13.5.
immediateWithoutProration	DÉSACTIVÉ TEMPORAIREMENT : ce mode de prorata présente un risque de fraude potentiel, car les utilisateurs pourraient bénéficier d'un abonnement supérieur sans paiement supplémentaire pour un cycle de facturation. Veuillez noter que nous avons temporairement désactivé ce mode pendant que nous travaillons sur la résolution du problème.
immediateWithTimeProration	L'abonnement passe à un forfait supérieur ou inférieur immédiatement. Le temps restant est ajusté en fonction de la différence de prix, puis crédité sur le nouvel abonnement en repoussant la date de facturation suivante. Il s'agit du comportement par défaut.
deferred	L'abonnement ne passe à un forfait supérieur ou inférieur qu'au moment du renouvellement. Cela est particulièrement utile pour les rétrogradations.
unknownSubscriptionUpgradeDowngradePolicy	Aucune règle définie. Cette action n'est pas recommandée.

Pour en savoir plus sur les différents modes de prorata dans la bibliothèque Google Play Billing, consultez la documentation de référence. Consultez la documentation Android pour les développeurs pour en savoir plus sur les mises à niveau et les rétrogradations d'abonnements et les recommandations concernant le mode de prorata.

L'utilisation de ces champs supplémentaires ressemblera à ceci :

const paymentMethod = [
  {
    supportedMethods: 'https://play.google.com/billing',
    data: {
      sku: item.itemId,
      oldSku: oldPurchase.itemId,
      purchaseToken: oldPurchase.purchaseToken,
      prorationMode: 'immediateAndChargeProratedPrice',
    },
  },
];

Ici, item correspond à ItemDetails du nouvel abonnement auquel l'utilisateur tente de passer (niveau supérieur ou inférieur), et oldPurchase correspond à PurchaseDetails de l'abonnement actuel de l'utilisateur.

Confirmer un achat

Une fois qu'un utilisateur a acheté un article, vous devez lui accorder les droits d'accès appropriés (à l'article ou au contenu qu'il vient d'acheter). Confirmez ensuite l'achat. Confirmer un achat permet à Google Play de savoir que vous l'avez reçu et traité correctement.

Remarque : Si un achat n'est pas confirmé dans les 72 heures suivant la date de l'achat, le paiement est remboursé à l'utilisateur et l'achat est révoqué. Le jeton d'achat ne sera plus valide. Par conséquent, lorsque vous interrogerez les achats existants, l'achat révoqué ne sera pas renvoyé. Cela permet de s'assurer qu'un utilisateur n'est pas facturé à tort en cas d'erreur réseau qui l'empêche d'accéder à son article.

Vous devez confirmer les achats depuis votre serveur backend à l'aide de l'API Google Play Developer. Nous vous recommandons d'accorder les droits d'accès, puis de confirmer l'achat ensemble sur votre serveur backend.

Une fois qu'un utilisateur a effectué un achat côté client, envoyez le jeton d'achat et l'ID de l'article dans une requête à votre serveur backend.
Sur votre backend, pour obtenir des informations sur l'achat afin de le valider, appelez :
- purchases.products.get pour les articles intégrés à l'application.
- purchases.subscriptions.get pour les abonnements.
Accordez le droit d'accès approprié dans votre base de données backend.
Confirmez ensuite l'achat en appelant :
- purchases.products.acknowledge pour les éléments intégrés.
- purchases.subscriptions.acknowledge pour les abonnements.

Utiliser un achat

Lorsque vous confirmez un achat, Google Play sait que l'utilisateur possède désormais l'article et ne doit plus être autorisé à l'acheter à nouveau. Si l'utilisateur n'a besoin d'acheter l'article qu'une seule fois et qu'il lui appartient pour toujours (par exemple, un skin de personnage de jeu), l'article n'est pas consommable.

Il peut également s'agir d'un article que vous limitez à un seul par utilisateur à la fois. L'utilisateur devra ensuite utiliser l'article avant de pouvoir en acheter un autre. Lorsque l'utilisateur "utilise" l'article, vous devez appeler la méthode consume() pour indiquer à Google Play que l'utilisateur a consommé l'article. Google Play rendra ensuite l'article de nouveau disponible à l'achat pour l'utilisateur.

Pour les articles dont vous autorisez les utilisateurs à posséder plusieurs exemplaires, ils doivent pouvoir être achetés à plusieurs reprises sans avoir besoin d'être utilisés au préalable (nous les appelons "articles réutilisables"). De même, ces articles doivent être "consommés" avant que Google Play n'autorise l'utilisateur à les acheter à nouveau. Par conséquent, même si l'utilisateur n'a pas encore utilisé l'article, vous devez appeler la méthode consume() pour le marquer comme consommé.

// After the user purchases the item, send the purchase token and item ID to your backend to grant the entitlement and acknowledge it right away

. . .
// When the user uses the item or if it is a repeatable item, consume it so it’s available for purchase again.
service.consume(purchaseToken);
}

Vérifier les achats existants

Le dernier flux utilisateur clé consiste à vérifier les achats existants (produits intégrés qui n'ont pas encore été consommés et abonnements en cours) pour informer vos utilisateurs des abonnements ou des articles qu'ils possèdent actuellement. Ces achats existants proviennent d'achats Google Play précédents effectués sur n'importe quel appareil, dans l'application ou sur le Play Store. Les achats effectués en dehors de l'application sur le Play Store sont appelés achats hors application.

Lorsque vous récupérez des achats existants, vous devez également vérifier l'état de confirmation et confirmer tous les achats effectués précédemment, mais qui n'ont pas été correctement confirmés. Il est recommandé de confirmer les achats dès que possible afin que les droits d'accès de l'utilisateur soient à jour et correctement reflétés dans l'application.

La méthode listPurchases() de l'API Digital Goods renvoie une liste de PurchaseDetails contenant les itemId et purchaseToken pour chacun des achats. Vous devrez utiliser l'API Google Play Developer sur votre serveur backend pour vérifier l'état des achats et les confirmer de manière appropriée. Vous saurez :

Appelez la méthode listPurchases() de l'API Digital Goods côté client pour récupérer la liste des achats de l'utilisateur.
Pour chaque achat, transmettez purchaseToken et itemId à votre backend.
Le cas échéant, accordez le droit d'accès dans votre base de données backend.
Appelez ensuite : et vérifiez acknowledgementState.
- purchases.products.get pour les articles intégrés à l'application.
- purchases.subscriptions.get pour les abonnements.
Si la valeur est 0 (non encore reconnue), appelez :
- purchases.products.acknowledge pour les éléments intégrés.
- purchases.subscriptions.acknowledge pour les abonnements.

Découvrez comment valider les achats sur votre serveur backend avant d'accorder des droits.

Historique des achats

Alors que listPurchases renvoie des informations sur les achats existants de l'utilisateur, la méthode listPurchaseHistory() (dans la version 2.1 de l'API) renvoie l'achat le plus récent effectué par l'utilisateur pour chaque article, qu'il ait expiré, été annulé ou été consommé. La méthode listPurchaseHistory() renvoie une liste de PurchaseDetails contenant les itemId et purchaseToken pour chaque achat. Vous devrez les utiliser avec l'API Google Play Developer sur votre serveur backend pour récupérer plus d'informations.

Achats hors application

Les achats hors application sont des achats qui ne sont pas effectués dans le flux d'achat intégré à l'application. Ces achats ont généralement lieu sur le Play Store plutôt que dans votre application. Il existe deux principaux moyens pour les utilisateurs d'effectuer un achat hors application :

Utiliser un code promotionnel : dans le menu utilisateur du Play Store, sous Offres et notifications > Utiliser un code promotionnel ou Paiements et abonnements > Utiliser une e-carte.
Se réabonner : dans le menu utilisateur du Play Store, accédez à Paiements et abonnements > Abonnements. Les utilisateurs peuvent y gérer tous leurs abonnements dans différentes applications. Pour les abonnements expirés ou résiliés, les utilisateurs ont la possibilité de se réabonner.

Lorsque les utilisateurs se réabonnent depuis le Play Store, leurs achats ne sont pas confirmés automatiquement, ce qui peut entraîner leur remboursement. Ce comportement est intentionnel, car les utilisateurs ne doivent être facturés pour leur abonnement que s'ils ouvrent l'application pour l'utiliser. L'utilisateur peut voir un message "Confirmer l'abonnement" comme celui-ci, lui rappelant d'ouvrir l'application.

Les utilisateurs sont invités à confirmer leur abonnement en ouvrant l'application pour accuser réception de l'achat.

En tant que développeur, il vous incombe de confirmer ces achats une fois que l'utilisateur lance l'application. C'est pourquoi nous vous recommandons de vérifier les achats existants (généralement lors du premier lancement de l'application) et de confirmer tous les achats qui ne l'ont pas encore été.

Autoriser les utilisateurs à gérer les abonnements

Pour offrir une bonne expérience utilisateur, il est important de permettre aux utilisateurs de gérer et de résilier leurs abonnements dans l'application. Nous vous recommandons de créer un lien profond sur une page ou un menu de paramètres qui redirige l'utilisateur vers la page de gestion des abonnements du Play Store pour votre application. Remplacez l'URL suivante par les valeurs appropriées pour "sub-product-id" et "app-package-name" :

https://play.google.com/store/account/subscriptions?sku=sub-product-id&package=app-package-name

Étapes suivantes

Ces flux utilisateur et extraits de code constituent une implémentation de base pour montrer comment utiliser l'API Digital Goods et l'API Payment Request dans votre PWA afin d'implémenter Play Billing. Vous devez utiliser les API de manière appropriée dans le contexte et les cas d'utilisation de votre application. Pour obtenir un exemple d'implémentation de bout en bout, consultez notre exemple Open Source.

Ensuite, découvrez comment implémenter des composants essentiels de Google Play Billing dans votre serveur backend pour sécuriser votre application et la maintenir à jour avec les droits d'accès de vos utilisateurs.

Implémenter Play Billing dans votre PWA Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.