In diesem Thema wird beschrieben, wie du von Google Play Billing Library 4 oder 5 zu Google Play Billing Library 6 migrierst und neue Abofunktionen verwendest.
Eine vollständige Liste der Änderungen in Version 6.0.0 finden Sie in den Versionshinweisen.
Übersicht
Google Play Billing Library 6 baut auf den neuen Abofunktionen von Version 5 auf und bietet einige weitere Verbesserungen. Mit diesen Funktionen haben Sie mehr Möglichkeiten, Abos zu verkaufen, und senken die Betriebskosten, da Sie keine ständig wachsende Anzahl von Artikelnummern erstellen und verwalten müssen.
Weitere Informationen zu den neuen Funktionen, die mit Play Billing Library 5 eingeführt wurden, findest du unter Kürzliche Änderungen an Abos in der Play Console.
Abwärtskompatibles Play Billing Library-Upgrade
Alle vorhandenen Aboprodukte wurden im Rahmen des Release von Play Billing Library 5 und der neuen Aboplattform vom Mai 2022 automatisch auf dieses neue Modell umgestellt. Du musst also keine Änderungen an der Produktkonfiguration für Abos vornehmen, um einen Katalog zu haben, der mit den neuen Versionen der Play Billing Library kompatibel ist. Weitere Informationen zur Umwandlung von Abo-Artikelnummern in abwärtskompatible Abos findest du im Abschnitt Mit älteren Abos arbeiten im Play Console-Hilfeartikel.
Ältere Versionen Ihrer App funktionieren weiterhin
Wenn du einen abwärtskompatiblen Abokatalog hast, sollten alle vorhandenen Versionen deiner App weiterhin wie für diese Produkte vorgesehen funktionieren. Einmalige Produktkäufe sollten auch in älteren Versionen weiterhin ohne Probleme funktionieren.
Für Versionen Ihrer App, für die eingestellte Methoden verwendet werden (z. B. querySkuDetailsAsync()
), können keine Basis-Abos oder Angebote verkauft werden, die nicht abwärtskompatibel sind. Informationen zu abwärtskompatiblen Angeboten findest du im entsprechenden Play Console-Hilfeartikel.
Upgrade auf Play Billing Library 5 oder 6
Play Billing Library 5 und 6 enthalten die eingestellten Methoden querySkuDetailsAsync
und BillingFlowParams.Builder.setSkuDetails
, für die SkuDetails
als Parameter für den Abrechnungsablauf verwendet wird. Das bedeutet, dass du schrittweise zu Play Billing Library 6 wechseln kannst, indem du verschiedene Phasen der Migration planst.
Als ersten Schritt zur Migration können Sie einfach die Bibliotheksversion aktualisieren, Ihren Katalog und Ihr Back-End unverändert lassen und Ihre Anwendung testen, während sie noch die eingestellten Methoden verwendet. Wenn Sie queryPurchases
, launchPriceChangeFlow
oder setVrPurchaseFlow
nicht verwenden, sollte es weiterhin wie vorgesehen funktionieren. Danach kannst du iterieren, um die neuen Abofunktionen, die im Mai 2022 veröffentlicht wurden, vollständig zu übernehmen.
Wenn du diese Funktionen bereits bei einer Migration zu Google Play Billing Library 5 verwendet hast, kannst du direkt mit den Abschnitten Google Play Billing Library aktualisieren und Abokä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 vollständigen Migrationsschritte lesen, um zu erfahren, wie Sie die neuen Funktionen implementieren.
Vollständige Migrationsschritte
Neue Abos im Backend-Produktkatalog erstellen
Mit der Play Console oder der Play Developer API kannst du jetzt ein einzelnes Abo mit mehreren Basis-Abos mit jeweils mehreren Angeboten konfigurieren. Für Aboangebote gelten flexible Preismodelle und Berechtigungsoptionen. Sie können Angebote mit einer Vielzahl von Prepaid-Tarifen und automatischen Verlängerungen für den gesamten Abolebenszyklus erstellen.
Wir empfehlen, neue Produkte gemäß der Entitätsstruktur auf der neuen Aboplattform für die Einbindung deiner Play Billing Library 6 zu erstellen, bevor du deine App migrierst. Du kannst doppelte Produkte in deinem alten Katalog mit denselben Berechtigungsvorteilen unter einem einzigen Abo konsolidieren und Basis-Abo- und Angebotskonfigurationen verwenden, um alle Optionen darzustellen, die du anbieten möchtest. Weitere Informationen zu dieser Empfehlung finden Sie im Play Console-Hilfeartikel unter Mit älteren Abos arbeiten.
Wir empfehlen, die umgewandelten Aboprodukte nach dem Release im Mai 2022 nicht mehr zu ändern. Sie sollten sie so belassen, wie sie mit den Versionen deiner App verkauft werden sollen, und zwar mit eingestellten Methoden (z. B. querySkuDetailsAsync()
), ohne Änderungen einzuführen, die sich auf diese älteren Builds auswirken könnten.
Durch die Konvertierung wurden die Aboprodukte, die sich vor Mai 2022 in deinem Katalog befanden, schreibgeschützt, um versehentliche Änderungen zu vermeiden, die zu Problemen mit deiner bestehenden Integration führen könnten. Sie können Änderungen an diesen Abos vornehmen. Das hätte jedoch Auswirkungen auf Ihre Frontend- und Backend-Integrationen:
Im Frontend dürfen in App-Versionen, die
querySkuDetailsAsync()
zum Abrufen von Aboproduktdetails verwenden, nur abwärtskompatible Basis-Abos und Angebote verkauft werden. Außerdem darf es nur eine abwärtskompatible Kombination aus Basis-Abo und Angebot geben. Wenn Sie den umgewandelten Abos also neue Abos oder Angebote hinzufügen, können die neuen zusätzlichen Basis-Abos oder Angebote nicht über diese älteren Versionen Ihrer App verkauft werden.Wenn Sie im Backend Ihre umgewandelten Abos in der Play Console-UI bearbeiten, können Sie sie nicht mit dem Endpunkt
inappproducts
verwalten, wenn Sie den Endpunkt zu diesem Zweck aufrufen. Du solltest auch zum neuen Endpunkt für Abokäufe (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 Verarbeitung abwärtskompatibler Basis-Abos und Käufe von Angeboten erforderlich sind. Weitere Informationen findest du im Abschnitt Status des Abokaufs verwalten.
Backend-Abokatalog mit der neuen API verwalten
Wenn du deinen Aboproduktkatalog automatisch mit der Google Play Developer API verwaltest, musst du die neuen Endpunkte für Aboproduktdefinitionen verwenden, um Abos, Basis-Abos und Angebote zu erstellen und zu verwalten. Weitere Informationen zu den Änderungen der Product Catalog API in diesem Release findest du im Leitfaden zu Abofunktionen von Mai 2022.
Wenn du ein automatisches Produktkatalogverwaltungsmodul für Google Play Billing-Abos migrieren möchtest, ersetze die inappproducts
API durch die neue Subscription Publishing API, um deinen Abokatalog zu verwalten und zu veröffentlichen. Es gibt drei neue Endpunkte:
Monetization.subscriptions
, um Aboprodukte zu verwalten.Monetization.basePlans
zum Verwalten von Basis-Abos für AbosMonetization.offers
, um Angebote für Basis-Abos zu verwalten.
Diese neuen Endpunkte bieten alle erforderlichen Funktionen, um alle neuen Funktionen in Ihrem Katalog zu nutzen: Basis-Abo- und Angebots-Tags, regionales Targeting, Prepaid-Tarife und mehr.
Du solltest weiterhin die inappproducts
API verwenden, um deinen In-App-Produktkatalog für Produkte mit einmaligem Kauf zu verwalten.
Für Versionen Ihrer App, für die eingestellte Methoden verwendet werden (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 hier.
Google Play Billing Library aktualisieren
Nachdem du deinen neuen Aboproduktkatalog erstellt hast, kannst du deine App zu Google Billing Library 5 migrieren. Ersetzen Sie die vorhandene Play Billing Library-Abhängigkeit durch die aktualisierte Version der Datei build.gradle
Ihrer App.
dependencies {
def billingVersion = "6.0.0"
implementation "com.android.billingclient:billing:$billingVersion"
}
Ihr Projekt sollte sofort erstellt werden, auch wenn Sie keine Methodenaufrufe geändert haben. Play Billing Library 6 ist abwärtskompatibel. Das Konzept einer Artikelnummer gilt als veraltet, ist aber weiterhin vorhanden, um die Portierung von Anwendungen zu einem einfacheren, inkrementellen Prozess zu machen.
Abrechnungsclient initialisieren und Verbindung zu Google Play herstellen
Die ersten Schritte zum Starten von Käufen über eine Android-App bleiben gleich:
Zum Kauf verfügbare Produkte anzeigen
So erhalten Sie alle Angebote, die ein Nutzer kaufen kann:
SkuDetailsParams
durchQueryProductDetailsParams
ersetzen- Stellen Sie den
BillingClient.querySkuDetailsAsync()
-Aufruf aufBillingClient.queryProductDetailsAsync()
um.
Die Abfrageergebnisse sind jetzt ProductDetails
statt SkuDetails
.
Jedes ProductDetails
-Element enthält Informationen über das Produkt (ID, Titel, Typ usw.). Bei Aboprodukten enthält ProductDetails
einen List<ProductDetails.SubscriptionOfferDetails>
. Das ist die Liste der Details zum Aboangebot. Bei Produkten mit einmaligem Kauf enthält ProductDetails
einen ProductDetails.OneTimePurchaseOfferDetails
. Diese können verwendet werden, um zu entscheiden, welche Angebote den Nutzern angezeigt werden.
Das folgende Beispiel zeigt, wie Ihre Anwendung 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 List<ProductDetails>
zurück.
Jedes ProductDetails
-Element enthält Informationen über das Produkt (ID, Titel, Typ usw.). Der Hauptunterschied besteht darin, dass Aboprodukte jetzt auch ein List<ProductDetails.SubscriptionOfferDetails>
mit allen für den Nutzer verfügbaren Angeboten enthalten.
Da vorherige Versionen der Play Billing Library die neuen Objekte (Abos, Basis-Abos, Angebote usw.) nicht unterstützen, übersetzt das neue System jede Abo-Artikelnummer in ein einzelnes abwärtskompatibles Basis-Abo und Angebot. Verfügbare Produkte, die einmalig gekauft werden, werden ebenfalls in ein ProductDetails
-Objekt portiert. Die Angebotsdetails eines Einmalkaufprodukts können mit der Methode getOneTimePurchaseOfferDetails()
aufgerufen werden.
In seltenen Fällen können ProductDetails
und queryProductDetailsAsync()
auf einigen Geräten nicht unterstützt werden. Das liegt in der Regel an veralteten Versionen der Google Play-Dienste. Damit dieses Szenario ordnungsgemäß unterstützt wird, rufen Sie vor dem Aufruf von queryProductDetailsAsync
isFeatureSupported()
für das PRODUCT_DETAILS
-Feature auf. Wenn die Antwort OK
lautet, unterstützt das Gerät die Funktion und Sie können mit dem Aufrufen 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 findest du im Leitfaden zu den Abofunktionen für Mai 2022.
Kaufvorgang starten
Der Start eines Kaufvorgangs für ein Angebot ähnelt dem Starten eines Kaufvorgangs für eine Artikelnummer. So starten Sie eine Kaufanfrage mit Version 6:
- Verwenden Sie
ProductDetailsParams
anstelle vonSkuDetails
fürBillingFlowParams
. - Die Angebotsdetails wie Angebots-ID, Basis-Abo-ID usw. können mit dem
SubscriptionOfferDetails
-Objekt abgerufen werden.
Wenn du ein Produkt mit dem vom Nutzer ausgewählten Angebot kaufen möchtest, rufe die offerToken
des ausgewählten Angebots ab und übergib es an das ProductDetailsParams
-Objekt.
Nachdem Sie ein BillingFlowParams
-Objekt erstellt haben, bleibt das Starten des Abrechnungsablaufs mit der BillingClient
gleich.
Das folgende Beispiel zeigt, wie Ihre Anwendung 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 Google Play Billing Library 6 ähnelt früheren Versionen.
So kannst du alle aktiven Käufe des Nutzers abrufen und neue Käufe abfragen:
- Übergeben Sie anstelle eines
BillingClient.SkuType
-Werts anqueryPurchasesAsync()
einQueryPurchasesParams
-Objekt, das einenBillingClient.ProductType
-Wert enthält.
Das folgende Beispiel zeigt, wie Ihre Anwendung 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 zur Verwaltung von Käufen außerhalb der App und ausstehenden Transaktionen haben sich nicht geändert.
Abokaufstatus mit der neuen API im Backend verwalten
Du solltest die Komponente zur Verwaltung des Abokaufstatus in deinem Back-End migrieren, damit du die Käufe der neuen Produkte verarbeiten kannst, die in den vorherigen Schritten erstellt wurden. Die aktuelle Komponente zur Verwaltung des Abokaufstatus sollte für die umgewandelten Aboprodukte, die Sie vor der Einführung im Mai 2022 definiert haben, wie gewohnt funktionieren. Sie sollte ausreichen, um Käufe abwärtskompatibler Angebote zu verwalten, unterstützt aber keine der neuen Funktionen.
Du musst die neue Subscription Purchases API für das Verwaltungsmodul deines Abokaufstatus implementieren. Diese prüft den Kaufstatus und verwaltet Play Billing-Aboberechtigungen in deinem Backend. Die alte Version der API gibt nicht alle Details zurück, die zur Verwaltung von Käufen auf der neuen Plattform erforderlich sind. Weitere Informationen zu den Änderungen gegenüber früheren Versionen findest du im Leitfaden zu den neuen Abofunktionen im Mai 2022.
Normalerweise musst du jedes Mal die Subscription Purchases API aufrufen, wenn du eine SubscriptionNotification
-Entwicklerbenachrichtigung in Echtzeit erhältst, um die neuesten Informationen zum Abostatus abzurufen. Du musst deine purchases.subscriptions.get
-Aufrufe durch die neue Version der Subscription Purchases API purchases.subscriptionsv2.get
ersetzen.
Die neue Ressource SubscriptionPurchaseV2
bietet genügend Informationen zur Verwaltung von Kaufberechtigungen für Abos im neuen Modell.
Dieser neue Endpunkt gibt den Status für alle Aboprodukte und Käufe zurück, unabhängig von der App-Version, über die sie verkauft wurden, und davon, wann das Produkt definiert wurde (vor oder nach dem Release im Mai 2022). Daher benötigst du nach der Migration nur diese Version deines Statusverwaltungsmoduls für Abokäufe.
Abokäufe von Nutzern ändern
In Play Billing Library 5 und niedriger wurde ProrationMode
verwendet, um Änderungen an den Abokäufen eines Nutzers vorzunehmen, z. B. Upgrades oder Downgrades. Dies wurde verworfen und in Version 6 durch ReplacementMode
ersetzt.
Abopreisänderungen verarbeiten
Die zuvor eingestellte launchPriceConfirmationFlow
API wurde in Play Billing Library 6 entfernt. Informationen zu Alternativen findest du im Leitfaden zu Preisänderungen.
Play Billing Library-Fehler beheben
In Play Billing Library 6 wurde ein neuer NETWORK_ERROR
-Code hinzugefügt, um auf Probleme mit der Netzwerkverbindung zwischen dem Gerät des Nutzers und dem Google Play-System hinzuweisen. Es wurden auch Änderungen an den Codes SERVICE_TIMEOUT
und SERVICE_UNAVAILABLE
vorgenommen. Weitere Informationen finden Sie unter Antwortcodes für BillingResult.
Ausstehende Transaktionen verarbeiten
Ab Version 6.0.0 erstellt die Play Billing Library keine Bestell-ID für ausstehende Käufe. Bei diesen Käufen wird die Bestell-ID eingefügt, nachdem der Kauf in den Bundesstaat PURCHASED
verschoben wurde. Achten Sie darauf, dass Ihre Integration erst dann eine Bestell-ID erwartet, wenn eine Transaktion vollständig abgeschlossen ist. Sie können das Kauftoken weiterhin für Ihre Einträge verwenden. Weitere Informationen zur Verarbeitung ausstehender Käufe findest du im Integrationsleitfaden für die Play Billing Library und im Leitfaden zur Verwaltung des Kauflebenszyklus.