Von Version 4 oder 5 zu Google Play Billing Library 6 migrieren

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 Abos
• Monetization.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.

Hinweis :Die inappproducts API für die Produktverwaltung gibt wie zuvor auch weiterhin Details zu Abo-Produkten zurück, sofern Sie diese nicht in der Play Console bearbeitbar gemacht haben. Sobald du mit der Bearbeitung deiner Abos in der Console begonnen hast, kann die inappproducts API nicht mehr für Abos verwendet werden.

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.

Hinweis :Wenn Sie von Play Billing Library 5 migrieren, können Sie mit dem Abschnitt Abokäufe eines Nutzers ändern fortfahren.

Abrechnungsclient initialisieren und Verbindung zu Google Play herstellen

Die ersten Schritte zum Starten von Käufen über eine Android-App bleiben gleich:

• Rechnungskunden initialisieren
• Verbindung zu Google Play herstellen

Zum Kauf verfügbare Produkte anzeigen

So erhalten Sie alle Angebote, die ein Nutzer kaufen kann:

• SkuDetailsParams durch QueryProductDetailsParams ersetzen
• Stellen Sie den BillingClient.querySkuDetailsAsync()-Aufruf auf BillingClient.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 von SkuDetails für BillingFlowParams.
• 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 an queryPurchasesAsync() ein QueryPurchasesParams-Objekt, das einen BillingClient.ProductType-Wert enthält.

Hinweis :Wenn du von Version 4 migrierst, solltest du beachten, dass die zuvor eingestellte Methode queryPurchases in Play Billing Library 6 entfernt wurde. Verwenden Sie stattdessen queryPurchasesAsync wie unten gezeigt.

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.