System rozliczeniowy Google Play to usługa, która umożliwia sprzedaż treści i produktów cyfrowych w aplikacji na Androida. W wersji z maja 2022 roku zmieniliśmy sposób definiowania produktów objętych subskrypcją, co wpływa na sposób ich sprzedaży w aplikacji i zarządzania nimi w infrastrukturze. Jeśli po raz pierwszy przeprowadzasz integrację z Płatnościami w Google Play, możesz rozpocząć integrację, przechodząc do sekcji Przygotowywanie.
Jeśli sprzedawali subskrypcje z Płatnościami w Google Play przed majem 2022 roku, ważne jest, aby dowiedzieć się, jak wdrażać nowe funkcje i jednocześnie zachować dotychczasowe subskrypcje.
Pamiętaj, że wszystkie Twoje obecne subskrypcje, aplikacje i integracje backendowe działają tak samo jak przed premierą w maju 2022 r. Nie musisz od razu wprowadzać żadnych zmian. Nowe funkcje możesz wdrażać z czasem. Każda główna wersja Biblioteki płatności w Google Play jest obsługiwana przez 2 lata od wydania. Istniejące integracje z interfejsem Google Play Developer API będą nadal działać bez zmian.
Oto podsumowanie zmian wprowadzonych w maju 2022 roku:
- Nowa Konsola Google Play pozwala tworzyć subskrypcje, abonamenty podstawowe i oferty oraz nimi zarządzać. Obejmuje to zarówno nowe, jak i przeniesione subskrypcje.
- Interfejs Play Developer API zawiera aktualizacje obsługujące nowe funkcje interfejsu Konsoli Google Play w formie interfejsu API. W szczególności dostępna jest nowa wersja interfejsu Subscription Purchases API. Używaj tego interfejsu API, aby sprawdzać stan subskrypcji i zarządzać zakupami subskrypcji.
- Nowa Biblioteka płatności w Play w wersji 5 umożliwia korzystanie ze wszystkich nowych funkcji subskrypcji w Twojej aplikacji. Gdy zdecydujesz się przejść na wersję 5, postępuj zgodnie ze wskazówkami podanymi w przewodniku po migracji.
Konfiguracja subskrypcji
Zarządzanie subskrypcjami w Konsoli Google Play
Od maja 2022 roku można zauważyć pewne różnice w Konsoli Google Play.
Pojedyncza subskrypcja może teraz obejmować wiele abonamentów podstawowych i ofert. Wcześniej utworzone kody SKU subskrypcji wyświetlają się teraz w Konsoli Play jako nowe subskrypcje, abonament podstawowy i obiekty oferty. W sekcji Najnowsze zmiany w subskrypcjach w Konsoli Play znajdziesz opisy nowych obiektów, w tym ich funkcje i konfigurację. Wszystkie dotychczasowe usługi subskrypcji są widoczne w Konsoli Google Play w nowym formacie. Każdy kod SKU jest teraz reprezentowany przez obiekt subskrypcji, który zawiera 1 abonament podstawowy i w stosownych przypadkach ofertę zgodną wstecznie.
Ponieważ starsze integracje oczekiwały, że każda subskrypcja będzie zawierać 1 ofertę reprezentowaną przez obiekt SkuDetails, każda subskrypcja może mieć 1 zgodny wstecznie abonament podstawowy lub ofertę.
Zgodny wstecznie abonament podstawowy lub oferta są zwracane jako część kodu 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. Jeśli Twoja aplikacja korzysta tylko z queryProductDetailsAsync() i gdy żadne starsze wersje aplikacji nie będą nadal dokonywać zakupów, nie musisz już korzystać ze zgodnej oferty wstecznie.
Zarządzanie subskrypcjami za pomocą interfejsu Subscriptions Publishing API
Interfejs Play Developer API zawiera nowe funkcje dotyczące kupowania subskrypcji. Interfejs API inappproducts do zarządzania kodami SKU działa bez zmian, m.in. obsługuje produkty i subskrypcje kupowane raz, dzięki czemu nie musisz wprowadzać żadnych natychmiastowych zmian, aby zachować integrację.
Pamiętaj jednak, że w Konsoli Google Play możesz używać tylko nowych elementów subskrypcji. Gdy zaczniesz edytować subskrypcje w konsoli, nie będzie można używać interfejsu API inappproducts w przypadku subskrypcji.
Jeśli zdarzyło Ci się korzystać z interfejsu Publishing API przed majem 2022 roku, wszystkie bieżące subskrypcje będą wyświetlane w Konsoli Google Play jako dostępne tylko do odczytu, aby uniknąć problemów. Jeśli spróbujesz wprowadzić zmiany, możesz zobaczyć ostrzeżenie z wyjaśnieniem tego ograniczenia. Zanim przejdziesz do dalszej edycji subskrypcji w konsoli, zaktualizuj integrację backendu, aby używać 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 tej tabeli możesz zobaczyć, jak różne pola są mapowane z encji InAppProduct na nowe obiekty w monetization.subscriptions:
| Produkt w aplikacji | Subskrypcja |
|---|---|
packageName |
packageName |
sku |
productId |
status |
basePlans[0].state |
prices |
basePlans[0].regionalConfigs.price |
listings |
strony |
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 |
ustawienia podatków i zgodności |
Ta wymagana aktualizacja interfejsu API dotyczy tylko interfejsu API do publikowania (zarządzania 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()
wciąż istnieją, więc możesz przejść na
nową funkcję
bez konieczności natychmiastowego aktualizowania kodu subskrypcji.
Możesz też kontrolować, które oferty są dostępne za pomocą tych metod, oznaczając je jako zgodne wstecznie.
Oprócz zachowania starszych metod Biblioteka płatności w Play 5 zawiera teraz nowy obiekt ProductDetails i odpowiadającą jej metodę queryProductDetailsAsync() do obsługi nowych elementów i funkcji. ProductDetails obsługuje już dotychczasowe produkty w aplikacji (jednorazowe zakupy i produkty konsumpcyjne).
W przypadku subskrypcji ProductDetails.getSubscriptionOfferDetails() zwraca listę wszystkich abonamentów podstawowych i ofert, które użytkownik może kupić.
Oznacza to, że masz dostęp do wszystkich abonamentów podstawowych i ofert odpowiednich dla danego użytkownika, niezależnie od zgodności wstecznej.
getSubscriptionOfferDetails() zwraca wartość null w przypadku produktów, które nie są subskrybentami. W przypadku jednorazowych zakupów możesz użyć getOneTimePurchaseOfferDetails().
Biblioteka płatności w Play 5 zawiera też nowe i starsze metody rozpoczynania procesu zakupu. Jeśli obiekt BillingFlowParams przekazany do BillingClient.launchBillingFlow() jest skonfigurowany za pomocą obiektu SkuDetails, system wyodrębnia informacje o ofercie do sprzedaży ze zgodnego wstecznie abonamentu podstawowego lub oferty odpowiadającej kodowi SKU. Jeśli obiekt BillingFlowParams przekazany do BillingClient.launchBillingFlow() jest skonfigurowany za pomocą obiektów ProductDetailsParams, które obejmują ProductDetails i String reprezentujący token konkretnej oferty dla kupowanej oferty, system użyje tych informacji do identyfikacji produktu pozyskiwanego 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 zawierający wartość BillingClient.ProductType reprezentującą nowe elementy subskrypcji.
Zalecamy jak najszybsze zaktualizowanie aplikacji do wersji 5 biblioteki, aby móc korzystać z nowych funkcji subskrypcji.
Zarządzanie stanem subskrypcji
W tej sekcji opisujemy główne zmiany w komponentach backendu integracji z systemem rozliczeniowym Google Play, które trzeba wprowadzić w celu migracji do wersji 5.
Powiadomienia dla deweloperów w czasie rzeczywistym
Wkrótce obiekt SubscriptionNotification nie będzie już zawierać parametru subscriptionId. Jeśli używasz tego pola do identyfikowania usługi objętej subskrypcją, zaktualizuj dane, aby uzyskiwać te informacje na podstawie stanu subskrypcji. Aby to zrobić, po otrzymaniu powiadomienia użyj pola purchases.subscriptionv2:get. Każdy element SubscriptionPurchaseLineItem w kolekcji lineItems zwracany w ramach stanu zakupu będzie zawierał odpowiedni element productId.
Interfejs Subscriptions Purchases API: pobieranie stanu subskrypcji
W poprzednich wersjach interfejsu Subscriptions Purchases API można było tworzyć zapytania o stan subskrypcji za pomocą funkcji purchases.subscriptions:get.
Ten punkt końcowy nie ulegnie zmianie i nadal będzie działać w przypadku zakupów subskrypcji zgodnych wstecznie. Ten punkt końcowy nie obsługuje żadnych nowych funkcji opublikowanych w maju 2022 r.
W nowej wersji interfejsu Subscriptions Purchases API użyj wartości purchases.subscriptionsv2:get, aby sprawdzić stan zakupu subskrypcji. Ten interfejs API jest zgodny z przeniesionymi subskrypcjami, nowymi subskrypcjami (zarówno odnawianymi przedpłaconymi, jak i automatycznymi) oraz zakupami każdego typu. Możesz użyć tego punktu końcowego, aby sprawdzić stan subskrypcji po otrzymaniu powiadomień. Zwrócony obiekt SubscriptionPurchaseV2 zawiera nowe pola, ale wciąż zawiera starsze dane, które są niezbędne do obsługi istniejących subskrypcji.
Pola SubscriptionPurchaseV2 dotyczące 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. Do abonamentów przedpłaconych mają zastosowanie wszystkie pola tak samo jak w przypadku subskrypcji odnawianych automatycznie, z tymi wyjątkami:
- [Nowe pole] lineItems[0].prepaid_plan.allowExtendAfterTime: oznacza, kiedy użytkownik może kupić kolejne doładowanie, aby przedłużyć abonament przedpłacony, ponieważ użytkownik może jednorazowo mieć tylko 1 niewykorzystane doładowanie.
- [Nowe pole] SubscriptionState: określa stan obiektu subskrypcji.
W przypadku abonamentów przedpłaconych ta wartość zawsze wynosi
ACTIVE,PENDINGlubCANCELED. - lineItems[0].expiryTime: to pole jest zawsze obecne w przypadku abonamentów przedpłaconych.
- paused_state_context: to pole nigdy nie jest widoczne, ponieważ abonamenty przedpłacone nie mogą być wstrzymywane.
- lineItems[0].auto_renewing_plan: brak w przypadku abonamentów przedpłaconych.
- canceled_state_context: brak w przypadku abonamentów przedpłaconych, ponieważ to pole dotyczy tylko użytkowników, którzy aktywnie anulowali subskrypcję.
- lineItems[0].productId: to pole zastępuje pole
subscriptionIdz poprzednich wersji.
Pola SubscriptionPurchaseV2 dotyczące subskrypcji cyklicznych
purchases.subscriptionv2 zawiera nowe pola, które dostarczają dodatkowych informacji o nowych obiektach subskrypcji. W tabeli poniżej pokazujemy, jak pola ze starszego punktu końcowego subskrypcji są mapowane na odpowiednie pola w purchases.subscriptionv2.
| Zakup subskrypcji | Zakup subskrypcji (wersja 2) |
|---|---|
countryCode |
regionCode |
orderId |
latestOrderId |
| (brak równoważnego pola) | lineItems (lista SubscriptionPurchaseLineItem), która reprezentuje produkty nabyte razem z zakupem |
| (brak równoważnego pola) | lineItems.offerDetails.basePlanId |
| (brak równoważnego pola) | lineItems.offerDetails.offerId |
| (brak równoważnego pola) | lineItems.offerDetails.offerTags |
startTimeMillis |
startTime |
expiryTimeMillis |
lineItems.expiryTime (każda subskrypcja pozyskana w ramach zakupu ma własne expiryTime) |
| (brak równoważnego pola) | subscriptionState (wskazuje
stan subskrypcji) |
| (brak równoważnego pola) | pausedStateContext (obecny tylko wtedy, gdy stan subskrypcji to SUBSCRIPTION_STATE_PAUSED) |
autoResumeTimeMillis |
pausedStateContext.autoResumeTime |
| (brak równoważnego pola) | canceledStateContext (obecny tylko wtedy, gdy stan subskrypcji to SUBSCRIPTION_STATE_CANCELED) |
| (brak równoważnego pola) | testPurchase (tylko w przypadku zakupów licencjonowanych testerów) |
autoRenewing |
lineItems.autoRenewingPlan.autoRenewEnabled |
priceCurrenceCode,
priceAmountMicros,
introductoryPriceInfo |
(brak równoważnego pola) Te informacje można znaleźć w basePlan/offer każdej zakupionej subskrypcji. |
| DeveloperPayload | (brak równoważnego pola) ładunek programisty został wycofany |
| paymentState, | (brak równoważnego pola) Stan płatności możesz określić na podstawie wartości subscriptionState:
|
cancelReason,
userCancellationTimeMillis,
cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken (bez zmian) |
purchaseType |
Testuj: do testPurchasePromocja: (bez równoważnego pola); już wkrótce |
priceChange |
lineItems.autoRenewingPlan.priceChangeDetails |
profileName,
emailAddress,
givenName,
familyName,
profileId |
subscribeWithGoogleInfo |
acknowledgementState |
acknowledgementState (no change) |
promotionType,
promotionCode |
(brak równoważnego pola); już wkrótce |
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 subskrypcjami dla deweloperów w punkcie końcowym purchases.subscriptions na razie pozostają bez zmian, dzięki czemu można w dalszym ciągu korzystać z usług purchases.subscriptions:acknowledge,
purchases.subscriptions:cancel, purchases.subscriptions:defer, purchases.subscriptions:refund
i {19.}purchases.subscriptions:revoke{/21.}
Interfejs Pricing API
Użyj punktu końcowego monetization.convertRegionPrices, aby obliczyć ceny regionalne w taki sam sposób jak w Konsoli Play. Ta metoda akceptuje pojedynczą cenę w dowolnej walucie obsługiwanej przez Google Play i zwraca ceny przeliczone (łącznie z domyślną stawką podatku, jeśli ma to zastosowanie) we wszystkich regionach, w których Google Play obsługuje zakupy.