Diese Seite wurde von der Cloud Translation API übersetzt.

Play Billing in Ihre PWA implementieren

Wenn Ihre PWA bei Google Play gelistet ist und Sie sie durch den Verkauf von In-App-Produkten oder ‑Abos monetarisieren möchten, müssen Sie gemäß der Play-Richtlinie Play Billing implementieren. Sie müssen zwei APIs in Ihre PWA implementieren: die Digital Goods API und die Payment Request API.

Digital Goods API

Die Digital Goods API ist eine Schnittstelle zwischen Ihrer App und Google Play. Damit können Sie die digitalen Produkte und Details abrufen, die Sie für Ihre In‑App-Produkte und Abos in der Play Console eingegeben haben, sowie bestehende Käufe eines Nutzers. Wenn Sie noch keine In‑App-Produkte oder Abos in der Play Console hinzugefügt haben, folgen Sie der Play Console-Einrichtung für Play Billing.

Am 30. November 2021 wurde ChromeOS 96 mit der Implementierung der Digital Goods API 2.0 veröffentlicht.

Der Ursprungstest für die erste Version der Digital Goods API wurde am 30. Januar 2022 beendet. Daher wurde sie eingestellt und es ist nur noch die V2 der API verfügbar.

Am 23. Juni 2022 wurde ChromeOS 103 mit der Implementierung der Digital Goods API 2.1 veröffentlicht. Diese Version enthält keine wichtigen Änderungen, sondern nur neue Methoden und zusätzliche Felder: listPurchaseHistory() und itemType.

Für den Ursprungstest registrieren

Hinweis:Die Digital Goods API ist derzeit über einen Origin Trial verfügbar. Das ist ein Mechanismus, der Entwicklern einen frühen Zugriff auf neue Web-APIs ermöglicht. Sie müssen sich für den Origin-Test der Digital Goods API v2 registrieren und ein Token anfordern, das Sie auf allen Seiten in Ihrem Ursprung bereitstellen müssen.

Nach der Registrierung für den Ursprungstest wird das Datum „Gültig bis“ angezeigt, bis zu dem Ihr Token garantiert funktioniert. Denken Sie daran, Ihre Tokens zu erneuern, wenn das Datum näher rückt, damit Sie weiterhin am Test teilnehmen können. APIs, die als Origin Trial angeboten werden, können sich ändern. Sie sollten sich daher über die neuesten Änderungen an allen Origin Trials, an denen Sie teilnehmen, auf dem Laufenden halten. Bei Problemen finden Sie weitere Informationen in der Dokumentation zur Digital Goods API.

Payment Request API

Die Payment Request API übernimmt die eigentliche Zahlungstransaktion, wenn ein Kauf erfolgt. Dabei werden die Artikeldetails verwendet, die von der Digital Goods API bereitgestellt werden, um den In-App-Kauf mit der entsprechenden Zahlungsmethode durchzuführen. In unserem Fall ist das Google Play Billing.

Digital Goods API erkennen

Sie können prüfen, ob Sie die API auf Ihrer Website über den Ursprungstest richtig aktiviert haben, indem Sie im window-Objekt nach der Methode getDigitalGoodsService suchen.

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
} else {
  console.log('DigitalGoodsService is not available.');
  // Use another payment method
}

Mit dem Google Play-Abrechnungsdienst verbinden

Die Digital Goods API wurde so konzipiert, dass sie mit verschiedenen Browsern und digitalen Shops kompatibel ist. Ähnlich wie die Payment Request API ist sie browserunabhängig und kann mit verschiedenen Zahlungsanbietern verwendet werden. Wenn Sie eine Instanz des mit Google Play Billing verknüpften Dienstes abrufen möchten, übergeben Sie den String "https://play.google.com/billing" als Zahlungsmethode an getDigitalGoodsService().

Wenn die Methode einen Fehler ausgibt, ist die Zahlungsmethode von Google Play Billing nicht verfügbar (z.B. wenn der Nutzer über den Browser auf Ihre PWA zugreift). Stattdessen sollten Sie eine andere Zahlungsmethode für Transaktionen anbieten.

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
  try {
    const service = await window.getDigitalGoodsService('https://play.google.com/billing');
    // Google Play Billing service is available
  } catch (error) {
    // Google Play Billing service is not available. Use another payment flow.
  }
}

Artikeldetails abrufen

Sobald Sie den Dienst für digitale Waren mit Google Play verbunden haben, können Sie mit der API Informationen zu Produkten und Käufen abrufen.

Mit der Methode getDetails() können Sie Informationen zu den Artikeln abrufen, die Sie in der Play Console eingerichtet haben. Informationen wie Produkttitel, Beschreibung und Preis sollten dem Nutzer in der Benutzeroberfläche Ihrer App angezeigt werden, damit er weiß, was zum Kauf angeboten wird und wie viel es kostet.

Für die Methode getDetails() ist eine Liste von Artikel-IDs erforderlich, die den Produkt-IDs der In-App-Produkte und Abos entsprechen, die Sie in der Play Console erstellt haben.

const itemDetails = await service.getDetails(['product_1', 'product_2', 'product_3']);
for (const item of itemDetails) {
  // Display item information to user
  displayItem(item.title, item.description, item.price);
}

Damit der richtige Preis für den Standort des Nutzers angezeigt wird, müssen Sie einige zusätzliche Formatierungen vornehmen:

const localePrice = new Intl.NumberFormat(navigator.language, {
  style: 'currency',
  currency: item.price.currency,
}).format(item.price.value);

Hinweis:Die Digital Goods API bietet keine Methode zum Abrufen einer Liste von Artikel-IDs. Stattdessen müssen Sie sie entweder in Ihren Client einprogrammieren oder von Ihrem Backend-Server abrufen. Mit der Google Play Developer API können Sie die Liste der Artikel-IDs über ein Back-End abfragen. Weitere Informationen zum Implementieren wichtiger Play Billing-Komponenten auf Ihrem Backend-Server Unabhängig davon, für welche Lösung Sie sich entscheiden, müssen die Artikel-IDs mit den IDs in der Play Console übereinstimmen.

In Version 2.1 der API ist itemType eines der Felder, die von getDetails() zurückgegeben werden. Es handelt sich um einen Enum, dessen Wert ”product” oder ”subscription” ist, um anzugeben, ob das entsprechende Element ein In-App-Produkt oder ein Abo ist. Es kann nützlich sein, zwischen den beiden Produkttypen zu unterscheiden, wenn Sie unterschiedliche Testgruppen auf die einzelnen Produkttypen anwenden müssen. So haben Sie beispielsweise eine bestimmte Seite für Nutzer, die ein Abo abschließen möchten, und eine andere Seite für die anderen Produkte, für die kein Abo erforderlich ist. Außerdem ist es nützlich, um die richtige Google Play Developer API-REST-Ressource für Ihr Backend (purchases.products oder purchases.subscriptions) zu ermitteln.

Artikel kaufen

Sobald Ihre Produkte und Details dem Nutzer angezeigt werden, können Sie den Kaufvorgang mit der Payment Request API erstellen. Bei Verwendung in Verbindung mit der Digital Goods API ist nur ein Eingabeparameter erforderlich: methodData.

Mit Play Billing kann jeweils nur ein Artikel gekauft werden. Der Preis und die Details des Artikels sind dem Play-Server bereits bekannt, sodass der Parameter details nicht erforderlich ist. Eine detailliertere Erklärung finden Sie in der Erklärung.

Verwenden Sie das supportedMethods-Element des Parameters methodData in PaymentRequest, um Google Play Billing als Zahlungsmethode mit dem String "https://play.google.com/billing" zu identifizieren. Übergeben Sie dann im data-Element die Artikel-ID als sku.

const paymentMethodData = [
  {
    supportedMethods: 'https://play.google.com/billing',
    data: {
      sku: item.itemId,
    },
  },
];

Erstellen Sie dann die Zahlungsanfrage und rufen Sie show() auf, um den Zahlungsablauf zu starten:

const request = new PaymentRequest(paymentMethodData);
const paymentResponse = await request.show();

Dadurch wird die Play-Kauf-Benutzeroberfläche für den Nutzer angezeigt, in der er die Details zu dem Produkt sieht, das er kaufen möchte. Sie können die Transaktion abbrechen oder mit der Zahlung fortfahren. Wenn der Nutzer die Zahlung abbricht, wird das von show() zurückgegebene Promise mit einem Fehler abgelehnt. Wenn sie die Zahlung erfolgreich ausführen und den Kauf abschließen, wird das Promise mit einem PaymentResponse aufgelöst. In der details-Eigenschaft der Zahlungsantwort wird ein Kauf-Token zurückgegeben.

Um Betrug zu verhindern, ist es wichtig, den Kauf und das Kauftoken auf Ihrem Back-End-Server zu überprüfen. Es ist auch eine gute Idee, Nutzer und die zugehörigen Kauf-Tokens im Blick zu behalten. Informationen zum Implementieren der Überprüfung auf Ihrem Backend-Server

Rufen Sie nach der Bestätigung des Kaufs complete() in der Zahlungsantwort auf, um den Zahlungsablauf abzuschließen und die Abrechnungsoberfläche zu schließen. Sie können auch einen optionalen result-String übergeben, um den Status des Zahlungsvorgangs anzugeben. Es liegt am Browser, ob er dem Nutzer einen Hinweis auf dieses Ergebnis gibt. Chrome erstellt keine für Nutzer sichtbaren Hinweise. Es wird daher empfohlen, eigene Fehler- oder Erfolgsmeldungen in Ihrer PWA anzuzeigen.

/* Changes were recently made so that the PaymentResponse `details` property returns the purchase token as `purchaseToken` instead of `token`. Note that `token` will be deprecated at some point in the future. To ensure that your app won't be affected by this, make the change to `purchaseToken` in your client code and use the latest version of Bubblewrap (v1.13.5 and later) to update and generate a new app package to upload to the Play Console. */
const { purchaseToken } = paymentResponse.details;

let paymentComplete;
if (validatePurchaseOnBackend(purchaseToken)) {
  paymentComplete = await paymentResponse.complete('success');
  // Let user know their purchase transaction has successfully completed and been verified
} else {
  paymentComplete = await paymentResponse.complete('fail');
  // Let user know their purchase transaction failed to verify
}

Abo-Upgrades und ‑Downgrades

Dieser Kaufvorgang ist für In-App-Produkte und Abokäufe identisch. Für Abos bietet Google Play jedoch zusätzliche Kaufoptionen, die Sie implementieren können: Upgrade und Downgrade. Wenn Sie die data für die Zahlungsmethode erstellen, müssen Sie die folgenden Informationen übergeben, um einen Upgrade- oder Downgrade-Vorgang zu starten:

sku: Dies ist die Artikel-ID für das neue Abo, auf das das Abo aktualisiert oder herabgestuft werden soll.
oldSku: Dies ist die Artikel-ID für das aktuelle Abo des Nutzers.
purchaseToken: Das ist das Kauf-Token für das aktuelle Abo des Nutzers. Wie bereits erwähnt, ist es ratsam, die Kauf-Tokens in Ihrem Backend zu speichern. In diesem und anderen Fällen sollten Sie einem Nutzer auch seine aktuellen Käufe und Kauf-Tokens zuordnen.
prorationMode: So wird das neue Abo abgerechnet, wenn es das aktuelle Abo des Nutzers ersetzt.

Abrechnungsmodus	Beschreibung
immediateAndChargeProratedPrice	Das Abo wird sofort aktualisiert und der Abrechnungszeitraum bleibt unverändert. Die Preisdifferenz für den verbleibenden Zeitraum wird dem Nutzer dann in Rechnung gestellt.
immediateAndChargeFullPrice	Das Abo wird auf ein höheres oder niedrigeres Abo umgestellt und dem Nutzer wird der volle Preis für die neue Berechtigung sofort in Rechnung gestellt. Der Restwert des vorherigen Abos wird anteilig auf das neue Abo angerechnet. Dieser anteilige Abrechnungsmodus wurde vor Kurzem in der Google Play Billing Library 4.0 eingeführt. Sie ist jetzt über Bubblewrap ab Version 1.13.5 verfügbar.
immediateWithoutProration	VORÜBERGEHEND DEAKTIVIERT: Bei diesem Abrechnungsmodus besteht ein potenzieller Betrugsfall, bei dem Nutzer ein Upgrade für ihr Abo ohne zusätzliche Zahlung für einen Abrechnungszeitraum erhalten könnten. Wir haben diesen Modus vorübergehend deaktiviert, während wir an einer Lösung arbeiten.
immediateWithTimeProration	Das Abo wird sofort aktualisiert. Die verbleibende Zeit wird auf Grundlage der Preisdifferenz angepasst und dem neuen Abo gutgeschrieben, indem das nächste Abrechnungsdatum nach vorn verschoben wird. Das ist das Standardverhalten.
zurückgestellt	Das Abo wird nur beim Verlängern des Abos up- oder downgradet. Das ist besonders bei Downgrades nützlich.
unknownSubscriptionUpgradeDowngradePolicy	Keine Richtlinie festgelegt. Das wird nicht empfohlen.

Weitere Informationen zu den verschiedenen Abrechnungsarten finden Sie in der Referenzdokumentation zur Google Play Billing Library. Weitere Informationen zu Abo-Upgrades und ‑Downgrades und Empfehlungen für den Abrechnungsmodus finden Sie in der Android-Entwicklerdokumentation.

Die Verwendung dieser zusätzlichen Felder sieht in etwa so aus:

const paymentMethod = [
  {
    supportedMethods: 'https://play.google.com/billing',
    data: {
      sku: item.itemId,
      oldSku: oldPurchase.itemId,
      purchaseToken: oldPurchase.purchaseToken,
      prorationMode: 'immediateAndChargeProratedPrice',
    },
  },
];

Dabei ist item die ItemDetails des neuen Abos, auf das der Nutzer ein Upgrade oder Downgrade durchführen möchte, und oldPurchase die PurchaseDetails des aktuellen Abos des Nutzers.

Kauf bestätigen

Nachdem ein Nutzer einen Artikel gekauft hat, sollten Sie ihm die entsprechenden Berechtigungen gewähren (Zugriff auf den Artikel oder die Inhalte, die er gerade gekauft hat). Bestätigen Sie dann den Kauf. Wenn Sie einen Kauf bestätigen, wird Google Play darüber informiert, dass Sie den Kauf erhalten und ordnungsgemäß abgewickelt haben.

Hinweis:Wenn ein Kauf nicht innerhalb von 72 Stunden nach dem Kauf bestätigt wird, wird die Zahlung an den Nutzer erstattet und der Kauf wird widerrufen. Das Kauf-Token ist nicht mehr gültig. Wenn Sie also nach bestehenden Käufen suchen, wird der widerrufene Kauf nicht zurückgegeben. So wird verhindert, dass einem Nutzer im Falle eines Netzwerkfehlers, der dazu führt, dass er keine Berechtigung für seinen Artikel erhält, fälschlicherweise Gebühren berechnet werden.

Sie sollten Käufe über die Google Play Developer API von Ihrem Backend-Server aus bestätigen. Wir empfehlen, Berechtigungen zu erteilen und den Kauf dann gemeinsam auf Ihrem Backend-Server zu bestätigen.

Nachdem ein Nutzer einen Kauf clientseitig getätigt hat, senden Sie das Kauf-Token und die Artikel-ID in einer Anfrage an Ihren Backend-Server.
Rufen Sie in Ihrem Backend Folgendes auf, um Details zum Kauf zu erhalten und ihn zu bestätigen:
- purchases.products.get für In-App-Artikel.
- purchases.subscriptions.get für Abos.
Gewähren Sie die entsprechende Berechtigung in Ihrer Backend-Datenbank.
Bestätigen Sie dann den Kauf durch Aufrufen von:
- purchases.products.acknowledge für In‑App-Artikel.
- purchases.subscriptions.acknowledge für Abos.

Kauf nutzen

Wenn Sie einen Kauf bestätigen, wird Google Play mitgeteilt, dass der Nutzer das Artikel jetzt besitzt und ihn nicht noch einmal kaufen darf. Wenn es sich um einen Artikel handelt, den der Nutzer nur einmal kaufen muss und der ihm dann für immer gehört (z.B. ein Skin für eine Spielfigur), ist der Artikel nicht verbrauchbar.

Alternativ kann es sich um einen Artikel handeln, von dem ein Nutzer jeweils nur einen haben darf. Der Nutzer muss den Artikel dann erst verwenden, bevor er einen weiteren kaufen kann. Wenn der Nutzer das Element „verwendet“, müssen Sie die Methode consume() aufrufen, um Google Play mitzuteilen, dass der Nutzer das Element genutzt hat. Google Play macht den Artikel dann wieder für den Nutzer verfügbar.

Bei Artikeln, von denen ein Nutzer mehrere besitzen darf, muss es möglich sein, sie wiederholt zu kaufen, ohne dass sie zuerst verwendet werden müssen. Wir nennen diese Artikel „wiederholbare Artikel“. Auch diese Artikel müssen „verbraucht“ werden, bevor Google Play dem Nutzer erlaubt, sie noch einmal zu kaufen. Daher müssen Sie die Methode consume() aufrufen, um den Artikel als verbraucht zu kennzeichnen, auch wenn der Nutzer ihn noch nicht verwendet hat.

// After the user purchases the item, send the purchase token and item ID to your backend to grant the entitlement and acknowledge it right away

. . .
// When the user uses the item or if it is a repeatable item, consume it so it’s available for purchase again.
service.consume(purchaseToken);
}

Vorhandene Käufe prüfen

Im letzten Key User-Ablauf wird geprüft, ob bereits Käufe (In-App-Produkte, die noch nicht genutzt wurden, und laufende Abos) vorhanden sind, damit Nutzer wissen, welche Abos oder Artikel sie derzeit besitzen. Diese bestehenden Käufe stammen aus früheren Google Play-Käufen auf einem beliebigen Gerät, die in der App oder im Play Store getätigt wurden. Käufe, die außerhalb der App im Play Store getätigt werden, werden als Out-of-App-Käufe bezeichnet.

Wenn Sie vorhandene Käufe abrufen, sollten Sie auch den Bestätigungsstatus prüfen und alle Käufe bestätigen, die zuvor getätigt, aber nicht ordnungsgemäß bestätigt wurden. Es wird empfohlen, Käufe so schnell wie möglich zu bestätigen, damit die Berechtigungen des Nutzers aktuell sind und in der App richtig angezeigt werden.

Die Methode listPurchases() der Digital Goods API gibt eine Liste von PurchaseDetails zurück, die für jeden Kauf die itemId und purchaseToken enthält. Sie müssen die Google Play Developer API auf Ihrem Backend-Server verwenden, um den Status von Käufen zu prüfen und sie entsprechend zu bestätigen. …solltest du:

Rufen Sie die Digital Goods API-Methode listPurchases() clientseitig auf, um die Liste der Käufe des Nutzers abzurufen.
Übergeben Sie für jeden Kauf die purchaseToken und itemId an Ihr Backend.
Gewähren Sie gegebenenfalls die Berechtigung in Ihrer Backend-Datenbank.
Rufen Sie dann Folgendes auf:und prüfen Sie acknowledgementState.
- purchases.products.get für In-App-Artikel.
- purchases.subscriptions.get für Abos.
Wenn der Wert „0“ ist (noch nicht bestätigt), rufen Sie Folgendes auf:
- purchases.products.acknowledge für In-App-Artikel.
- purchases.subscriptions.acknowledge für Abos.

Weitere Informationen zum Bestätigen von Käufen auf Ihrem Backend-Server vor dem Gewähren von Berechtigungen

Bisherige Käufe

Während listPurchases Informationen zu den bestehenden Käufen des Nutzers zurückgibt, gibt die Methode listPurchaseHistory() (in Version 2.1 der API) den letzten Kauf des Nutzers für jedes Element zurück, unabhängig davon, ob der Kauf abgelaufen, storniert oder verbraucht ist. Die Methode listPurchaseHistory() gibt eine Liste von PurchaseDetails zurück, die die itemId und purchaseToken für jeden Kauf enthält. Diese müssen Sie mit der Google Play Developer API auf Ihrem Backend-Server verwenden, um weitere Informationen abzurufen.

Out-of-App-Käufe

Out-of-App-Käufe sind Käufe, die nicht über den normalen In-App-Kaufvorgang erfolgen. Diese Käufe erfolgen in der Regel im Play Store und nicht in Ihrer App. Es gibt zwei Hauptmöglichkeiten, wie Nutzer einen Kauf außerhalb der App tätigen können:

Gutscheincode einlösen: Im Play Store-Nutzermenü unter „Angebote & Benachrichtigungen“ -> „Gutscheincode einlösen“ oder unter „Zahlungen & Abos“ -> „Gutscheincode einlösen“.
Abo reaktivieren: Im Play Store-Nutzermenü unter Zahlungen & Abos > Abos. Hier können Nutzer alle ihre Abos für verschiedene Apps verwalten. Bei abgelaufenen oder gekündigten Abos haben Nutzer die Möglichkeit, das Abo neu abzuschließen.

Wenn Nutzer im Play Store ein neues Abo abschließen, werden ihre Käufe nicht automatisch bestätigt. Das kann dazu führen, dass sie eine Erstattung erhalten. Dieses Verhalten ist beabsichtigt, da Nutzer nur dann für ihr Abo belastet werden sollten, wenn sie die App öffnen, um sie zu verwenden. Der Nutzer sieht möglicherweise eine Meldung wie „Abo bestätigen“, die ihn daran erinnert, die App zu öffnen.

Nutzer werden aufgefordert, ihr Abo zu bestätigen, indem sie die App öffnen, um den Kauf zu bestätigen.

Als Entwickler müssen Sie die Bestätigung dieser Käufe implementieren, sobald der Nutzer die App startet. Wir empfehlen daher, nach vorhandenen Käufen zu suchen (normalerweise beim ersten Start der App) und alle Käufe zu bestätigen, die noch nicht bestätigt wurden.

Nutzern erlauben, Abos zu verwalten

Für eine gute Nutzererfahrung ist es wichtig, dass Nutzer ihre Abos in der App verwalten und kündigen können. Wir empfehlen, auf einer Einstellungsseite oder in einem Menü einen Deeplink zu erstellen, der den Nutzer zur Seite zur Aboverwaltung im Play Store für Ihre App weiterleitet. Ersetzen Sie die folgende URL durch die entsprechende „sub-product-id“ und „app-package-name“:

https://play.google.com/store/account/subscriptions?sku=sub-product-id&package=app-package-name

Nächste Schritte

Diese Nutzerabläufe und Code-Snippets sind eine grundlegende Implementierung, die zeigt, wie Sie die Digital Goods API und die Payment Request API in Ihrer PWA verwenden, um Play Billing zu implementieren. Sie sollten die APIs entsprechend dem Kontext und den Anwendungsfällen Ihrer App verwenden. Ein Beispiel für eine End-to-End-Implementierung finden Sie in unserem Open-Source-Beispiel.

Sehen Sie sich dann an, wie Sie wichtige Play Billing-Komponenten in Ihrem Backend-Server implementieren, um Ihre App zu schützen und immer mit den Berechtigungen Ihrer Nutzer auf dem neuesten Stand zu halten.

Play Billing in Ihre PWA implementieren Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.