Das Abrechnungssystem von Google Play ist ein Dienst, über den Sie digitale Produkte und Inhalte in Ihrer Android-App verkaufen können. Mit der Version vom Mai 2022 haben wir die Definition von Aboprodukten geändert. Das wirkt sich darauf aus, wie sie in Ihrer App verkauft und in Ihrem Backend verwaltet werden. Wenn Sie Google Play Billing zum ersten Mal einbinden, lesen Sie den Hilfeartikel Vorbereitung.
Wenn Sie vor Mai 2022 Abos mit Google Play Billing verkauft haben, sollten Sie wissen, wie Sie neue Funktionen einführen und gleichzeitig Ihre bestehenden Abos beibehalten.
Zuerst einmal: Alle Ihre bestehenden Abos, Apps und Backend-Integrationen funktionieren genau wie vor der Veröffentlichung im Mai 2022. Sie müssen jetzt unmittelbar nichts tun – sondern können sich mit den neuen Funktionen auch nach und nach vertraut machen. Jede Hauptversion der Google Play Billing Library wird nach der Veröffentlichung zwei Jahre lang unterstützt. Vorhandene Integrationen mit der Google Play Developer API funktionieren weiterhin wie gewohnt.
Hier eine Übersicht über die Updates für Mai 2022:
- In der neuen Google Play Console können Sie 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-Benutzeroberfläche in API-Form. Insbesondere gibt es 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 Ihre App alle neuen Abofunktionen nutzen. Wenn Sie bereit sind, auf Version 5 umzustellen, folgen Sie der Anleitung im Migrationsleitfaden.
Abokonfiguration
Abos über die Google Play Console verwalten
Seit Mai 2022 gibt es einige Änderungen in der Google Play Console.
Ein einzelnes Abo kann jetzt mehrere Basis-Abos und Angebote haben. Bisher erstellte Abo-SKUs werden jetzt in der Play Console als diese neuen Abo-, Basis-Abo- und Angebotsobjekte angezeigt. Im Artikel Kürzliche Änderungen an Abos in der Play Console finden Sie Beschreibungen der neuen Objekte, einschließlich ihrer Funktionen und Konfiguration. Alle Ihre bestehenden Aboprodukte werden in der Google Play Console in diesem neuen Format angezeigt. Jede SKU wird jetzt durch ein Aboobjekt dargestellt, 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 umfasst, 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 jetzt eingestellte querySkuDetailsAsync()-Methode verwenden.
Weitere Informationen zum Konfigurieren und Verwalten von abwärtskompatiblen Angeboten finden Sie unter Abos. Wenn in Ihrer App nur noch queryProductDetailsAsync() verwendet wird und es keine älteren Versionen Ihrer App mehr gibt, über die Käufe getätigt werden, müssen Sie kein abwärtskompatibles Angebot mehr verwenden.
Abos über die Subscriptions Publishing API verwalten
Die Play Developer API enthält neue Funktionen für Abokäufe. Die API für die Artikelnummernverwaltung inappproducts funktioniert weiterhin wie gewohnt, einschließlich der Verarbeitung von Produkten mit Einmalkauf und Abos. Sie müssen also keine sofortigen Änderungen vornehmen, um Ihre Integration aufrechtzuerhalten.
In der Google Play Console werden jedoch nur die neuen Aboentitäten verwendet. Sobald Sie Ihre Abos in der Console bearbeiten, kann die inappproducts API nicht mehr für Abos verwendet werden.
Wenn Sie die Publishing API vor Mai 2022 verwendet haben, werden alle vorhandenen Abos jetzt in der Google Play Console nur noch als schreibgeschützt angezeigt, um Probleme zu vermeiden. Wenn Sie versuchen, Änderungen vorzunehmen, wird möglicherweise eine Warnung mit einer Erklärung zu dieser Einschränkung angezeigt. Bevor du Abos in der Console weiter bearbeitest, solltest du deine Backend-Integration so aktualisieren, dass sie die neuen Endpunkte für die Aboveröffentlichung verwendet. 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, wie die verschiedenen Felder der Entität InAppProduct den neuen Objekten unter monetization.subscriptions zugeordnet werden:
| InAppProduct | 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 gilt nur für 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 auf die neuen Funktionen umstellen, ohne den vorhandenen Abocode sofort aktualisieren zu müssen.
Sie können auch festlegen, welche Angebote über diese Methoden verfügbar sind, indem Sie sie als abwärtskompatibel kennzeichnen.
Neben den bisherigen Methoden enthält die Play Billing Library 5 jetzt ein neues ProductDetails-Objekt und eine entsprechende queryProductDetailsAsync()-Methode zum Umgang mit neuen Entitäten und Funktionen. Vorhandene In-App-Produkte (Einmalkaufprodukte und Verbrauchsmaterialien) werden jetzt auch von ProductDetails unterstützt.
Für ein Abo gibt ProductDetails.getSubscriptionOfferDetails() eine Liste aller Basistarife und Angebote zurück, die der Nutzer kaufen kann.
Das bedeutet, dass du unabhängig von der Abwärtskompatibilität auf alle Basis-Abos und Angebote zugreifen kannst, die für den Nutzer infrage kommen.
getSubscriptionOfferDetails() gibt null für Produkte zurück, die kein Abo sind. Für einmalige Käufe kannst du getOneTimePurchaseOfferDetails() verwenden.
Die 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 zum Verkauf aus dem abwärtskompatiblen Basis-Abo oder Angebot, das der SKU entspricht. Wenn das an BillingClient.launchBillingFlow() übergebene BillingFlowParams-Objekt mit ProductDetailsParams-Objekten konfiguriert ist, die ProductDetails und ein String enthalten, das das spezifische Angebotstoken für das gekaufte Angebot darstellt, verwendet das System diese Informationen, um das vom Nutzer gekaufte Produkt zu identifizieren.
queryPurchasesAsync() gibt alle Käufe zurück, die dem Nutzer gehören. Um den angeforderten Produkttyp anzugeben, kannst du wie in älteren Versionen einen BillingClient.SkuType-Wert oder ein QueryPurchasesParams-Objekt mit einem BillingClient.ProductType-Wert übergeben, der die neuen Aboentitäten darstellt.
Wir empfehlen, Ihre Apps bald auf Version 5 der Bibliothek zu aktualisieren, damit Sie diese neuen Abofunktionen nutzen können.
Abostatus verwalten
In diesem Abschnitt werden die wichtigsten Änderungen an den Backend-Komponenten einer Google Play-Abrechnungssystemintegration beschrieben, die für die Migration zu Version 5 implementiert werden müssen.
Entwicklerbenachrichtigungen in Echtzeit
Demnächst enthält das SubscriptionNotification-Objekt kein subscriptionId mehr. Wenn Sie dieses Feld zur Identifizierung des Aboprodukts verwenden, sollten Sie es aktualisieren, um diese Informationen aus dem Abostatus abzurufen. Verwenden Sie dazu purchases.subscriptionv2:get, sobald Sie die Benachrichtigung erhalten haben. Jedes SubscriptionPurchaseLineItem-Element in der Sammlung lineItems, 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 konnten Sie den Abostatus mit purchases.subscriptions:get abfragen.
Dieser Endpunkt bleibt unverändert und funktioniert weiterhin für abwärtskompatible Abokäufe. Dieser Endpunkt unterstützt keine neuen Funktionen, die im Mai 2022 veröffentlicht wurden.
In der neuen Version der Subscriptions Purchases API kannst du den Status des Abokaufs mit purchases.subscriptionsv2:get abrufen. Diese API ist mit migrierten Abos, neuen Abos (sowohl Prepaid- als auch automatisch verlängerbare) und Käufen aller Art kompatibel. Mit diesem Endpunkt können Sie den Abostatus prüfen, wenn Sie Benachrichtigungen erhalten. Das zurückgegebene Objekt SubscriptionPurchaseV2 enthält neue Felder, aber auch weiterhin alte Daten, die für die weitere Unterstützung bestehender Abos erforderlich sind.
SubscriptionPurchaseV2-Felder für Prepaid-Tarife
Es wurden neue Felder hinzugefügt, um Prepaid-Abos zu unterstützen, die vom Nutzer verlängert werden, anstatt automatisch verlängert zu werden. Alle Felder gelten für Prepaid-Tarife wie für Abos mit automatischer Verlängerung, mit folgenden Ausnahmen:
- [Neues Feld] „lineItems[0].prepaid_plan.allowExtendAfterTime“: Gibt an, wann ein Nutzer ein weiteres Guthaben kaufen kann, um seinen Prepaid-Tarif zu verlängern. Ein Nutzer darf jeweils nur ein nicht in Anspruch genommenes Guthaben haben.
- [Neues Feld] SubscriptionState: Gibt den Status des Aboobjekts an.
Bei Prepaid-Tarifen ist dieser Wert immer
ACTIVE,PENDINGoderCANCELED. - lineItems[0].expiryTime: Dieses Feld ist immer für Abos mit Vorauszahlung vorhanden.
- paused_state_context: Dieses Feld ist nie vorhanden, da Prepaid-Tarife nicht pausiert werden können.
- lineItems[0].auto_renewing_plan: Nicht vorhanden für Prepaid-Tarife.
- canceled_state_context: Nicht vorhanden bei Prepaid-Tarifen, 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. In der folgenden Tabelle wird gezeigt, wie Felder aus dem alten Aboendpunkt den entsprechenden Feldern in purchases.subscriptionv2 zugeordnet werden.
| SubscriptionPurchase | SubscriptionPurchaseV2 |
|---|---|
countryCode |
regionCode |
orderId |
latestOrderId |
| (kein entsprechendes Feld) | lineItems (Liste von SubscriptionPurchaseLineItem) mit den mit dem Kauf erworbenen Produkten |
| (kein entsprechendes Feld) | lineItems.offerDetails.basePlanId |
| (kein entsprechendes Feld) | lineItems.offerDetails.offerId |
| (kein entsprechendes Feld) | lineItems.offerDetails.offerTags |
startTimeMillis |
startTime |
expiryTimeMillis |
lineItems.expiryTime (jedes im Kauf erworbene Abo hat eine eigene expiryTime) |
| (kein entsprechendes Feld) | subscriptionState (
Status des Abos) |
| (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 durch Lizenztester vorhanden) |
autoRenewing |
lineItems.autoRenewingPlan.autoRenewEnabled |
priceCurrenceCode,
priceAmountMicros,
introductoryPriceInfo |
(kein entsprechendes Feld) Diese Informationen finden Sie in den Feldern basePlan/offer für jedes der gekauften Abos. |
| developerPayload | (kein entsprechendes Feld) Die Entwicklernutzlast wurde eingestellt |
| paymentState | (kein entsprechendes Feld) Sie können den Zahlungsstatus anhand von subscriptionState ableiten:
|
cancelReason,
userCancellationTimeMillis,
cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken (keine Änderung) |
purchaseType |
Test: über testPurchaseAngebot: signupPromotion |
priceChange |
lineItems.autoRenewingPlan.priceChangeDetails |
profileName,
emailAddress,
givenName,
familyName,
profileId |
subscribeWithGoogleInfo |
acknowledgementState |
acknowledgementState (no change) |
promotionType,
promotionCode |
signupPromotion |
externalAccountId,
obfuscatedExternalAccountId,
obfuscatedExteranlProfileId |
externalAccountIdentifiers |
Weitere Funktionen zur Aboverwaltung
purchases.subscriptions:get wurde auf purchases.subscriptionsv2:get umgestellt. Die übrigen Funktionen zur Verwaltung von Entwicklerabos bleiben im purchases.subscriptions-Endpunkt vorerst unverändert. Sie können also weiterhin purchases.subscriptions:acknowledge, purchases.subscriptions:cancel, purchases.subscriptions:defer, purchases.subscriptions:refund und purchases.subscriptions:revoke wie gewohnt verwenden.
Pricing API
Verwenden Sie den Endpunkt monetization.convertRegionPrices, um regionale Preise wie in der Play Console zu berechnen. Bei dieser Methode wird ein einzelner Preis in einer beliebigen von Google Play unterstützten Währung akzeptiert und es werden konvertierte Preise (einschließlich der Standardsteuersätze, sofern zutreffend) für alle Regionen zurückgegeben, in denen Google Play Käufe unterstützt.