Das Abrechnungssystem von Google Play ist ein Dienst, mit dem du digitale Produkte und Inhalte in deiner Android-App verkaufen kannst. Mit dem Release vom Mai 2022 haben wir die Definition von Aboprodukten geändert. Dies wirkt sich darauf aus, wie sie in der App verkauft und in deinem Back-End verwaltet werden. Wenn Sie Google Play Billing zum ersten Mal einbinden, lesen Sie Vorbereitung, wie Sie mit der Integration beginnen können.
Wenn Sie vor Mai 2022 Abos über Google Play Billing verkauft haben, ist es wichtig zu wissen, wie Sie neue Funktionen einführen können, während Sie Ihre bestehenden Abos behalten.
Zuerst einmal: Alle vorhandenen Abos, Apps und Back-End-Integrationen funktionieren wie vor dem Release im Mai 2022. Sie müssen nicht sofort Änderungen vornehmen. Sie können diese neuen Funktionen im Laufe der Zeit übernehmen. Jede Hauptversion der Google Play Billing Library wird nach der Veröffentlichung zwei Jahre lang unterstützt. Bestehende Integrationen mit der Google Play Developer API funktionieren weiterhin wie gewohnt.
Hier ist eine Übersicht der Aktualisierungen im Mai 2022:
- In der neuen Google Play Console kannst du Abos, Basis-Abos und Angebote erstellen und verwalten. Das gilt sowohl für neue als auch für migrierte Abos.
- Die Play Developer API enthält Updates zur Unterstützung neuer Funktionen der Google Play Console-UI in API-Form. Es gibt eine neue Version der Subscription Purchases API. Mit dieser API kannst du den Abostatus prüfen und Abokäufe verwalten.
- Mit der neuen Play Billing Library Version 5 kann deine App alle neuen Abofunktionen nutzen. Wenn Sie ein Upgrade auf Version 5 ausführen möchten, folgen Sie der Anleitung in der Migrationsanleitung.
Abokonfiguration
Abos über die Google Play Console verwalten
Ab Mai 2022 werden Sie in der Google Play Console einige Unterschiede feststellen.
Ein einzelnes Abo kann jetzt mehrere Basis-Abos und Angebote haben. Zuvor erstellte Abo-Artikelnummern werden jetzt in der Play Console als neue Abo-, Basis-Abo- und Angebotsobjekte angezeigt. Beschreibungen der neuen Objekte, einschließlich ihrer Funktionen und Konfiguration, findest du unter Kürzliche Änderungen an Abos in der Play Console. Alle deine bereits vorhandenen Aboprodukte werden in der Google Play Console in diesem neuen Format angezeigt. Jede SKU wird jetzt durch ein Aboobjekt repräsentiert, das ein einzelnes Basis-Abo und gegebenenfalls ein abwärtskompatibles Angebot enthält.
Da bei älteren Integrationen davon ausgegangen wird, dass jedes Abo ein einzelnes Angebot enthält, das durch ein SkuDetails-Objekt dargestellt wird, kann jedes Abo ein einzelnes abwärtskompatibles Basis-Abo oder Angebot haben.
Das abwärtskompatible Basis-Abo oder Angebot wird als Teil einer Artikelnummer für Apps zurückgegeben, die die inzwischen eingestellte Methode querySkuDetailsAsync() verwenden.
Weitere Informationen zum Konfigurieren und Verwalten von abwärtskompatiblen Angeboten findest du unter Abos verstehen. Sobald deine App nur queryProductDetailsAsync() verwendet und keine älteren Versionen deiner App mehr gekauft werden, musst du kein abwärtskompatibles Angebot mehr nutzen.
Abos über die Subscriptions Publishing API verwalten
Die Play Developer API bietet neue Funktionen für Abokäufe. Die inappproducts API für die Artikelnummerverwaltung funktioniert weiterhin wie zuvor und umfasst auch die Verwaltung von Produkten und Abos mit einmaligem Kauf. Du musst also keine sofortigen Änderungen vornehmen, um deine Integration aufrechtzuerhalten.
Wichtig: In der Google Play Console werden nur die neuen Aboentitäten verwendet. Sobald du damit begonnen hast, deine Abos in der Console zu bearbeiten, kann die inappproducts API nicht mehr für Abos verwendet werden.
Wenn du die Publishing API vor Mai 2022 verwendet hast, werden alle vorhandenen Abos jetzt in der Google Play Console als schreibgeschützt angezeigt, um Probleme zu vermeiden. Wenn Sie versuchen, Änderungen vorzunehmen, wird möglicherweise eine Warnung angezeigt, in der diese Einschränkung erläutert wird. Bevor Sie Abos in der Console weiter bearbeiten, sollten Sie Ihre Back-End-Integration so aktualisieren, dass die neuen Endpunkte für die Abo-Veröffentlichung verwendet werden. Mit den neuen Endpunkten monetization.subscriptions, monetization.subscriptions.baseplans und monetization.subscriptions.offers können Sie alle verfügbaren Basis-Abos und Angebote verwalten. In der folgenden Tabelle sehen Sie unter monetization.subscriptions, wie die verschiedenen Felder der Entität InAppProduct den neuen Objekten zugeordnet werden:
| In-App-Produkt | Abo |
|---|---|
packageName |
packageName |
sku |
productId |
status |
basePlans[0].state |
prices |
basePlans[0].regionalConfigs.price |
listings |
Einträge |
defaultPrice |
Keine Äquivalenz |
subscriptionPeriod |
basePlans[0].autoRenewingBasePlanType.billingPeriodDuration |
trialPeriod |
basePlans[0].offers[0].phases[0].regionalConfigs[0].free |
gracePeriod |
basePlans[0].autoRenewingBasePlanType.gracePeriodDuration |
subscriptionTaxesAndComplianceSettings |
TaxAndComplianceSettings |
Dieses erforderliche API-Update betrifft nur die Publishing API (SKU-Verwaltung).
Änderungen an der Play Billing Library
Zur Unterstützung einer schrittweisen Migration enthält die Play Billing Library alle Methoden und Objekte, die in früheren Versionen verfügbar waren.
SkuDetails-Objekte und -Funktionen wie querySkuDetailsAsync() sind weiterhin verfügbar. Du kannst also ein Upgrade durchführen, um neue Funktionen nutzen zu können, ohne sofort den vorhandenen Abocode aktualisieren zu müssen.
Sie können auch steuern, welche Angebote mit diesen Methoden verfügbar sind, indem Sie sie als abwärtskompatibel markieren.
Zusätzlich zu den alten Methoden enthält Play Billing Library 5 jetzt ein neues ProductDetails-Objekt und eine entsprechende queryProductDetailsAsync()-Methode zur Verarbeitung neuer Entitäten und Funktionen. Vorhandene In-App-Produkte (einmalige Käufe und Verbrauchsgüter) werden jetzt auch von ProductDetails unterstützt.
Bei einem Abo gibt ProductDetails.getSubscriptionOfferDetails() eine Liste aller Basis-Abos und Angebote zurück, die der Nutzer kaufen kann.
Das bedeutet, dass Sie unabhängig von der Abwärtskompatibilität auf alle Basis-Abos und Angebote zugreifen können, die für den Nutzer infrage kommen.
getSubscriptionOfferDetails() gibt null für Produkte zurück, die kein Abo sind. Für einmalige Käufe können Sie getOneTimePurchaseOfferDetails() verwenden.
Play Billing Library 5 enthält sowohl neue als auch alte Methoden zum Starten des Kaufvorgangs. Wenn das an BillingClient.launchBillingFlow() übergebene BillingFlowParams-Objekt mit einem SkuDetails-Objekt konfiguriert ist, extrahiert das System die Angebotsinformationen für den Verkauf aus dem abwärtskompatiblen Basis-Abo oder Angebot, das der SKU entspricht. Wenn das an BillingClient.launchBillingFlow() übergebene BillingFlowParams-Objekt mithilfe von ProductDetailsParams-Objekten konfiguriert ist, zu denen ProductDetails und ein String für das spezifische Angebotstoken für das gekaufte Angebot gehören, verwendet das System diese Informationen, um das vom Nutzer erworbene Produkt zu identifizieren.
queryPurchasesAsync() gibt alle Käufe des Nutzers zurück. Um den angeforderten Produkttyp anzugeben, kannst du wie in älteren Versionen einen BillingClient.SkuType-Wert oder ein QueryPurchasesParams-Objekt übergeben, das einen BillingClient.ProductType-Wert für die neuen Aboentitäten enthält.
Wir empfehlen dir, deine Apps möglichst bald auf Version 5 der Bibliothek zu aktualisieren, damit du die neuen Abofunktionen nutzen kannst.
Abostatus verwalten
In diesem Abschnitt werden die primären Änderungen an den Back-End-Komponenten einer Google Play-Abrechnungssystemsintegration beschrieben, die für die Migration zu Version 5 implementiert werden müssen.
Entwicklerbenachrichtigungen in Echtzeit
Das Objekt SubscriptionNotification enthält bald keine subscriptionId mehr. Wenn du dich auf dieses Feld verlässt, um das Aboprodukt zu identifizieren, solltest du diese Informationen über purchases.subscriptionv2:get aus dem Abostatus abrufen, sobald du die Benachrichtigung erhalten hast. Jedes SubscriptionPurchaseLineItem-Element in der lineItems-Sammlung, das im Rahmen des Kaufstatus zurückgegeben wird, enthält die entsprechende productId.
Subscriptions Purchases API: Abostatus abrufen
In früheren Versionen der Subscriptions Purchases API konntest du den Abostatus mit purchases.subscriptions:get abfragen.
Dieser Endpunkt bleibt unverändert und kann weiterhin für abwärtskompatible Abokäufe verwendet werden. Dieser Endpunkt unterstützt keine neuen Funktionen, die im Mai 2022 veröffentlicht wurden.
Verwende in der neuen Version der Subscriptions Purchases API purchases.subscriptionsv2:get, um den Status des Abokaufs abzurufen. Diese API ist mit migrierten Abos, neuen Abos (sowohl im Voraus als auch mit automatischer Verlängerung) und Käufen aller Art kompatibel. Mit diesem Endpunkt kannst du den Abostatus prüfen, wenn du Benachrichtigungen erhältst. Das zurückgegebene Objekt SubscriptionPurchaseV2 enthält neue Felder, enthält aber weiterhin Legacy-Daten, die erforderlich sind, um vorhandene Abos weiterhin zu unterstützen.
Felder für „AbokaufV2“ für Prepaid-Tarife
Es wurden neue Felder hinzugefügt, um Prepaid-Tarife zu unterstützen, die vom Nutzer erweitert werden, anstatt sich automatisch zu verlängern. Für Prepaid-Tarife gelten alle Felder wie für Abos mit automatischer Verlängerung, mit folgenden Ausnahmen:
- [New field] lineItems[0].prepaid_plan.allowExtendAfterTime: Gibt an, wann ein Nutzer eine weitere Aufladung zur Verlängerung seines Prepaid-Tarifs kaufen darf, da er nur eine nicht verbrauchte Aufladung auf einmal haben darf.
- [Neues Feld] SubscriptionState: Gibt den Status des Aboobjekts an.
Bei Prepaid-Tarifen ist dieser Wert immer entweder
ACTIVE,PENDINGoderCANCELED. - lineItems[0].expiryTime: Dieses Feld ist bei Prepaid-Tarifen immer vorhanden.
- paused_state_context: Dieses Feld ist nie vorhanden, da Prepaid-Tarife nicht pausiert werden können.
- lineItems[0].auto_renewing_plan: Nicht bei Prepaid-Tarifen vorhanden.
- canceled_state_context: Nicht für Prepaid-Tarife vorhanden, da dieses Feld nur für Nutzer gilt, die ein Abo aktiv kündigen.
- lineItems[0].productId: Dieses Feld ersetzt
subscriptionIdaus früheren Versionen.
SubscriptionPurchaseV2-Felder für wiederkehrende Abos
purchases.subscriptionv2 enthält neue Felder mit weiteren Details zu neuen Aboobjekten. Die folgende Tabelle zeigt, wie Felder vom Legacy-Aboendpunkt den entsprechenden Feldern in purchases.subscriptionv2 zugeordnet werden.
| Abokauf | AbonnementkaufV2 |
|---|---|
countryCode |
regionCode |
orderId |
latestOrderId |
| (kein entsprechendes Feld) | lineItems (Liste von SubscriptionPurchaseLineItem), das die mit dem Kauf erworbenen Produkte darstellt |
| (kein entsprechendes Feld) | lineItems.offerDetails.basePlanId |
| (kein entsprechendes Feld) | lineItems.offerDetails.offerId |
| (kein entsprechendes Feld) | lineItems.offerDetails.offerTags |
startTimeMillis |
startTime |
expiryTimeMillis |
lineItems.expiryTime (Jedes beim Kauf erworbene Abo hat eine eigene expiryTime) |
| (kein entsprechendes Feld) | subscriptionState (zeigt den
Status des Abos an) |
| (kein entsprechendes Feld) | pausedStateContext (nur vorhanden, wenn der Abostatus SUBSCRIPTION_STATE_PAUSED ist) |
autoResumeTimeMillis |
pausedStateContext.autoResumeTime |
| (kein entsprechendes Feld) | canceledStateContext (nur vorhanden, wenn der Abostatus SUBSCRIPTION_STATE_CANCELED ist) |
| (kein entsprechendes Feld) | testPurchase (nur bei Käufen lizenzierter Tester) |
autoRenewing |
lineItems.autoRenewingPlan.autoRenewEnabled |
priceCurrenceCode,
priceAmountMicros,
introductoryPriceInfo |
(kein äquivalentes Feld) Diese Informationen findest du in den basePlan/offer für jedes der erworbenen Abos. |
| developerPayload | (kein äquivalentes Feld) Entwicklernutzlast wurde eingestellt |
| paymentState | (kein entsprechendes Feld) Du kannst den Zahlungsstatus von subscriptionState ableiten:
|
cancelReason,
userCancellationTimeMillis,
cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken (keine Änderung) |
purchaseType |
Test: bis testPurchaseAngebot: (kein entsprechendes Feld), demnächst verfügbar |
priceChange |
lineItems.autoRenewingPlan.priceChangeDetails |
profileName,
emailAddress,
givenName,
familyName,
profileId |
subscribeWithGoogleInfo |
acknowledgementState |
acknowledgementState (no change) |
promotionType,
promotionCode |
(kein entsprechendes Feld); demnächst verfügbar |
externalAccountId,
obfuscatedExternalAccountId,
obfuscatedExteranlProfileId |
externalAccountIdentifiers |
Weitere Funktionen zur Aboverwaltung
Während purchases.subscriptions:get auf purchases.subscriptionsv2:get aktualisiert wurde, bleiben die übrigen Funktionen der Entwickleraboverwaltung am purchases.subscriptions-Endpunkt unverändert. Du kannst also weiterhin purchases.subscriptions:acknowledge, purchases.subscriptions:cancel, purchases.subscriptions:refund und wie zuvor .20/}{/2 verwenden.purchases.subscriptions:deferpurchases.subscriptions:revoke
Pricing API
Verwenden Sie den Endpunkt monetization.convertRegionPrices, um regionale Preise wie in der Play Console zu berechnen. Diese Methode akzeptiert einen Einzelpreis in jeder von Google Play unterstützten Währung und gibt umgerechnete Preise (einschließlich des Standardsteuersatzes, falls zutreffend) für alle Regionen zurück, in denen Google Play Käufe unterstützt.