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 biens 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 distribuées via le Google Play Store, vous pouvez désormais utiliser l'API Payment Request et l'API Digital Goods pour les intégrer à Google Play Billing. Elle est disponible sur 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 comme mode de paiement et de finaliser le parcours d'achat.

Monétiser des applications sur le Play Store

Votre application peut être monétisée de deux manières 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 avez déjà Bubblewrap, veillez à 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 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 un backend de plate-forme de téléchargement d'applications particulier est compatible, vous devez appeler getDigitalGoodsService() en transmettant l'ID de la plate-forme de téléchargement d'applications 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 utilisateur et fournir plus de 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'un objet PaymentRequest accepte deux paramètres: une liste de modes de paiement et une liste d'informations de paiement.

Dans l'activité Web sécurisée, vous devez utiliser le mode de paiement de facturation Google Play en définissant https://play.google.com/billing comme identifiant et en ajoutant le SKU du produit en tant que membre de 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 aboutit, cela signifie que le paiement a 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, cette étape doit être implémentée à l'aide de votre backend. Consultez la documentation Play Billing pour découvrir comment implémenter la validation dans votre backend. Si vous ne confirmez pas l'achat, au bout de trois jours, l'utilisateur recevra un remboursement et Google Play annulera l'achat.

...
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
}
...

consume() peut être appelé 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, à partir d'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 le moment de vérifier les achats effectués précédemment, 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. L'utilisation du protocole HTTP entraîne l'undefined de l'API.

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. L'utilisation du protocole HTTP entraîne l'undefined de l'API.

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

Le Play Store propose des fonctionnalités de test, y compris des comptes utilisateur de test et des codes 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.