Przewodnik po zmianach w subskrypcjach w maju 2022 r.

System rozliczeniowy Google Play to usługa, która umożliwia sprzedaż produktów i treści cyfrowych w aplikacji na Androida. W wersji z maja 2022 r. zmieniliśmy sposób definiowania produktów subskrypcyjnych, co ma wpływ na sposób ich sprzedaży w aplikacji i zarządzania nimi na serwerze backendu. Jeśli po raz pierwszy integrujesz system rozliczeniowy Google Play, możesz zacząć od przeczytania artykułu Przygotowania.

Jeśli przed majem 2022 r. sprzedawałeś(-aś) subskrypcje za pomocą systemu płatności w Google Play, musisz wiedzieć, jak wdrożyć nowe funkcje, zachowując dotychczasowe subskrypcje.

Po pierwsze, wszystkie Twoje obecne subskrypcje, aplikacje i integracje backendowe będą działać tak samo jak przed wprowadzeniem zmian w maju 2022 r. Nie musisz od razu wprowadzać zmian. Z nowych funkcji możesz zacząć korzystać stopniowo. Każda główna wersja Biblioteki płatności w Google Play jest obsługiwana przez 2 lata od jej wprowadzenia. Dotychczasowe integracje z Google Play Developer API będą nadal działać jak wcześniej.

Oto przegląd zmian z maja 2022 r.:

Konfiguracja subskrypcji

Zarządzanie subskrypcjami w Konsoli Google Play

Od maja 2022 roku w Konsoli Google Play zauważysz pewne różnice.

Jedna subskrypcja może teraz mieć wiele abonamentów podstawowych i ofert. Wcześniej utworzone kody SKU subskrypcji są teraz widoczne w Konsoli Play jako nowe obiekty subskrypcji, abonamentu podstawowego i oferty. Jeśli jeszcze tego nie zrobiono, zapoznaj się z artykułem Najnowsze zmiany w subskrypcjach w Konsoli Play, w którym znajdziesz opisy nowych obiektów, w tym ich funkcjonalności i konfiguracji. Wszystkie Twoje dotychczasowe produkty subskrypcyjne będą widoczne w Konsoli Google Play w tym nowym formacie. Każdy SKU jest teraz reprezentowany przez obiekt subskrypcji, który zawiera 1 abonament podstawowy i ofertę zgodną wstecznie (w stosownych przypadkach).

Starsze integracje oczekiwały, że każda subskrypcja będzie zawierać 1 ofertę reprezentowaną przez obiekt SkuDetails. Dlatego każda subskrypcja może mieć 1 abonament podstawowy lub 1 ofertę o zgodności wstecznej. Zgodny wstecznie abonament podstawowy lub oferta jest zwracany(-a) jako część SKU w przypadku aplikacji, które korzystają z wycofanej już metody querySkuDetailsAsync(). Więcej informacji o konfigurowaniu ofert zgodnych wstecznie i zarządzaniu nimi znajdziesz w artykule Informacje o subskrypcjach. Gdy Twoja aplikacja będzie korzystać tylko z queryProductDetailsAsync() i gdy starsze wersje aplikacji nie będą już dokonywać zakupów, nie musisz już korzystać z oferty zgodnej wstecznie.

Zarządzanie subskrypcjami za pomocą interfejsu Subscriptions Publishing API

Interfejs Play Developer API zawiera nowe funkcje dotyczące zakupu subskrypcji. Interfejs API do zarządzania kodami SKUinappproducts nadal działa jak wcześniej, w tym obsługuje produkty kupowane raz i subskrypcje, więc nie musisz wprowadzać żadnych natychmiastowych zmian, aby utrzymać integrację.

Pamiętaj jednak, że Konsola Google Play używa tylko nowych obiektów subskrypcji. Gdy zaczniesz edytować subskrypcje w Konsoli, nie będzie można już używać interfejsu inappproducts API do zarządzania subskrypcjami.

Jeśli przed majem 2022 r. korzystałeś(-aś) z interfejsu Publishing API, aby uniknąć problemów, wszystkie dotychczasowe subskrypcje będą teraz widoczne w Konsoli Play Google jako tylko do odczytu. Jeśli spróbujesz wprowadzić zmiany, może pojawić się ostrzeżenie wyjaśniające to ograniczenie. Zanim zaczniesz dalej edytować subskrypcje w Konsoli, zaktualizuj integrację backendu, aby korzystać z nowych punktów końcowych publikowania subskrypcji. Nowe punkty końcowe monetization.subscriptions, monetization.subscriptions.baseplans i monetization.subscriptions.offers umożliwiają zarządzanie wszystkimi dostępnymi abonamentami podstawowymi i ofertami. W tabeli poniżej możesz zobaczyć, jak różne pola są mapowane z InAppProduct na nowe obiekty w sekcji monetization.subscriptions:

InAppProduct Subskrypcja
packageName packageName
sku productId
status basePlans[0].state
prices basePlans[0].regionalConfigs.price
listings informacje o produktach,
defaultPrice Brak równoważności
subscriptionPeriod basePlans[0].autoRenewingBasePlanType.billingPeriodDuration
trialPeriod basePlans[0].offers[0].phases[0].regionalConfigs[0].free
gracePeriod basePlans[0].autoRenewingBasePlanType.gracePeriodDuration
subscriptionTaxesAndComplianceSettings taxAndComplianceSettings

Ta wymagana aktualizacja interfejsu API dotyczy tylko interfejsu Publishing API (zarządzanie kodami SKU).

Zmiany w Bibliotece płatności w Play

Aby umożliwić stopniową migrację, Biblioteka płatności w Play zawiera wszystkie metody i obiekty dostępne w poprzednich wersjach. SkuDetails obiekty i funkcje, takie jak querySkuDetailsAsync(), nadal istnieją, więc możesz przejść na nowe funkcje bez konieczności natychmiastowej aktualizacji kodu istniejących subskrypcji. Możesz też określić, które oferty są dostępne w ten sposób, oznaczając je jako wstecznie kompatybilne.

Biblioteka płatności w Google Play 5 oprócz zachowania starszych metod zawiera teraz nowy obiekt ProductDetails i odpowiadającą mu metodę queryProductDetailsAsync() do obsługi nowych podmiotów i funkcji. ProductDetails obsługuje teraz też istniejące produkty w aplikacji (zakupy jednorazowe i produkty konsumpcyjne).

W przypadku subskrypcji funkcja ProductDetails.getSubscriptionOfferDetails() zwraca listę wszystkich abonamentów podstawowych i ofert, które użytkownik może kupić. Oznacza to, że możesz uzyskać dostęp do wszystkich abonamentów podstawowych i ofert kwalifikujących się dla użytkownika, niezależnie od zgodności wstecznej. getSubscriptionOfferDetails() zwroty null w przypadku produktów nieobjętych subskrypcją. W przypadku zakupów jednorazowych możesz użyć getOneTimePurchaseOfferDetails().

Biblioteka płatności w Play w wersji 5 zawiera też nowe i starsze metody uruchamiania procesu zakupu. Jeśli obiekt BillingFlowParams przekazany do funkcji BillingClient.launchBillingFlow() jest skonfigurowany za pomocą obiektu SkuDetails, system wyodrębnia informacje o ofercie do sprzedaży z abonamentu podstawowego lub oferty zgodnej wstecznie, która odpowiada kodowi SKU. Jeśli obiekt BillingFlowParams przekazywany do BillingClient.launchBillingFlow() jest skonfigurowany za pomocą obiektów ProductDetailsParams, które zawierają ProductDetails i String reprezentujące konkretny token oferty dla kupowanej oferty, system wykorzystuje te informacje do identyfikacji produktu nabywanego przez użytkownika.

queryPurchasesAsync() – zwraca wszystkie zakupy należące do użytkownika. Aby wskazać żądany typ produktu, możesz przekazać wartość BillingClient.SkuType, tak jak w starszych wersjach, lub obiekt QueryPurchasesParams, który zawiera wartość BillingClient.ProductType reprezentującą nowe jednostki subskrypcji.

Zalecamy zaktualizowanie aplikacji do wersji 5 biblioteki, aby móc korzystać z tych nowych funkcji subskrypcji.

Zarządzanie stanem subskrypcji

W tej sekcji opisujemy główne zmiany w komponentach backendu integracji systemu rozliczeniowego Google Play, które należy wdrożyć, aby przejść na wersję 5.

Powiadomienia w czasie rzeczywistym dla deweloperów

Wkrótce obiekt SubscriptionNotification przestanie zawierać element subscriptionId. Jeśli używasz tego pola do identyfikowania produktu subskrypcyjnego, po otrzymaniu powiadomienia zaktualizuj je, aby uzyskać te informacje ze stanu subskrypcji za pomocą purchases.subscriptionv2:get. Każdy element SubscriptionPurchaseLineItem w kolekcji lineItems, który jest zwracany w ramach stanu zakupu, będzie zawierać odpowiedni productId.

Interfejs Subscriptions Purchases API: pobieranie stanu subskrypcji

W poprzednich wersjach interfejsu Subscriptions Purchases API można było sprawdzać stan subskrypcji za pomocą metody purchases.subscriptions:get. Ten punkt końcowy pozostaje bez zmian i nadal działa w przypadku zakupów subskrypcji zgodnych wstecznie. Ten punkt końcowy nie obsługuje żadnych nowych funkcji udostępnionych w maju 2022 r.

W nowej wersji interfejsu Subscriptions Purchases API używaj purchases.subscriptionsv2:get do uzyskiwania stanu zakupu subskrypcji. Ten interfejs API jest zgodny z przeniesionymi subskrypcjami, nowymi subskrypcjami (zarówno przedpłaconymi, jak i odnawianymi automatycznie) oraz zakupami wszystkich typów. Możesz użyć tego punktu końcowego, aby sprawdzić stan subskrypcji podczas otrzymywania powiadomień. Zwracany obiekt SubscriptionPurchaseV2 zawiera nowe pola, ale nadal obejmuje starsze dane, które są potrzebne do dalszej obsługi istniejących subskrypcji.

Pola SubscriptionPurchaseV2 w przypadku abonamentów przedpłaconych

Dodaliśmy nowe pola, aby obsługiwać abonamenty przedpłacone, które są przedłużane przez użytkownika, a nie odnawiane automatycznie. Wszystkie pola mają zastosowanie do abonamentów przedpłaconych, tak jak w przypadku subskrypcji odnawianych automatycznie, z wyjątkiem tych:

  • [Nowe pole] lineItems[0].prepaid_plan.allowExtendAfterTime: określa, kiedy użytkownik będzie mógł kupić kolejne doładowanie, aby przedłużyć abonament przedpłacony, ponieważ może mieć tylko jedno niewykorzystane doładowanie naraz.
  • [Nowe pole] SubscriptionState: określa stan obiektu subskrypcji. W przypadku abonamentów przedpłaconych ta wartość to zawsze ACTIVE, PENDING lub CANCELED.
  • lineItems[0].expiryTime: to pole jest zawsze obecne w przypadku planów przedpłaconych.
  • paused_state_context: to pole nigdy nie występuje, ponieważ subskrypcji przedpłaconych nie można wstrzymać.
  • lineItems[0].auto_renewing_plan: nie występuje w przypadku abonamentów przedpłaconych.
  • canceled_state_context: nie występuje w przypadku planów przedpłaconych, ponieważ to pole dotyczy tylko użytkowników, którzy aktywnie anulują subskrypcję.
  • lineItems[0].productId: to pole zastępuje pole subscriptionId z poprzednich wersji.

Pola SubscriptionPurchaseV2 w przypadku subskrypcji cyklicznych

purchases.subscriptionv2 zawiera nowe pola, które dostarczają więcej szczegółów o nowych obiektach subskrypcji. W tabeli poniżej pokazujemy, jak pola z starszego punktu końcowego subskrypcji są mapowane na odpowiednie pola w purchases.subscriptionv2.

SubscriptionPurchase SubscriptionPurchaseV2
countryCode regionCode
orderId latestOrderId
(brak odpowiedniego pola) lineItems.offerPhase (określa bieżący etap: bezpłatny okres próbny, cena początkowa, proporcjonalna cena, cena bazowa)
(brak odpowiedniego pola) lineItems (lista SubscriptionPurchaseLineItem), która reprezentuje produkty uzyskane w ramach zakupu.
(brak odpowiedniego pola) lineItems.offerDetails.basePlanId
(brak odpowiedniego pola) lineItems.offerDetails.offerId
(brak odpowiedniego pola) lineItems.offerDetails.offerTags
startTimeMillis startTime
expiryTimeMillis lineItems.expiryTime (każda subskrypcja uzyskana w ramach zakupu ma własny expiryTime)
(brak odpowiedniego pola) subscriptionState (wskazuje stan subskrypcji)
(brak odpowiedniego pola) pausedStateContext (występuje tylko wtedy, gdy stan subskrypcji to SUBSCRIPTION_STATE_PAUSED)
autoResumeTimeMillis pausedStateContext.autoResumeTime
(brak odpowiedniego pola) canceledStateContext (występuje tylko wtedy, gdy stan subskrypcji to SUBSCRIPTION_STATE_CANCELED)
(brak odpowiedniego pola) testPurchase (występuje tylko w przypadku zakupów licencjonowanych testerów)
autoRenewing lineItems.autoRenewingPlan.autoRenewEnabled
priceCurrenceCode, priceAmountMicros lineItems.autoRenewingPlan.recurringPrice
introductoryPriceInfo lineItems.offerPhase.introductoryPrice
Te informacje znajdziesz też w offer dotyczącym każdej kupionej subskrypcji.
developerPayload (brak odpowiedniego pola) pole danych dewelopera zostało wycofane
paymentState (brak odpowiedniego pola)
Stan płatności możesz wywnioskować z pola subscriptionState:
  • Płatność oczekuje na przetworzenie:
    • SUBSCRIPTION_STATE_PENDING (nowe zakupy z transakcją oczekującą)
    • SUBSCRIPTION_STATE_IN_GRACE_PERIOD
    • SUBSCRIPTION_STATE_ON_HOLD
  • Płatność została otrzymana:
    • SUBSCRIPTION_STATE_ACTIVE
  • Bezpłatny okres próbny:
    • lineItems.offerPhase.freeTrial
  • Odroczone uaktualnienie lub przejście na niższą wersję:
    • SUBSCRIPTION_STATE_PENDING
cancelReason, userCancellationTimeMillis, cancelSurveyResult canceledStateContext
linkedPurchaseToken linkedPurchaseToken (bez zmian)
purchaseType Test: do testPurchase
Promocja: signupPromotion
priceChange lineItems.autoRenewingPlan.priceChangeDetails
profileName, emailAddress, givenName, familyName, profileId subscribeWithGoogleInfo
acknowledgementState acknowledgementState (no change)
promotionType, promotionCode signupPromotion
externalAccountId, obfuscatedExternalAccountId, obfuscatedExteranlProfileId externalAccountIdentifiers

Inne funkcje zarządzania subskrypcjami

Usługa purchases.subscriptions:get została uaktualniona do wersji purchases.subscriptionsv2:get, ale pozostałe funkcje zarządzania subskrypcją dewelopera w punkcie końcowym purchases.subscriptions pozostają na razie bez zmian, więc możesz nadal korzystać z funkcji purchases.subscriptions:acknowledge, purchases.subscriptions:cancel, purchases.subscriptions:defer, purchases.subscriptions:refund i purchases.subscriptions:revoke w taki sam sposób jak wcześniej.

Pricing API

Użyj punktu końcowego monetization.convertRegionPrices do obliczania cen regionalnych w taki sam sposób jak w Konsoli Play. Ta metoda przyjmuje jedną cenę w dowolnej walucie obsługiwanej przez Google Play i zwraca przeliczone ceny (w tym domyślną stawkę podatku, jeśli ma to zastosowanie) dla wszystkich regionów, w których Google Play obsługuje zakupy.