Das Abrechnungssystem von Google Play ist ein Dienst, über den Sie digitale Produkte und Inhalte in Ihrer Android-App verkaufen können. Mit dem Release im Mai 2022 haben wir die Definition von Aboprodukten geändert. Dies wirkt sich darauf aus, wie sie in der App verkauft und im Backend verwaltet werden. Wenn du Google Play Billing zum ersten Mal integrierst, kannst du mit dem Lesen des Artikels Vorbereitung beginnen.
Wenn du vor Mai 2022 Abos mit Google Play Billing verkauft hast, ist es wichtig zu wissen, wie du neue Funktionen übernehmen und gleichzeitig deine bestehenden Abos beibehalten kannst.
Zuerst einmal funktionieren alle bereits bestehenden Abos, Apps und Backend-Integrationen noch genau wie vor dem Release im Mai 2022. Sie müssen jetzt unmittelbar nichts tun – sondern können sich mit den neuen Funktionen auch nach und nach vertraut machen. Jeder Hauptrelease der Google Play Billing Library wird zwei Jahre lang nach der Veröffentlichung unterstützt. Bestehende Integrationen mit der Google Play Developer API funktionieren weiterhin wie gewohnt.
Hier eine Übersicht der Updates für Mai 2022:
- In der neuen Google Play Console kannst du Abos, Basis-Abos und Angebote erstellen und verwalten. Dies gilt sowohl für neue als auch für migrierte Abos.
- Die Play Developer API enthält Updates, die neue Funktionen der Google Play Console-Benutzeroberfläche in API-Form unterstützen. Es gibt eine neue Version der Subscription Purchases API. Mit dieser API können Sie den Abostatus prüfen und Abokäufe verwalten.
- Mit der neuen Play Billing Library Version 5 kann deine App von allen neuen Abofunktionen profitieren. Wenn Sie bereit für ein Upgrade auf Version 5 sind, folgen Sie der Anleitung in der Migrationsanleitung.
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. Zuvor erstellte Abo-SKUs werden jetzt in der Play Console als diese neuen Abo-, Basis-Abo- und Angebotsobjekte angezeigt. Falls noch nicht geschehen, lesen Sie den Artikel Kürzliche Änderungen an Abos in der Play Console. Dort 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 Abo-Objekt dargestellt, das ein einzelnes Basis-Abo und gegebenenfalls ein abwärtskompatibles Angebot enthält.
Da bei älteren Integrationen davon ausgegangen wurde, 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 SKU für Apps zurückgegeben, die die jetzt eingestellte Methode querySkuDetailsAsync() verwenden. Weitere Informationen zum Konfigurieren und Verwalten von abwärtskompatiblen Angeboten finden Sie unter Abos. Wenn Ihre App nur noch queryProductDetailsAsync() verwendet und keine früheren Versionen Ihrer App mehr Käufe tätigen, müssen Sie kein abwärtskompatibles Angebot mehr verwenden.
Abos mit der Subscriptions Publishing API verwalten
Die Play Developer API enthält neue Funktionen für Abokäufe. Die inappproducts API für die SKU-Verwaltung funktioniert weiterhin wie zuvor, einschließlich der Verarbeitung von Einmalkaufprodukten und Abos. Sie müssen also keine sofortigen Änderungen vornehmen, um Ihre Integration aufrechtzuerhalten.
In der Google Play Console werden jedoch nur die neuen Abo-Entitäten verwendet. Nachdem du mit der Bearbeitung deiner Abos in der Console begonnen hast, 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 mit Lesezugriff angezeigt, um Probleme zu vermeiden.
Wenn Sie versuchen, Änderungen vorzunehmen, erhalten Sie möglicherweise eine Warnung, in der diese Einschränkung erläutert wird.
Bevor du Abos in der Console weiter bearbeitest, solltest du deine Backend-Integration so aktualisieren, dass die neuen Endpunkte für die Veröffentlichung von Abos 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, 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 |
listings |
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 vorhanden, sodass Sie ein Upgrade durchführen können, um neue Funktionen zu nutzen, ohne den vorhandenen Code für Abos 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.
Zusätzlich zu den alten Methoden enthält die Play Billing Library 5 jetzt ein neues ProductDetails-Objekt und eine entsprechende queryProductDetailsAsync()-Methode, um neue Entitäten und Funktionen zu verarbeiten. Vorhandene In-App-Produkte (einmalige Käufe und Verbrauchsmaterialien) 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 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 Nicht-Aboprodukte zurück. Für einmalige Käufe können Sie getOneTimePurchaseOfferDetails() verwenden.
Die Play Billing Library 5 enthält außerdem neue und 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 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 erworbene Produkt zu identifizieren.
queryPurchasesAsync() gibt alle Käufe des Nutzers zurück. Um den angeforderten Produkttyp anzugeben, können Sie wie in früheren Versionen einen BillingClient.SkuType-Wert oder ein QueryPurchasesParams-Objekt übergeben, das einen BillingClient.ProductType-Wert enthält, der die neuen Abo-Entitäten darstellt.
Wir empfehlen, deine Apps bald auf Version 5 der Bibliothek zu aktualisieren, damit du diese neuen Abofunktionen nutzen kannst.
Abostatus verwalten
In diesem Abschnitt werden die wichtigsten Änderungen an den Backend-Komponenten einer Integration des Google Play-Abrechnungssystems beschrieben, die für die Migration zu Version 5 implementiert werden müssen.
Entwicklerbenachrichtigungen in Echtzeit
In Kürze enthält das Objekt SubscriptionNotification keine subscriptionId mehr. Wenn du dieses Feld zur Identifizierung des Aboprodukts verwendest, solltest du es aktualisieren, um diese Informationen nach Erhalt der Benachrichtigung über purchases.subscriptionsv2:get aus dem Abostatus abzurufen. Jedes SubscriptionPurchaseLineItem-Element in der lineItems-Sammlung, das als Teil 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 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 purchases.subscriptionsv2:get verwenden, um den Status des Abokaufs abzurufen.
Diese API ist mit migrierten Abos, neuen Abos (sowohl Prepaid-Abos als auch Abos mit automatischer Verlängerung) 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 Legacy-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-Tarife zu unterstützen, die vom Nutzer verlängert werden, anstatt sich automatisch zu verlängern. 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 eine weitere Aufladung kaufen darf, um seinen Prepaid-Tarif zu verlängern. Ein Nutzer darf jeweils nur eine nicht verbrauchte Aufladung haben. - [Neues Feld]
SubscriptionState: Gibt den Status des Abo-Objekts an. Bei Prepaid-Tarifen ist dieser Wert immer entwederACTIVE,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 vorhanden für Prepaid-Tarife.canceled_state_context: Nicht vorhanden für Prepaid-Tarife, da dieses Feld nur für Nutzer gilt, die ein Abo aktiv kündigen.lineItems[0].productId: Dieses Feld ersetztsubscriptionIdaus früheren Versionen.
SubscriptionPurchaseV2-Felder für wiederkehrende Abos
purchases.subscriptionsv2 enthält neue Felder, die mehr Details zu neuen Abo-Objekten liefern. In der folgenden Tabelle sehen Sie, wie Felder aus dem alten Abo-Endpunkt den entsprechenden Feldern in purchases.subscriptionsv2 zugeordnet werden.
| SubscriptionPurchase | SubscriptionPurchaseV2 |
|---|---|
countryCode |
regionCode |
orderId |
latestOrderId |
| (kein Äquivalent) | lineItems.offerPhase (gibt die aktuelle Phase an: kostenloser Testzeitraum, Einführungspreis, anteilige Berechnung, Basispreis) |
| (kein Äquivalent) | lineItems (Liste von SubscriptionPurchaseLineItem), die die mit dem Kauf erworbenen Produkte darstellt |
| (kein Äquivalent) | lineItems.offerDetails.basePlanId |
| (kein Äquivalent) | lineItems.offerDetails.offerId |
| (kein Äquivalent) | lineItems.offerDetails.offerTags |
startTimeMillis |
startTime |
expiryTimeMillis |
lineItems.expiryTime (jedes im Rahmen des Kaufs erworbene Abo hat eine eigene expiryTime) |
| (kein Äquivalent) | subscriptionState (gibt den Status des Abos an) |
| (kein Äquivalent) | pausedStateContext (nur vorhanden, wenn der Abostatus SUBSCRIPTION_STATE_PAUSED ist) |
autoResumeTimeMillis |
pausedStateContext.autoResumeTime |
| (kein Äquivalent) | canceledStateContext (nur vorhanden, wenn der Abostatus SUBSCRIPTION_STATE_CANCELED ist) |
| (kein Äquivalent) | testPurchase (nur bei Käufen von lizenzierten Testern vorhanden) |
autoRenewing |
lineItems.autoRenewingPlan.autoRenewEnabled |
priceCurrenceCode,
priceAmountMicros |
lineItems.autoRenewingPlan.recurringPrice |
introductoryPriceInfo |
lineItems.offerPhase.introductoryPriceDiese Informationen finden Sie auch in der offer für jedes der gekauften Abos. |
| developerPayload | (kein entsprechendes Feld) „developerPayload“ wurde eingestellt |
| paymentState | (kein entsprechendes Feld) Du kannst den Zahlungsstatus aus subscriptionState ableiten:
|
cancelReason,
userCancellationTimeMillis,
cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken (keine Änderung) |
purchaseType |
Test: bis testPurchasePromotion: 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 zwar auf purchases.subscriptionsv2:get aktualisiert, die restlichen Funktionen zur Verwaltung von Entwicklerabos bleiben jedoch vorerst im Endpunkt purchases.subscriptions unverändert. Du kannst also purchases.subscriptions:acknowledge, purchases.subscriptions:cancel, purchases.subscriptions:defer, purchases.subscriptions:refund und purchases.subscriptions:revoke wie bisher verwenden.
Pricing API
Verwenden Sie den Endpunkt monetization.convertRegionPrices, um regionale Preise wie in der Play Console zu berechnen. Diese Methode akzeptiert einen einzelnen Preis in einer 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.