In diesem Dokument wird beschrieben, wie Sie von der Google Play Billing Library 4 oder 5 zur Google Play Billing Library 6 migrieren und wie Sie neue Abo-Funktionen verwenden.
Eine vollständige Liste der Änderungen in Version 6.0.0 finden Sie in den Versionshinweisen.
Übersicht
Die Google Play Billing Library 6 baut auf den neuen Abo-Funktionen auf, die in Version 5 eingeführt wurden, und bietet einige weitere Verbesserungen. Mit diesen Funktionen können Sie Abos auf mehr Arten verkaufen und die Betriebskosten senken, da Sie nicht mehr eine immer größere Anzahl von SKUs erstellen und verwalten müssen.
Weitere Informationen zu den neuen Funktionen, die mit der Play Billing Library 5 eingeführt wurden, findest du unter Kürzliche Änderungen an Abos in der Play Console.
Abwärtskompatibles Upgrade der Play Billing Library
Alle bestehenden Aboprodukte wurden im Rahmen der Veröffentlichung der Play Billing Library 5 und der neuen Aboplattform im Mai 2022 automatisch auf dieses neue Modell umgestellt. Das bedeutet, dass du keine Änderungen an der Konfiguration von Aboprodukten vornehmen musst, um einen Katalog zu haben, der mit den neuen Versionen der Play Billing Library kompatibel ist. Weitere Informationen dazu, wie Abo-SKUs in abwärtskompatible Abos umgewandelt wurden, findest du im Play Console-Hilfeartikel im Abschnitt Mit älteren Abos arbeiten.
Frühere Versionen Ihrer App funktionieren weiterhin
Wenn Sie einen abwärtskompatiblen Abokatalog haben, sollten alle vorhandenen Versionen Ihrer App für diese Produkte weiterhin wie vorgesehen funktionieren. Einmalkäufe von Produkten sollten auch in früheren Versionen weiterhin problemlos funktionieren.
In Versionen Ihrer App, die verworfene Methoden verwenden (z. B. querySkuDetailsAsync()), können keine Basis-Abos oder Angebote verkauft werden, die nicht abwärtskompatibel sind. Weitere Informationen zu abwärtskompatiblen Angeboten finden Sie im entsprechenden Hilfeartikel in der Play Console.
Upgrade auf Play Billing Library 5 oder 6
Die Play Billing Library 5 und 6 enthalten die verworfenen Methoden querySkuDetailsAsync und BillingFlowParams.Builder.setSkuDetails, die SkuDetails als Parameter für den Abrechnungsvorgang verwenden. Das bedeutet, dass ihr schrittweise zur Play Billing Library 6 migrieren könnt, indem ihr verschiedene Migrationsphasen plant.
Als ersten Schritt der Migration können Sie einfach die Bibliotheksversion aktualisieren, Ihren Katalog und Ihr Backend unverändert lassen und Ihre App testen, während sie noch die verworfenen Methoden verwendet. Wenn Sie queryPurchases, launchPriceChangeFlow oder setVrPurchaseFlow nicht verwenden, sollte es trotzdem wie vorgesehen funktionieren. Anschließend können Sie die neuen Abo-Funktionen, die im Mai 2022 veröffentlicht wurden, vollständig übernehmen.
Wenn du diese Funktionen bereits im Rahmen einer Migration zur Google Play Billing Library 5 eingeführt hast, kannst du direkt mit den Abschnitten Google Play Billing Library aktualisieren und Abo-Käufe eines Nutzers ändern fortfahren. Wenn Sie mit einer früheren Version beginnen oder die neuen Funktionen noch nicht vollständig übernommen haben, können Sie die folgenden vollständigen Migrationsschritte lesen, um zu erfahren, wie Sie sie übernehmen.
Schritte für die vollständige Migration
Neue Abos im Backend-Produktkatalog erstellen
Über die Play Developer Console oder die Play Developer API kannst du jetzt ein einzelnes Abo mit mehreren Basis-Abos konfigurieren, wobei jedes Basis-Abo wiederum verschiedene Angebote umfassen kann. Für Aboangebote lassen sich verschiedene Preismodelle und Voraussetzungen festlegen. Sie können Angebote im gesamten Abolebenszyklus erstellen. Dafür stehen Ihnen viele verschiedene Optionen zur automatischen Verlängerung sowie für Prepaid-Tarife zur Verfügung.
Wir empfehlen, vor der Migration Ihrer App neue Produkte gemäß der Entitätsstruktur in der neuen Aboplattform für Ihre Integration der Play Billing Library 6 zu erstellen. Sie können doppelt vorhandene Produkte in Ihrem alten Katalog, die dieselben Berechtigungen bieten, in einem einzigen Abo zusammenfassen und die Konfigurationen für Basis-Abos und Angebote verwenden, um alle Optionen darzustellen, die Sie anbieten möchten. Weitere Informationen zu dieser Empfehlung finden Sie im Play Console-Hilfeartikel im Abschnitt Mit älteren Abos arbeiten.
Lassen Sie konvertierte Aboprodukte nach dem Release im Mai 2022 unverändert, damit App-Versionen, die verworfene Methoden (z. B. querySkuDetailsAsync()) verwenden, diese weiterhin verkaufen können, ohne dass diese Builds beeinträchtigt werden.
Durch den Umwandlungsprozess wurden die Aboprodukte, die sich vor Mai 2022 in Ihrem Katalog befanden, schreibgeschützt, um versehentliche Änderungen zu vermeiden, die zu Problemen mit Ihrer bestehenden Integration führen könnten. Änderungen an diesen Abos sind möglich, können sich aber auf Ihre Frontend- und Backend-Integrationen auswirken:
Im Frontend können App-Versionen, die
querySkuDetailsAsync()verwenden, um Details zu Aboprodukten abzurufen, nur abwärtskompatible Basis-Abos und Angebote verkaufen. Außerdem kann es nur eine Kombination aus abwärtskompatiblem Basis-Abo und Angebot geben. Wenn Sie den konvertierten Abos also neue Abos oder Angebote hinzufügen, können die neuen zusätzlichen Basis-Abos oder Angebote nicht in diesen früheren Versionen Ihrer App verkauft werden.Wenn Sie Ihre konvertierten Abos in der Play Console-Benutzeroberfläche bearbeiten, können Sie sie nicht mehr mit dem
inappproducts-Endpunkt verwalten, falls Sie den Endpunkt zu diesem Zweck aufgerufen haben. Außerdem solltet ihr zum neuen Endpunkt für den Kaufstatus von Abos (purchases.subscriptionsv2.get) migrieren, um Käufe für diese Abos zu verwalten, da der alte Endpunkt für den Kaufstatus (purchases.subscriptions.get) nur die Daten zurückgibt, die für die Abwicklung von Käufen von abwärtskompatiblen Basis-Abos und Angeboten erforderlich sind. Weitere Informationen finden Sie im Abschnitt Status von Abokäufen verwalten.
Backend-Abokatalog mit der neuen API verwalten
Wenn Sie Ihren Aboproduktkatalog automatisch mit der Google Play Developer API verwalten, müssen Sie die neuen Endpunkte für die Aboproduktdefinition verwenden, um Abos, Basis-Abos und Angebote zu erstellen und zu verwalten. Weitere Informationen zu den Änderungen an der Produktkatalog API in diesem Release finden Sie im Leitfaden zu den Abo-Funktionen vom Mai 2022.
Wenn Sie ein automatisches Modul zur Verwaltung des Produktkatalogs für Google Play Billing-Abos migrieren möchten, ersetzen Sie die inappproducts API durch die neue Subscription Publishing API, um Ihren Abokatalog zu verwalten und zu veröffentlichen.
Es gibt drei neue Endpunkte:
Monetization.subscriptions, um Aboprodukte zu verwalten.Monetization.basePlans, um Basis-Abos für Abos zu verwalten.Monetization.offers, um Angebote für Basis-Abos zu verwalten.
Diese neuen Endpunkte bieten alle erforderlichen Funktionen, um alle neuen Möglichkeiten in Ihrem Katalog zu nutzen: Tags für Basis-Abos und Angebote, regionales Targeting, Prepaid-Tarife und mehr.
Sie sollten weiterhin die inappproducts API verwenden, um Ihren In-App-Produktkatalog für Einmalkaufprodukte zu verwalten.
In Versionen Ihrer App, die verworfene Methoden verwenden (z. B. querySkuDetailsAsync()), können keine Basis-Abos oder Angebote verkauft werden, die nicht abwärtskompatibel sind. Informationen zu abwärtskompatiblen Angeboten finden Sie im Play Console-Hilfeartikel.
Google Play Billing Library aktualisieren
Nachdem du deinen neuen Produktkatalog mit Aboprodukten erstellt hast, kannst du deine App zur Google Billing Library 5 migrieren. Ersetze die vorhandene Play Billing Library-Abhängigkeit in der build.gradle-Datei deiner App durch die aktualisierte Version.
dependencies {
def billingVersion = "6.0.0"
implementation "com.android.billingclient:billing:$billingVersion"
}
Ihr Projekt sollte sofort erstellt werden, auch wenn Sie keine Aufrufe von Methoden geändert haben. Die Play Billing Library 6 ist abwärtskompatibel. Das Konzept einer SKU gilt als veraltet, ist aber weiterhin vorhanden, um die Portierung von Apps zu vereinfachen und schrittweise zu gestalten.
Billing Client initialisieren und eine Verbindung zu Google Play herstellen
Die ersten Schritte zum Starten von Käufen über eine Android-App bleiben gleich:
Produkte anzeigen, die gekauft werden können
So rufen Sie alle Angebote ab, die ein Nutzer kaufen kann:
SkuDetailsParamsdurchQueryProductDetailsParamsersetzen- Stellen Sie den Aufruf
BillingClient.querySkuDetailsAsync()aufBillingClient.queryProductDetailsAsync()um.
Beachten Sie, dass die Abfrageergebnisse jetzt ProductDetails statt SkuDetails sind.
Jedes ProductDetails-Element enthält Informationen zum Produkt (ID, Titel, Typ usw.). Bei Aboprodukten enthält ProductDetails ein List<ProductDetails.SubscriptionOfferDetails>, d. h. die Liste der Details zum Aboangebot. Bei Einmalkaufprodukten enthält ProductDetails ein ProductDetails.OneTimePurchaseOfferDetails. Anhand dieser Informationen kann entschieden werden, welche Angebote den Nutzern angezeigt werden sollen.
Das folgende Beispiel zeigt, wie Ihre App vor und nach diesen Änderungen aussehen könnte:
Vorher
Kotlin
val skuList = ArrayList<String>()
skuList.add("up_basic_sub")
val params = SkuDetailsParams.newBuilder()
params.setSkusList(skuList).setType(BillingClient.SkuType.SUBS).build()
billingClient.querySkuDetailsAsync(params) {
billingResult,
skuDetailsList ->
// Process the result
}
Java
List<String> skuList = new ArrayList<>();
skuList.add("up_basic_sub");
SkuDetailsParams.Builder params = SkuDetailsParams.newBuilder();
params.setSkusList(skuList).setType(SkuType.SUBS).build();
billingClient.querySkuDetailsAsync(params,
new SkuDetailsResponseListener() {
@Override
public void onSkuDetailsResponse(BillingResult billingResult,
List<SkuDetails> skuDetailsList) {
// Process the result.
}
}
);
Nachher
Kotlin
val productList =
listOf(
QueryProductDetailsParams.Product.newBuilder()
.setProductId("up_basic_sub")
.setProductType(BillingClient.ProductType.SUBS)
.build()
)
val params = QueryProductDetailsParams.newBuilder().setProductList(productList).build()
billingClient.queryProductDetailsAsync(params) {
billingResult,
productDetailsList ->
// Process the result
}
Java
ImmutableList<Product> productList = ImmutableList.of(Product.newBuilder()
.setProductId("up_basic_sub")
.setProductType(ProductType.SUBS)
.build());
QueryProductDetailsParams params = QueryProductDetailsParams.newBuilder()
.setProductList(productList)
.build();
billingClient.queryProductDetailsAsync(
params,
new ProductDetailsResponseListener() {
public void onProductDetailsResponse(BillingResult billingResult, List<ProductDetails> productDetailsList) {
// Process the result
}
}
);
Der Callback für queryProductDetailsAsync gibt ein List<ProductDetails> zurück.
Jedes ProductDetails-Element enthält Informationen zum Produkt (ID, Titel, Typ usw.). Der Hauptunterschied besteht darin, dass Aboprodukte jetzt auch ein List<ProductDetails.SubscriptionOfferDetails> enthalten, das alle für den Nutzer verfügbaren Angebote enthält.
Da frühere Versionen der Play Billing Library die neuen Objekte (Abos, Basis-Abos, Angebote usw.) nicht unterstützen, übersetzt das neue System jede Abo-SKU in ein einzelnes abwärtskompatibles Basis-Abo und Angebot. Verfügbare Einmalkaufprodukte werden ebenfalls in ein ProductDetails-Objekt übertragen. Auf die Angebotsdetails eines Einmalkaufprodukts kann mit der Methode getOneTimePurchaseOfferDetails() zugegriffen werden.
In seltenen Fällen unterstützen einige Geräte ProductDetails und queryProductDetailsAsync() nicht, was in der Regel auf veraltete Versionen der Google Play-Dienste zurückzuführen ist. Damit dieses Szenario ordnungsgemäß unterstützt wird, rufen Sie isFeatureSupported() für das Feature PRODUCT_DETAILS auf, bevor Sie queryProductDetailsAsync aufrufen. Wenn die Antwort OK lautet, unterstützt das Gerät die Funktion und Sie können mit dem Aufruf von queryProductDetailsAsync() fortfahren. Wenn die Antwort FEATURE_NOT_SUPPORTED lautet, können Sie stattdessen die Liste der verfügbaren abwärtskompatiblen Produkte mit querySkuDetailsAsync() anfordern. Weitere Informationen zur Verwendung der Abwärtskompatibilitätsfunktionen finden Sie im Leitfaden zu den Abo-Funktionen vom Mai 2022.
Kaufvorgang für das Angebot starten
Das Starten eines Kaufvorgangs für ein Angebot ist dem Starten eines Vorgangs für eine SKU sehr ähnlich. So starten Sie eine Kaufanfrage mit Version 6:
- Verwenden Sie für
BillingFlowParamsnichtSkuDetails, sondernProductDetailsParams. - Die Angebotsdetails wie Angebots-ID, Basis-Abo-ID und mehr können über das Objekt
SubscriptionOfferDetailsabgerufen werden.
Wenn Sie ein Produkt mit dem vom Nutzer ausgewählten Angebot kaufen möchten, rufen Sie die offerToken des ausgewählten Angebots ab und übergeben Sie sie an das ProductDetailsParams-Objekt.
Nachdem du ein BillingFlowParams-Objekt erstellt hast, bleibt das Starten des Abrechnungsvorgangs mit der BillingClient gleich.
Das folgende Beispiel zeigt, wie Ihre App vor und nach diesen Änderungen aussehen könnte:
Vorher
Kotlin
// An activity reference from which the billing flow will be launched.
val activity : Activity = ...
// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync().
val billingFlowParams = BillingFlowParams.newBuilder()
.setSkuDetails(skuDetails)
.build()
val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)
Java
// An activity reference from which the billing flow will be launched.
Activity activity = ...;
// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync().
BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
.setSkuDetails(skuDetails)
.build();
BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)
Nachher
Kotlin
// An activity reference from which the billing flow will be launched.
val activity : Activity = ...;
val productDetailsParamsList = listOf(
BillingFlowParams.ProductDetailsParams.newBuilder()
// retrieve a value for "productDetails" by calling queryProductDetailsAsync()
.setProductDetails(productDetails)
// For One-time product, "setOfferToken" method shouldn't be called.
// For subscriptions, to get the offer token corresponding to the selected
// offer call productDetails.subscriptionOfferDetails?.get(selectedOfferIndex)?.offerToken
.setOfferToken(selectedOfferToken)
.build()
)
val billingFlowParams = BillingFlowParams.newBuilder()
.setProductDetailsParamsList(productDetailsParamsList)
.build()
// Launch the billing flow
val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)
Java
// An activity reference from which the billing flow will be launched.
Activity activity = ...;
ImmutableList<ProductDetailsParams> productDetailsParamsList =
ImmutableList.of(
ProductDetailsParams.newBuilder()
// retrieve a value for "productDetails" by calling queryProductDetailsAsync()
.setProductDetails(productDetails)
// For one-time products, "setOfferToken" method shouldn't be called.
// For subscriptions, to get the offer token corresponding to the selected
// offer call productDetails.getSubscriptionOfferDetails().get(selectedOfferIndex).getOfferToken()
.setOfferToken(selectedOfferToken)
.build()
);
BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
.setProductDetailsParamsList(productDetailsParamsList)
.build();
// Launch the billing flow
BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);
Käufe verarbeiten
Die Verarbeitung von Käufen mit der Google Play Billing Library 6 ähnelt der in früheren Versionen.
So rufst du alle aktiven Käufe des Nutzers ab und fragst nach neuen Käufen:
- Anstatt einen
BillingClient.SkuType-Wert anqueryPurchasesAsync()zu übergeben, übergeben Sie einQueryPurchasesParams-Objekt, das einenBillingClient.ProductType-Wert enthält.
Das folgende Beispiel zeigt, wie Ihre App vor und nach diesen Änderungen aussehen könnte:
Vorher
Kotlin
billingClient.queryPurchasesAsync(BillingClient.SkuType.SUBS) {
billingResult,
purchaseList -> {
// Process the result
}
}
Java
billingClient.queryPurchasesAsync(
BillingClient.SkuType.SUBS,
new PurchasesResponseListener() {
public void onQueryPurchasesResponse(
BillingResult billingResult,
List<Purchase> purchases) {
// process the result
}
}
);
Nachher
Kotlin
billingClient.queryPurchasesAsync(
QueryPurchasesParams.newBuilder()
.setProductType(BillingClient.ProductType.SUBS)
.build()
) { billingResult, purchaseList ->
// Process the result
}
Java
billingClient.queryPurchasesAsync(
QueryPurchasesParams.newBuilder().setProductType(ProductType.SUBS).build(),
new PurchasesResponseListener() {
public void onQueryPurchasesResponse(
BillingResult billingResult,
List<Purchase> purchases) {
// Process the result
}
}
);
Die Schritte zum Verwalten von Out-of-App-Käufen und ausstehenden Transaktionen haben sich nicht geändert.
Abokaufstatus mit der neuen API im Backend verwalten
Du solltest die Komponente zur Verwaltung des Kaufstatus von Abos in deinem Backend migrieren, damit du Käufe der neuen Produkte verarbeiten kannst, die in den vorherigen Schritten erstellt wurden. Die aktuelle Komponente zur Verwaltung des Kaufstatus von Abos sollte für die konvertierten Aboprodukte, die du vor der Einführung im Mai 2022 definiert hast, wie gewohnt funktionieren. Sie sollte ausreichen, um Käufe von abwärtskompatiblen Angeboten zu verwalten, unterstützt aber keine der neuen Funktionen.
Du musst die neue Subscription Purchases API für dein Modul zur Verwaltung des Kaufstatus von Abos implementieren. Dieses Modul prüft den Kaufstatus und verwaltet die Berechtigungen für Google Play Billing-Abos in deinem Backend. Die alte Version der API gibt nicht alle erforderlichen Details zurück, um Käufe auf der neuen Plattform zu verwalten. Details zu den Änderungen gegenüber früheren Versionen finden Sie im Leitfaden zu den neuen Abo-Funktionen vom Mai 2022.
Beachten Sie bei der Migration des Moduls zur Verwaltung des Kaufstatus Folgendes:
- Rufe die Subscription Purchases API jedes Mal auf, wenn du eine
SubscriptionNotification-Entwicklerbenachrichtigung in Echtzeit erhältst, um die neuesten Informationen zum Abostatus abzurufen. - Ersetzen Sie Ihre Aufrufe von
purchases.subscriptions.getdurch die neue Version der Subscription Purchases API,purchases.subscriptionsv2.get. - Verwende die neue Ressource
SubscriptionPurchaseV2, die genügend Informationen bietet, um die Kaufberechtigung für Abos im neuen Modell zu verwalten.
Dieser neue Endpunkt gibt den Status für alle deine Aboprodukte und alle deine Käufe zurück, unabhängig von der Version der App, über die sie verkauft wurden, und davon, wann das Produkt definiert wurde (vor oder nach dem Release im Mai 2022). Nach der Migration benötigst du also nur diese Version deines Moduls zur Verwaltung des Kaufstatus von Abos.
Abo-Käufe eines Nutzers ändern
In der Play Billing Library 5 und früheren Versionen wurde ProrationMode verwendet, um Änderungen an den Abokäufen eines Nutzers vorzunehmen, z. B. Upgrades oder Downgrades. Diese wurde verworfen und in Version 6 durch ReplacementMode ersetzt.
Änderungen von Abopreisen verwalten
Die zuvor verworfene launchPriceConfirmationFlow API wurde in der Play Billing Library 6 entfernt. Alternativen finden Sie im Leitfaden zu Preisänderungen.
Fehler in der Play Billing Library beheben
In der Play Billing Library 6 wurde ein neuer NETWORK_ERROR-Code hinzugefügt, der auf Probleme mit der Netzwerkverbindung zwischen dem Gerät des Nutzers und dem Google Play-System hinweist. Außerdem wurden die Codes SERVICE_TIMEOUT und SERVICE_UNAVAILABLE geändert. Weitere Informationen findest du unter BillingResult-Antwortcodes verarbeiten.
Ausstehende Transaktionen verarbeiten
Ab Version 6.0.0 wird in der Play Billing Library keine Bestell-ID für ausstehende Käufe erstellt. Bei diesen Käufen wird die Bestell-ID ausgefüllt, nachdem der Kauf in den Status PURCHASED verschoben wurde. Achte darauf, dass deine Integration erst nach Abschluss einer Transaktion eine Bestell-ID erwartet. Sie können das Kaufftoken weiterhin für Ihre Unterlagen verwenden. Weitere Informationen zum Umgang mit ausstehenden Käufen findest du im Integrationsleitfaden für die Play Billing Library und im Leitfaden zur Verwaltung des Kauflebenszyklus.