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

Bandarra
André Cipriani Bandarra
Twitter GitHub Glitch Mastodon Startseite

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 für die Verwaltung deines Katalogs, deiner Preise und Abos, nützliche Berichte und einen Zahlungsvorgang über den Play Store, mit dem deine Nutzer bereits vertraut sind.

Für Apps, die mithilfe von Trusted Web Activitys erstellt wurden und über den Google Play Store bereitgestellt werden, können Sie jetzt die Payment Request API und die Digital Goods API für die Einbindung in Google Play Billing verwenden. Sie ist ab Chrome 101 für Android und ChromeOS verfügbar.

In diesem Leitfaden erfährst du, wie du Google Play Billing-Support zu deiner PWA hinzufügen und sie für den Vertrieb im Google Play Store sowohl für ChromeOS als auch für den Play Store verpacken kannst.

Du verwendest zwei Webplattform-APIs, um deiner PWA Play Billing-Unterstützung hinzuzufügen. Die Digital Goods API wird verwendet, um SKU-Informationen zu erfassen und auf Käufe und Berechtigungen im Play Store zu prüfen. 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 Ihre App mit Google Play Billing im Play Store monetarisieren können:

  • In-App-Käufe ermöglichen den Verkauf von langlebigen und kurzfristig nutzbaren virtuellen Waren wie zusätzliche Funktionen oder das Entfernen von Werbung.
  • Abos: Bieten Sie Ihren Nutzern gegen eine wiederkehrende Gebühr dauerhaften Zugriff auf Inhalte oder Dienste, z. B. Nachrichtenabos oder Mitgliedschaften.

Voraussetzungen

Für die Einrichtung von Google Play Billing benötigen Sie Folgendes:

Bubblewrap-Projekt aktualisieren

Wenn Bubblewrap noch nicht installiert ist, müssen Sie es installieren. Weitere Informationen zu den ersten Schritten finden Sie in der Kurzanleitung. Wenn Sie Bubblewrap bereits haben, aktualisieren Sie auf Version 1.8.2 oder höher.

Bubblewrap hat auch die Funktion hinter einer Flagge. Wenn Sie sie aktivieren möchten, müssen Sie die Projektkonfiguration im twa-manifest.json im Stammverzeichnis des Projekts ändern und sowohl alphaDependencies als auch das Feature playBilling aktivieren:

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

Nachdem die Konfigurationsdatei aktualisiert wurde, 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.

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

Die Digital Goods API wird derzeit von Chrome nur unterstützt, wenn die PWA in einer Trusted Web Activity ausgeführt wird. Sie können feststellen, 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 ist möglicherweise in jedem Browser verfügbar und unterstützt verschiedene Shops. Um zu prüfen, ob ein bestimmtes Speicher-Back-End unterstützt wird, müssen Sie getDigitalGoodsService() aufrufen und dabei die Speicher-ID als Parameter übergeben. Der Google Play Store ist am String https://play.google.com/billing zu erkennen:

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 Artikelnummer abrufen

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

Sie können diese Informationen dann auf Ihrer Nutzungsoberflä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 PaymentRequest verwendet zwei Parameter: eine Liste mit Zahlungsmethoden und eine Liste mit Zahlungsdetails.

Wenn du dich im Trusted Web Activity-Konto befindest, musst du die Google Play Billing-Zahlungsmethode verwenden, indem du https://play.google.com/billing als Kennung festlegst und die Produkt-Artikelnummer als Datenmitglied hinzufügst:

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

   ...
}

Obwohl die Zahlungsdetails erforderlich sind, ignoriert Play Billing diese Werte und verwendet die Werte, die beim Erstellen der Artikelnummer in der Play Console festgelegt wurden, sodass sie mit falschen Werten gefüllt werden können:

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

const request = new PaymentRequest(paymentMethods, paymentDetails);

Rufen Sie show() für das Zahlungsanforderungsobjekt auf, um den Zahlungsablauf zu starten. Wenn das Versprechen erfolgreich ist, ist die Zahlung möglicherweise erfolgreich. Wenn ein Fehler auftritt, hat der Nutzer die Zahlung wahrscheinlich abgebrochen.

Wenn das Versprechen erfolgreich ist, musst du den Kauf bestätigen und bestätigen. Zum Schutz vor Betrug muss dieser Schritt mithilfe Ihres Back-Ends implementiert werden. Wie du die Verifizierung in deinem Back-End implementierst, erfährst du in der Play Billing-Dokumentation. Wenn du den Kauf nicht bestätigst, erhält der Nutzer nach drei Tagen eine Erstattung und Google Play wird den Kauf widerrufen.

...
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 markieren und einen neuen Kauf zu ermöglichen.

Wenn alles zusammengenommen wird, 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 kannst du prüfen, ob der Nutzer bestehende Berechtigungen (In-App-Käufe, die noch nicht eingelöst wurden oder laufende Abos) aus früheren Käufen hat, die er bereits getätigt hat, ob auf einem anderen Gerät, bei einer vorherigen Installation, über einen Gutscheincode eingelöst oder erst 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}`);
}

Dies ist auch ein guter Zeitpunkt, um zu prüfen, ob Käufe bereits getätigt, aber nicht bestätigt wurden. Es wird empfohlen, Käufe so bald wie möglich zu bestätigen, damit die Berechtigungen deiner Nutzer in deiner 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 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. Gehen Sie dazu zu chrome://flags und suchen Sie anhand des Namens nach dem Flag:
    • #enable-debug-for-store-billing
  • Achten Sie darauf, dass die Website mit einem HTTPS-Protokoll gehostet wird. Wenn du http verwendest, wird die API zu undefined

Auf einem ChromeOS-Gerät

Die Digital Goods API ist ab Version 89 unter ChromeOS (stabile Version) verfügbar. In der Zwischenzeit ist es möglich, die Digital Goods API zu testen:

  • Installieren Sie die App über den Play Store auf dem Gerät.
  • Achten Sie darauf, dass die Website mit einem HTTPS-Protokoll gehostet wird. Wenn du http verwendest, wird die API zu undefined

Mit Testnutzern und QA-Teams

Im Play Store gibt es Angebote für Tests, einschließlich Nutzertestkonten und Test-Artikelnummern. Weitere Informationen finden Sie in der Testdokumentation für Google Play Billing.

Wie geht es weiter?

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