Das Abrechnungssystem von Google Play ist ein Dienst, über den Sie digitale Produkte und Inhalte in Ihrer Android-App verkaufen können. Mit der Veröffentlichung im Mai 2022 haben wir die Definition von Abo-Produkten geändert. Dies wirkt sich darauf aus, wie sie in der App verkauft und in Ihrem Backend verwaltet werden. Wenn Sie Google Play Billing zum ersten Mal einbinden, können Sie mit der Integration beginnen, indem Sie den Abschnitt Vorbereitung lesen.
Wenn Sie vor Mai 2022 Abos mit Google Play Billing verkauft haben, sollten Sie wissen, wie Sie neue Funktionen nutzen und gleichzeitig Ihre bestehenden Abos beibehalten können.
Alle bereits bestehenden Abos, Apps und Backend-Integrationen funktionieren noch 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. Bestehende Integrationen mit der Google Play Developer API funktionieren weiterhin wie bisher.
Hier finden Sie eine Übersicht der Updates vom Mai 2022:
- In der neuen Google Play Console können Sie Abos, Basis-Abos und Angebote erstellen und verwalten. Dazu gehören sowohl neue als auch migrierte Abos.
- Die Play Developer API enthält Updates zur Unterstützung neuer Funktionen der Google Play Console-Benutzeroberfläche in API-Form. 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 5 können Sie alle neuen Abofunktionen in Ihrer App nutzen. Wenn Sie bereit sind, auf Version 5 umzustellen, folgen Sie der Anleitung im Migrationsleitfaden.
Abos konfigurieren
Abos über die Google Play Console verwalten
Seit Mai 2022 werden Sie einige Unterschiede in der Google Play Console feststellen.
Ein einzelnes Abo kann jetzt mehrere Basis-Abos und Angebote haben. Bisher erstellte Abo-Artikelnummern werden jetzt in der Play Console als diese neuen Abo-, Basis-Abo- und Angebotsobjekte angezeigt. Falls noch nicht geschehen, finden Sie unter Kürzliche Änderungen an Abos in der Play Console Beschreibungen der neuen Objekte, einschließlich ihrer Funktionen und Konfiguration. Alle Ihre bestehenden Abo-Produkte werden in der Google Play Console in diesem neuen Format angezeigt. Jede Artikelnummer wird jetzt durch ein Abo-Objekt repräsentiert, 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 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 eingestellte Methode querySkuDetailsAsync() verwenden.
Weitere Informationen zum Konfigurieren und Verwalten abwärtskompatibler Angebote finden Sie unter Abos. Wenn Ihre App nur noch queryProductDetailsAsync() verwendet und keine Käufe mehr über ältere Versionen Ihrer App erfolgen, benötigen Sie kein abwärtskompatibles Angebot mehr.
Abos über die Subscriptions Publishing API verwalten
Die Play Developer API enthält neue Funktionen für den Kauf von Abos. Die API inappproducts für die Verwaltung von SKUs funktioniert weiterhin wie bisher, 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. 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 bestehenden Abos jetzt schreibgeschützt in der Google Play Console 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 Backend-Integration aktualisieren, damit die neuen Subscription Publishing-Endpunkte 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 von der InAppProduct-Entität zu 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 Entsprechung |
subscriptionPeriod |
basePlans[0].autoRenewingBasePlanType.billingPeriodDuration |
trialPeriod |
basePlans[0].offers[0].phases[0].regionalConfigs[0].free |
gracePeriod |
basePlans[0].autoRenewingBasePlanType.gracePeriodDuration |
subscriptionTaxesAndComplianceSettings |
taxAndComplianceSettings |
Diese erforderliche API-Aktualisierung gilt nur für die Publishing API (SKU-Verwaltung).
Änderungen an der Play Billing Library
Um eine schrittweise Migration zu ermöglichen, 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. Sie können also ein Upgrade durchführen, um neue Funktionen zu nutzen, ohne auch sofort den vorhandenen Code für Abos aktualisieren zu müssen.
Sie können auch steuern, welche Angebote über diese Methoden verfügbar sind, indem Sie sie als abwärtskompatibel kennzeichnen.
Zusätzlich zu den Legacy-Methoden enthält die Play Billing Library 5 jetzt ein neues ProductDetails-Objekt und eine entsprechende queryProductDetailsAsync()-Methode zur Verarbeitung neuer Einheiten und Funktionen. Vorhandene In-App-Produkte (Einmalkäufe und Verbrauchsgüter) werden jetzt auch von ProductDetails unterstützt.
Für ein 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 keine Abos sind. Für einmalige Käufe können Sie getOneTimePurchaseOfferDetails() verwenden.
Die Play Billing Library 5 enthält sowohl neue als auch alte Methoden zum Starten des Kaufvorgangs. Wenn das BillingFlowParams-Objekt, das an BillingClient.launchBillingFlow() übergeben wird, 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 wird, 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 zurück, die dem Nutzer gehören. Um den angeforderten Produkttyp anzugeben, können Sie wie in älteren 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, 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 Integration des Google Play-Abrechnungssystems beschrieben, die für die Migration zu Version 5 implementiert werden müssen.
Entwicklerbenachrichtigungen in Echtzeit
Das SubscriptionNotification-Objekt enthält bald keine subscriptionId mehr. Wenn Sie sich auf dieses Feld verlassen, um das Abo-Produkt zu identifizieren, sollten Sie es aktualisieren, um diese Informationen aus dem Abo-Status mit purchases.subscriptionv2:get zu beziehen, sobald Sie die Benachrichtigung erhalten. Jedes SubscriptionPurchaseLineItem-Element in der lineItems-Sammlung, die 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 konnten Sie den Abostatus mit purchases.subscriptions:get abfragen.
Dieser Endpunkt ist unverändert und funktioniert weiterhin für abwärtskompatible Abo-Käufe. Dieser Endpunkt unterstützt nicht die neuen Funktionen, die im Mai 2022 eingeführt wurden.
In der neuen Version der Subscriptions Purchases API verwenden Sie purchases.subscriptionsv2:get, um den Status des Abokaufs abzurufen. Diese API ist mit migrierten Abos, neuen Abos (sowohl Prepaid- als auch Abos mit automatischer Verlängerung) und Käufen aller Art kompatibel. Sie können diesen Endpunkt verwenden, um den Abostatus zu 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 und sich nicht automatisch verlängern. Alle Felder gelten für Prepaid-Tarife wie für Abos, die sich automatisch verlängern, mit den folgenden Ausnahmen:
- [Neues Feld] lineItems[0].prepaid_plan.allowExtendAfterTime: Gibt an, wann ein Nutzer ein weiteres Guthaben aufladen darf, um seinen Prepaid-Tarif zu verlängern. Nutzer dürfen jeweils nur ein nicht genutztes Guthaben haben.
- [Neues Feld] SubscriptionState: Gibt den Status des Aboobjekts an.
Bei Prepaid-Abos ist dieser Wert immer
ACTIVE,PENDINGoderCANCELED. - lineItems[0].expiryTime: Dieses Feld ist für Prepaid-Abos immer vorhanden.
- paused_state_context: Dieses Feld ist nie vorhanden, da Prepaid-Tarife nicht pausiert werden können.
- lineItems[0].auto_renewing_plan: Nicht für Prepaid-Tarife vorhanden.
- canceled_state_context: Nicht für Prepaid-Abos 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, 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.subscriptionv2 zugeordnet werden.
| SubscriptionPurchase | SubscriptionPurchaseV2 |
|---|---|
countryCode |
regionCode |
orderId |
latestOrderId |
| (kein entsprechendes Feld) | lineItems.offerPhase (gibt die aktuelle Phase an: kostenloses Probeabo, Einführungspreis, anteilige Berechnung, Grundpreis) |
| (kein entsprechendes Feld) | lineItems (Liste von SubscriptionPurchaseLineItem), die 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 im Kauf erworbene Abo hat ein eigenes expiryTime) |
| (kein entsprechendes Feld) | subscriptionState (gibt 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 durch Lizenztester 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) Die Entwicklernutzlast wurde eingestellt. |
| paymentState | (kein entsprechendes Feld) Sie können den Zahlungsstatus aus 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 aktualisiert. Die restlichen Funktionen zur Verwaltung von Entwicklerabos bleiben vorerst im purchases.subscriptions-Endpunkt unverändert. Sie können also weiterhin 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 beliebigen von Play unterstützten Währung und gibt umgerechnete Preise (einschließlich des Standardsteuersatzes, sofern zutreffend) für alle Regionen zurück, in denen Google Play Käufe unterstützt.