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

André Cipani Bandarra
André Cipriani Bandarra
Twitter GitHub Glitch Mastodon Page d'accueil

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, les prix et les abonnements, des rapports utiles et un processus de paiement fourni par le Play Store, que vos utilisateurs connaissent déjà.

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 intégrer Google Play Billing. Elle est disponible à partir de la version 101 de Chrome pour Android et ChromeOS.

Dans ce guide, vous allez découvrir comment ajouter la compatibilité de Google Play Billing à votre PWA et comment la mettre en package en vue de sa distribution sur le Google Play Store pour ChromeOS et le Play Store.

Vous utiliserez deux API de plate-forme Web pour rendre votre PWA compatible avec Play Billing. L'API Digital Goods permet de collecter des informations sur les 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

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

  • Les achats via une application permettent de vendre des biens virtuels durables et consommables, tels que des fonctionnalités supplémentaires, ou de supprimer des annonces.
  • Abonnements : proposez à vos utilisateurs un accès continu à du contenu ou des services, comme des abonnements ou des abonnements à des actualités, moyennant des frais récurrents.

Conditions requises

Pour configurer Google Play Billing, vous devez disposer des éléments suivants:

Mettre à jour le projet Bubblewrap

Si vous n'avez pas installé Bubblewrap, vous devez l'installer. Consultez le guide de démarrage rapide pour savoir comment vous lancer. Si vous utilisez déjà Bubblewrap, assurez-vous de passer à la version 1.8.2 ou ultérieure.

Le papier bulle a également la fonctionnalité derrière un drapeau. Pour l'activer, vous devez modifier la configuration du projet dans le fichier twa-manifest.json, situé à la racine du projet, puis activer 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.

Détection de la disponibilité de l'API Digital Goods et 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 fiable. Il est possible de déterminer si elle est disponible en vérifiant 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 prise en charge par différents magasins. Pour vérifier si un backend de magasin particulier est compatible, 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 d'utilisation et fournir davantage 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'une PaymentRequest utilise deux paramètres: une liste des modes de paiement et une liste des détails du paiement.

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 détails du paiement sont obligatoires, Play Billing ignore ces valeurs et utilise celles définies lors de la création du code SKU dans la Play Console, de sorte qu'elles puissent être remplies par des valeurs erronées:

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

const request = new PaymentRequest(paymentMethods, paymentDetails);

Appelez show() sur l'objet de requête de paiement pour démarrer le flux de paiement. Si la promesse réussit, il est possible que le paiement ait abouti. S'il échoue, il est probable que l'utilisateur ait annulé le paiement.

Si la promesse aboutit, vous devrez vérifier 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 reçoit un remboursement et Google Play révoque 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
}
...

Vous pouvez éventuellement appeler consume() sur un purchaseToken pour marquer l'achat comme utilisé et lui permettre d'être à nouveau acheté.

En résumé, une méthode d'achat ressemble à ceci:

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 existants (achats via une application qui n'ont pas encore été utilisés ou abonnements en cours) pour des achats antérieurs qu'il a déjà effectués, qu'il s'agisse d'un autre appareil, d'une installation précédente, d'un code promotionnel ou uniquement 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 bon moment pour 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

Il est possible d'activer l'API Digital Goods sur un appareil Android de développement à des fins de test:

  • Vérifiez que vous utilisez Android 9 ou une version ultérieure et que le mode développeur est activé.
  • Installez Chrome 101 ou une version ultérieure.
  • Pour activer les indicateurs suivants dans Chrome, accédez à chrome://flags et recherchez l'indicateur par nom :
    • #enable-debug-for-store-billing
  • Vérifiez que le site est hébergé à l'aide d'un protocole HTTPS. Si vous utilisez HTTP, l'API sera undefined

Sur un appareil ChromeOS

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

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

Avec les utilisateurs de test 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 codes SKU de test. Pour en savoir plus, consultez la documentation sur le test Google Play Billing.

Et ensuite ?

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