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 zur Verwaltung Ihres Katalogs, Ihrer Preise und Abos, nützliche Berichte und einen Bezahlvorgang, der vom Play Store unterstützt wird und 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 Ihrer PWA Google Play Billing-Unterstützung hinzufügen und sie für die Bereitstellung im Google Play Store sowohl für ChromeOS als auch für den Play Store verpacken.

Sie verwenden zwei Webplattform-APIs, um Ihrer PWA Play Billing-Unterstützung hinzuzufügen. Mit der Digital Goods API werden SKU-Informationen erfasst und Käufe und Berechtigungen aus dem Play Store geprüft. 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, mit Ihrer App über Google Play Billing im Play Store Einnahmen zu erzielen:

  • 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.
  • Abos bieten Nutzern gegen eine wiederkehrende Gebühr kontinuierlichen Zugriff auf Inhalte oder Dienstleistungen, 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 finden Sie in der Kurzanleitung. Wenn Sie Bubblewrap bereits installiert haben, aktualisieren Sie es auf Version 1.8.2 oder höher.

Bei Bubblewrap ist die Funktion ebenfalls ausgeblendet. Um sie zu aktivieren, müssen Sie die Projektkonfiguration im twa-manifest.json im Stammverzeichnis des Projekts ändern und sowohl alphaDependencies als auch das playBilling-Feature 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 in den Play Store hochzuladen.

Funktion zur Erkennung der Digital Goods API und der Verfügbarkeit von Google Play Billing

Die Digital Goods API wird derzeit nur von Chrome unterstützt, wenn die PWA in einer vertrauenswürdigen Webaktivität ausgeführt wird. Sie können prüfen, ob sie verfügbar ist, indem Sie im window-Objekt nach getDigitalGoodsService suchen:

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

Die Digital Goods API kann in jedem Browser verfügbar sein und verschiedene Shops unterstützen. Um zu prüfen, ob ein bestimmtes Geschäfts-Back-End unterstützt wird, müssen Sie getDigitalGoodsService() aufrufen und dabei die Geschäfts-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 der Informationen wie der Produkttitel, die Beschreibung und vor allem der Preis aus dem Zahlungs-Back-End 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 Zahlungsanfrage nimmt zwei Parameter entgegen: eine Liste von Zahlungsmethoden und eine Liste von Zahlungsdetails.

Wenn Sie sich in der Funktion „Vertrauenswürdige Webaktivitäten“ befinden, müssen Sie die Google Play-Abrechnung als Zahlungsmethode verwenden. Legen Sie dazu https://play.google.com/billing als Kennung fest und fügen Sie die Artikelnummer des Produkts als Datenelement 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 der Play-Abrechnung ignoriert und die Werte verwendet, die beim Erstellen der Artikelnummer in der Play Console festgelegt wurden. Sie können also mit falschen Werten ausgefüllt werden:

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

const request = new PaymentRequest(paymentMethods, paymentDetails);

Rufe show() für das Zahlungsanfrageobjekt auf, um den Zahlungsvorgang zu starten. Wenn die Zusicherung erfolgreich ist, war die Zahlung möglicherweise erfolgreich. Wenn die Zahlung fehlschlägt, hat der Nutzer die Zahlung wahrscheinlich abgebrochen.

Wenn die Zusicherung erfolgreich ist, müssen Sie den Kauf bestätigen. Zum Schutz vor Betrug muss dieser Schritt über Ihr Backend implementiert werden. In der Play Billing-Dokumentation erfahren Sie, wie Sie die Bestätigung in Ihrem Backend implementieren. Wenn du den Kauf nicht bestätigst, erhält der Nutzer nach drei Tagen eine Erstattung und Google Play widerruft den Kauf.

...
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 aufgebraucht zu kennzeichnen und einen erneuten Kauf zu ermöglichen.

Zusammengenommen sieht eine Kaufmethode 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 bestehender Käufe prüfen

Mit der Digital Goods API können Sie prüfen, ob der Nutzer bestehende Berechtigungen (noch nicht in Anspruch genommene In-App-Käufe oder laufende Abos) aus früheren Käufen hat, die er auf einem anderen Gerät, bei einer früheren Installation, über einen Gutscheincode oder beim letzten Öffnen der App getätigt hat.


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

Prüfen Sie auch, ob Käufe, die Sie zuvor getätigt haben, nicht berücksichtigt wurden. Wir empfehlen, Käufe so schnell wie möglich zu bestätigen, damit die Berechtigungen Ihrer Nutzer in Ihrer App korrekt angezeigt 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 Entwicklungs-Android-Gerät

Sie können die Digital Goods API auf einem Android-Entwicklungsgerät für Tests aktivieren:

  • Sie benötigen Android 9 oder höher mit aktiviertem Entwicklermodus.
  • 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 Namen des Flags:
    • #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-Version 89 in der stabilen Version verfügbar. In der Zwischenzeit kannst du die Digital Goods API testen:

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

Mit Testnutzern und QA-Teams

Der Play Store bietet Funktionen für Tests, darunter Nutzertestkonten und Test-SKUs. Weitere Informationen finden Sie in der Testdokumentation für die Google Play-Abrechnung.

Was ist der nächste Schritt?

Wie in diesem Dokument erläutert, umfasst die Play Billing API clientseitige Komponenten, die von der Digital Goods API verwaltet werden, und serverseitige Komponenten.