Recevez des paiements via Google Play Billing avec l'API Digital Goods et l'API Payment Request

André Cipriani Bandarra

Si votre application est distribuée via Google Play et que vous souhaitez vendre des produits numériques ou proposer des abonnements, vous devez utiliser Google Play Billing. Google Play Billing propose des outils pour gérer votre catalogue, vos prix et vos abonnements, des rapports utiles et un parcours de paiement optimisé par le Play Store, qui est déjà familier à vos utilisateurs.

Pour les applications créées à l'aide d'activités Web fiables et diffusées via le Google Play Store, vous pouvez désormais utiliser l'API Payment Request et l'API Digital Goods pour l'intégration à Google Play Billing. Il est disponible dans Chrome 101 ou version ultérieure pour Android et ChromeOS.

Dans ce guide, vous allez découvrir comment ajouter la prise en charge de Google Play Billing à votre PWA et le empaqueter pour le distribuer sur le Google Play Store à la fois pour ChromeOS et le Play Store.

Vous allez utiliser deux API de plate-forme Web pour ajouter la prise en charge de Play Billing à votre PWA. L'API Digital Goods permet de collecter des informations sur les codes SKU et de vérifier les achats et les droits d'accès sur le Play Store. L'API Payment Request permet de configurer le Google Play Store en tant que mode de paiement et de terminer le parcours d'achat.

Comment monétiser des applications sur le Play Store

Il existe deux façons de monétiser votre application avec Google Play Billing sur le Play Store:

  • Les achats via une application permettent de vendre des biens virtuels durables et consommables, comme des fonctionnalités supplémentaires ou la suppression d'annonces.
  • Les abonnements permettent à vos utilisateurs d'accéder en permanence à des contenus ou services moyennant le paiement de frais récurrents, comme des abonnements à des actualités ou des abonnements.

Conditions requises

Pour configurer la facturation Google Play, vous avez besoin des éléments suivants:

Mettre à jour le projet Bubblewrap

Si Bubblewrap n'est pas installé, vous devez l'installer. Pour en savoir plus, consultez le guide de démarrage rapide. Si vous disposez déjà de Bubblewrap, assurez-vous de passer à la version 1.8.2 ou ultérieure.

Bubblewrap propose également cette fonctionnalité derrière un indicateur. Pour l'activer, vous devez modifier la configuration du projet dans le fichier twa-manifest.json, situé à la racine du projet, et activer à la fois alphaDependencies et la fonctionnalité playBilling:

  ...,
  "enableNotifications": true,
  "features": {
    "playBilling": {
      "enabled": true
    }
  },
  "alphaDependencies": {
    "enabled": true
  },
  ...

Une fois le fichier de configuration mis à jour, exécutez bubblewrap update pour appliquer la configuration au projet, puis bubblewrap build pour générer un nouveau package Android et l'importer sur le Play Store.

Fonctionnalité de détection de l'API Digital Goods et de la disponibilité de Google Play Billing

L'API Digital Goods n'est actuellement compatible avec Chrome que lorsque la PWA est exécutée dans une activité Web sécurisée. Vous pouvez détecter si elle est disponible en recherchant getDigitalGoodsService sur l'objet window:

if ('getDigitalGoodsService' in window) {
 // Digital Goods API is supported!
}

L'API Digital Goods peut être disponible dans n'importe quel navigateur et prendre en charge différents magasins. Pour vérifier si le backend d'un magasin donné est pris en charge, vous devez appeler getDigitalGoodsService() en transmettant l'ID de magasin en tant que paramètre. Le Google Play Store est identifié par la chaîne https://play.google.com/billing:

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
  try {
    const service =
        await window.getDigitalGoodsService('https://play.google.com/billing');
    // Google Play Billing is supported!

  } catch (error) {
    // Google Play Billing is not available. Use another payment flow.
    return;
  }
}

Récupérer les détails d'un SKU

L'API Digital Goods fournit getDetails(), qui permet de récupérer des informations telles que le titre, la description et surtout le prix du produit à partir du backend de paiement.

Vous pouvez ensuite utiliser ces informations dans votre interface pour fournir d'autres détails à l'utilisateur:

const skuDetails = await service.getDetails(['shiny_sword', 'gem']);
for (item of skuDetails) {
  // Format the price according to the user locale.
  const localizedPrice = new Intl.NumberFormat(
      navigator.language,
      {style: 'currency', currency: item.price.currency}
    ).format(item.price.value);

  // Render the price to the UI.
  renderProductDetails(
        item.itemId, item.title, localizedPrice, item.description);
}

Créer le parcours d'achat

Le constructeur d'une PaymentRequest utilise deux paramètres: une liste de modes de paiement et une liste des détails du paiement.

Lorsque vous êtes dans l'activité Web fiable, vous devez utiliser le mode de paiement Google Play Billing, en définissant https://play.google.com/billing comme identifiant et en ajoutant le SKU du produit en tant que membre des données:

async function makePurchase(service, sku) {
   // Define the preferred payment method and item ID
   const paymentMethods = [{
       supportedMethods: "https://play.google.com/billing",
       data: {
           sku: sku,
       }
   }];

   ...
}

Même si les informations de paiement sont obligatoires, Play Billing ignorera ces valeurs et utilisera celles définies lors de la création du SKU dans la Play Console. Elles peuvent donc être renseignées avec des valeurs factices:

const paymentDetails = {
    total: {
        label: `Total`,
        amount: {currency: `USD`, value: `0`}
    }
};

const request = new PaymentRequest(paymentMethods, paymentDetails);

Appelez show() sur l'objet de la demande de paiement pour lancer le parcours de paiement. Si la promesse est réussie, il se peut que le paiement ait bien été effectué. Si l'opération échoue, l'utilisateur a probablement interrompu le paiement.

Si la promesse aboutit, vous devrez valider et confirmer l'achat. Pour vous protéger contre la fraude, vous devez mettre en œuvre cette étape à l'aide de votre backend. Consultez la documentation de Play Billing pour découvrir comment implémenter la validation dans votre backend. Si vous ne confirmez pas l'achat, l'utilisateur recevra un remboursement et Google Play annulera l'achat au bout de trois jours.

...
const request = new PaymentRequest(paymentMethods, paymentDetails);
try {
    const paymentResponse = await request.show();
    const {purchaseToken} = paymentResponse.details;

    // Call backend to validate and acknowledge the purchase.
    if (await acknowledgePurchaseOnBackend(purchaseToken, sku)) {
        // Optional: tell the PaymentRequest API the validation was
        // successful. The user-agent may show a "payment successful"
        // message to the user.
        const paymentComplete = await paymentResponse.complete('success');
    } else {
        // Optional: tell the PaymentRequest API the validation failed. The
        // user agent may show a message to the user.
        const paymentComplete = await paymentResponse.complete('fail');
    }
} catch(e) {
    // The purchase failed, and we can handle the failure here. AbortError
    // usually means a user cancellation
}
...

Vous pouvez éventuellement appeler consume() sur un purchaseToken pour marquer l'achat comme utilisé et permettre de l'acheter à nouveau.

En résumé, une méthode d'achat se présente comme suit:

async function makePurchase(service, sku) {
    // Define the preferred payment method and item ID
    const paymentMethods = [{
        supportedMethods: "https://play.google.com/billing",
        data: {
            sku: sku,
        }
    }];

    // The "total" member of the paymentDetails is required by the Payment
    // Request API, but is not used when using Google Play Billing. We can
    // set it up with bogus details.
    const paymentDetails = {
        total: {
            label: `Total`,
            amount: {currency: `USD`, value: `0`}
        }
    };

    const request = new PaymentRequest(paymentMethods, paymentDetails);
    try {
        const paymentResponse = await request.show();
        const {purchaseToken} = paymentResponse.details;

        // Call backend to validate and acknowledge the purchase.
        if (await acknowledgePurchaseOnBackend(purchaseToken, sku)) {
            // Optional: consume the purchase, allowing the user to purchase
            // the same item again.
            service.consume(purchaseToken);

            // Optional: tell the PaymentRequest API the validation was
            // successful. The user-agent may show a "payment successful"
            // message to the user.
            const paymentComplete =
                    await paymentResponse.complete('success');
        } else {
            // Optional: tell the PaymentRequest API the validation failed.
            // The user agent may show a message to the user.
            const paymentComplete = await paymentResponse.complete('fail');
        }
    } catch(e) {
        // The purchase failed, and we can handle the failure here.
        // AbortError usually means a user cancellation
    }
}

Vérifier l'état des achats existants

L'API Digital Goods vous permet de vérifier si l'utilisateur dispose de droits d'accès existants (achats intégrés qui n'ont pas encore été consommés ou abonnements en cours) issus d'achats précédents qu'il a déjà effectués, que ce soit sur un autre appareil, à partir d'une installation précédente, via un code promotionnel ou simplement la dernière fois qu'il a ouvert l'application.


const service =
     await window.getDigitalGoodsService('https://play.google.com/billing');
...
const existingPurchases = await service.listPurchases();
for (const p of existingPurchases) {
    // Update the UI with items the user is already entitled to.
    console.log(`Users has entitlement for ${p.itemId}`);
}

C'est également l'occasion de vérifier les achats qui ont déjà été effectués, mais qui n'ont pas été confirmés. Nous vous recommandons de confirmer les achats dès que possible pour vous assurer que les droits d'accès de vos utilisateurs sont correctement reflétés dans votre application.

const service =
     await window.getDigitalGoodsService("https://play.google.com/billing");
...
const existingPurchases = await service.listPurchases();
for (const p of existingPurchases) {
    await verifyOrAcknowledgePurchaseOnBackend(p.purchaseToken, p.itemId);

    // Update the UI with items the user is already entitled to.
    console.log(`Users has entitlement for ${p.itemId}`);
}

Tester votre intégration

Sur un appareil Android de développement

Vous pouvez activer l'API Digital Goods sur un appareil Android de développement à des fins de test:

  • Assurez-vous d'utiliser Android 9 ou une version ultérieure avec le mode développeur activé.
  • Installez Chrome 101 ou une version ultérieure.
  • Activez les indicateurs suivants dans Chrome en accédant à chrome://flags et en recherchant l'indicateur par nom :
    • #enable-debug-for-store-billing
  • Assurez-vous que le site est hébergé à l'aide du protocole HTTPS. Si vous utilisez HTTP, l'API sera undefined.

Sur un appareil ChromeOS

L'API Digital Goods sera disponible sur ChromeOS stable à partir de la version 89. En attendant, vous pouvez tester l'API Digital Goods:

  • Installez votre application depuis le Play Store sur l'appareil.
  • Assurez-vous que le site est hébergé à l'aide du protocole HTTPS. Si vous utilisez HTTP, l'API sera undefined.

Avec les utilisateurs tests et les équipes de contrôle qualité

Le Play Store fournit des affordances pour les tests, y compris des comptes de test utilisateur et des SKU de test. Pour en savoir plus, consultez la documentation de test de Google Play Billing.

Où aller ensuite ?

Comme indiqué dans ce document, l'API Play Billing comporte des composants côté client, gérés par l'API Digital Goods, et des composants côté serveur.