Zahlungen über Google Play Billing mit der Digital Goods API und der Payment Request API erhalten

André Cipriani Bandarra

Wenn Ihre App über Google Play vertrieben wird und Sie digitale Waren verkaufen oder Abos anbieten möchten, müssen Sie Google Play Billing verwenden. Google Play Billing bietet Tools zum Verwalten Ihres Katalogs, Ihrer Preise und Abos, nützliche Berichte und einen von Google Play unterstützten Abrechnungsablauf, der Ihren Nutzern bereits vertraut ist.

Für Apps, die mit Trusted Web Activities erstellt und über den Google Play Store bereitgestellt werden, können Sie jetzt die Payment Request API und die Digital Goods API verwenden, um die Google Play-Abrechnung zu integrieren. Sie ist in Chrome 101 und höher für Android und ChromeOS verfügbar.

In dieser Anleitung erfahren Sie, wie Sie Google Play Billing-Unterstützung in Ihre PWA einfügen und sie für die Verteilung im Google Play Store für ChromeOS und den Play Store verpacken.

Sie verwenden zwei Webplattform-APIs, um Ihrer PWA Unterstützung für Play Billing hinzuzufügen. Die Digital Goods API wird verwendet, um SKU-Informationen zu erfassen und im Play Store nach Käufen und Berechtigungen zu suchen. Die Payment Request API wird verwendet, um den Google Play Store als Zahlungsmethode zu konfigurieren und den Kaufvorgang abzuschließen.

Apps im Play Store monetarisieren

Es gibt zwei Möglichkeiten, wie Sie mit Ihrer App im Play Store über Google Play-Abrechnung Einnahmen erzielen können:

  • Mit In-App-Käufen können Sie sowohl langlebige als auch Verbrauchsgüter verkaufen, z. B. zusätzliche Funktionen oder die Entfernung von Anzeigen.
  • Mit Abos können Sie Ihren Nutzern für eine wiederkehrende Gebühr kontinuierlichen Zugriff auf Inhalte oder Dienste bieten, z. B. Nachrichtenabos oder Mitgliedschaften.

Voraussetzungen

Für die Einrichtung der Google Play-Abrechnung benötigen Sie Folgendes:

Bubblewrap-Projekt aktualisieren

Wenn Bubblewrap noch nicht installiert ist, müssen Sie es installieren. Weitere Informationen zum Einstieg finden Sie in der Kurzanleitung. Wenn Sie Bubblewrap bereits installiert haben, müssen Sie ein Update auf Version 1.8.2 oder höher durchführen.

Auch in Bubblewrap ist die Funktion hinter einem Flag verfügbar. Dazu müssen Sie die Projektkonfiguration in der Datei twa-manifest.json im Stammverzeichnis des Projekts ändern und sowohl alphaDependencies als auch die Funktion playBilling aktivieren:

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

Nachdem Sie die Konfigurationsdatei aktualisiert haben, führen Sie bubblewrap update aus, um die Konfiguration auf das Projekt anzuwenden, gefolgt von bubblewrap build, um ein neues Android-Paket zu generieren und dieses Paket in den Play Store hochzuladen.

Verfügbarkeit der Digital Goods API und von Google Play Billing erkennen

Die Digital Goods API wird derzeit nur von Chrome unterstützt, wenn die PWA in einer Trusted Web Activity ausgeführt wird. Sie können prüfen, ob sie verfügbar ist, indem Sie das window-Objekt auf getDigitalGoodsService prüfen:

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

Die Digital Goods API ist möglicherweise in jedem Browser verfügbar und unterstützt verschiedene Stores. Wenn Sie prüfen möchten, ob ein bestimmtes Store-Backend unterstützt wird, müssen Sie getDigitalGoodsService() aufrufen und die Store-ID als Parameter übergeben. Der Google Play Store wird durch den String https://play.google.com/billing identifiziert:

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

Details zu einer SKU abrufen

Die Digital Goods API bietet getDetails(), mit dem Informationen wie Produkttitel, Beschreibung und vor allem der Preis aus dem Zahlungs-Backend abgerufen werden können.

Sie können diese Informationen dann in Ihrer Benutzeroberfläche verwenden und dem Nutzer weitere Details zur Verfügung stellen:

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);
}

Kaufvorgang erstellen

Der Konstruktor für eine PaymentRequest akzeptiert zwei Parameter: eine Liste von Zahlungsmethoden und eine Liste von Zahlungsdetails.

In der vertrauenswürdigen Web-Aktivität müssen Sie die Zahlungsmethode für die Google Play-Abrechnung verwenden. Dazu legen Sie https://play.google.com/billing als Kennung fest und fügen die Produkt-SKU als Datenmember hinzu:

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

   ...
}

Auch wenn die Zahlungsdetails erforderlich sind, werden diese Werte von Play Billing ignoriert. Stattdessen werden die Werte verwendet, die beim Erstellen der Artikelnummer in der Play Console festgelegt wurden. Daher können Sie Platzhalterwerte eingeben:

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

const request = new PaymentRequest(paymentMethods, paymentDetails);

Rufen Sie show() für das Zahlungsanfrageobjekt auf, um den Zahlungsablauf zu starten. Wenn das Promise erfolgreich ist, wurde die Zahlung möglicherweise erfolgreich ausgeführt. Wenn der Vorgang fehlschlägt, hat der Nutzer die Zahlung wahrscheinlich abgebrochen.

Wenn das Versprechen erfolgreich ist, müssen Sie den Kauf bestätigen. Um Betrug zu verhindern, muss dieser Schritt in Ihrem Backend implementiert werden. Weitere Informationen zum Implementieren der Überprüfung in Ihrem Backend Wenn Sie den Kauf nicht bestätigen, erhält der Nutzer nach drei Tagen eine Erstattung und Google Play macht den Kauf rückgängig.

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

Optional kann consume() für ein purchaseToken aufgerufen werden, um den Kauf als verbraucht zu markieren und einen erneuten Kauf zu ermöglichen.

Eine Kaufmethode sieht so aus:

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

Status vorhandener Käufe prüfen

Mit der Digital Goods API können Sie prüfen, ob der Nutzer bereits Berechtigungen hat (In-App-Käufe, die noch nicht genutzt wurden, oder laufende Abos) aus früheren Käufen, die er bereits getätigt hat, sei es auf einem anderen Gerät, bei einer früheren Installation, durch Einlösen eines Gutscheincodes oder einfach beim letzten Öffnen der App.


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}`);
}

Das ist auch ein guter Zeitpunkt, um nach Käufen zu suchen, die zuvor getätigt, aber nicht bestätigt wurden. Es wird empfohlen, Käufe so schnell wie möglich zu bestätigen, damit die Berechtigungen Ihrer Nutzer in Ihrer App richtig wiedergegeben werden.

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}`);
}

Integration testen

Auf einem Android-Entwicklungsgerät

Es ist möglich, die Digital Goods API auf einem Android-Entwicklungsgerät zum Testen zu aktivieren:

  • Achten Sie darauf, dass Sie Android 9 oder höher verwenden und der Entwicklermodus aktiviert ist.
  • Installieren Sie Chrome 101 oder höher.
  • Aktivieren Sie die folgenden Flags in Chrome. Rufen Sie dazu chrome://flags auf und suchen Sie nach dem Flag anhand des Namens:
    • #enable-debug-for-store-billing
  • Die Website muss über ein HTTPS-Protokoll gehostet werden. Wenn Sie HTTP verwenden, ist die API undefined.

Auf einem ChromeOS-Gerät

Die Digital Goods API ist ab ChromeOS 89 in der stabilen Version verfügbar. In der Zwischenzeit können Sie die Digital Goods API testen:

  • Installieren Sie die App aus dem Play Store auf dem Gerät.
  • Die Website muss über ein HTTPS-Protokoll gehostet werden. Wenn Sie HTTP verwenden, ist die API undefined.

Mit Testnutzern und QA-Teams

Der Play Store bietet Möglichkeiten zum Testen, darunter Nutzer-Testkonten und Test-SKUs. Weitere Informationen finden Sie in der Dokumentation zum Testen der Google Play-Abrechnung.

Wie geht es weiter?

Wie in diesem Dokument beschrieben, hat die Play Billing API clientseitige Komponenten, die von der Digital Goods API verwaltet werden, und serverseitige Komponenten.