System rozliczeniowy Google Play to usługa umożliwiająca sprzedaż produktów i treści cyfrowych w aplikacji na Androida. W wersji z maja 2022 r. zmieniliśmy sposób definiowania subskrypcji, co wpływa na sposób ich sprzedaży w aplikacji i zarządzania nimi na zapleczu. Jeśli integrację z systemem płatności Google Play przeprowadzasz po raz pierwszy, możesz zacząć od przeczytania artykułu Przygotowanie.
Jeśli przed majem 2022 r. sprzedawałeś/sprzedawałaś subskrypcje za pomocą systemu rozliczeniowego Google Play, musisz wiedzieć, jak wdrożyć nowe funkcje, zachowując jednocześnie dotychczasowe subskrypcje.
Po pierwsze, wszystkie Twoje obecne subskrypcje, aplikacje i integracje backendowe działają tak samo jak przed aktualizacją z maja 2022 r. Nie musisz wprowadzać żadnych zmian. Z nowych funkcji możesz zacząć korzystać stopniowo. Każda główna wersja biblioteki Google Play Billing jest obsługiwana przez 2 lata od jej wydania. Dotychczasowe integracje z interfejsem Google Play Developer API będą działać tak jak dotąd.
Oto przegląd zmian z maja 2022 r.:
- Nowa Konsola Google Play umożliwia tworzenie subskrypcji i zarządzanie nimi, abonamentami podstawowymi oraz ofertami. Dotyczy to zarówno nowych, jak i przeniesionych subskrypcji.
- Interfejs Play Developer API zawiera aktualizacje, które umożliwiają obsługę nowych funkcji interfejsu konsoli Google Play w formie interfejsu API. Jest to m.in. nowa wersja interfejsu Subscription Purchases API. Za pomocą tego interfejsu API możesz sprawdzać stan subskrypcji i zarządzać zakupami subskrypcji.
- Nowa Biblioteka płatności w Google Play w wersji 5 pozwala korzystać z wszystkich nowych funkcji subskrypcji. Gdy zechcesz 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 w Konsoli Google Play mogą pojawić się pewne różnice.
Jedna subskrypcja może teraz mieć wiele abonamentów podstawowych i ofert. Wcześniej utworzone identyfikatory SKU subskrypcji są teraz widoczne w Konsoli Play jako nowe obiekty subskrypcji, abonamentu podstawowego i oferty. Jeśli jeszcze tego nie zrobiłeś, zapoznaj się z artykułem Najnowsze zmiany w subskrypcjach w Konsoli Play, aby poznać opisy nowych obiektów, w tym ich funkcjonalność i konfigurację. Wszystkie wcześniejsze usługi subskrypcji będą widoczne w Konsoli Google Play w tym nowym formacie. Każdy identyfikator SKU jest teraz reprezentowany przez obiekt subskrypcji, który zawiera 1 abonament podstawowy i ofertę zgodną wstecznie (w odpowiednich przypadkach).
Starsze integracje oczekują, że każda subskrypcja będzie zawierać 1 ofertę reprezentowaną przez obiekt SkuDetails, dlatego każda subskrypcja może mieć 1 abonament podstawowy lub ofertę zgodną wstecznie.
Zgodny wstecznie abonament podstawowy lub oferta są zwracane w ramach SKU w przypadku aplikacji, które korzystają z wycofanej 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 używać tylko interfejsu queryProductDetailsAsync() i nie będzie już w niej żadnych starszych wersji, które nadal dokonują 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 umożliwiające zakup subskrypcji. Interfejs API do zarządzania identyfikatorami SKU działa nadal tak jak wcześniej, w tym obsługuje produkty kupowane jednorazowo i subskrypcje, więc nie musisz wprowadzać żadnych zmian, aby utrzymać integrację.inappproducts
Pamiętaj jednak, że Konsola Google Play używa tylko nowych obiektów subskrypcji. Gdy zaczniesz edytować subskrypcje w Konsoli, interfejsu API inappproducts nie będzie można już używać do zarządzania subskrypcjami.
Jeśli korzystasz z interfejsu Publishing API przed majem 2022 r., aby uniknąć problemów, wszystkie istniejące subskrypcje są teraz widoczne w Konsoli Google Play tylko do odczytu. Jeśli spróbujesz wprowadzić zmiany, możesz zobaczyć ostrzeżenie wyjaśniające to ograniczenie. Zanim zaczniesz edytować subskrypcje w Konsoli, zaktualizuj integrację backendu, aby używać nowych punktów końcowych Publishing API. 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 z podmiotu InAppProduct są mapowane na nowe obiekty w grupie monetization.subscriptions:
| InAppProduct | Subskrypcja |
|---|---|
packageName |
packageName |
sku |
productId |
status |
basePlans[0].state |
prices |
basePlans[0].regionalConfigs.price |
listings |
informacje o produktach |
defaultPrice |
Brak odpowiednika |
subscriptionPeriod |
basePlans[0].autoRenewingBasePlanType.billingPeriodDuration |
trialPeriod |
basePlans[0].offers[0].phases[0].regionalConfigs[0].free |
gracePeriod |
basePlans[0].autoRenewingBasePlanType.gracePeriodDuration |
subscriptionTaxesAndComplianceSettings |
taxAndComplianceSettings |
Wymagane uaktualnienie interfejsu API dotyczy tylko interfejsu Publishing API (zarządzanie 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.
Obiekty i funkcje SkuDetails, takie jak querySkuDetailsAsync(), nadal są dostępne, więc możesz przejść na nowszą wersję, aby korzystać z nowych funkcji, nie aktualizując od razu kodu dotychczasowych subskrypcji.
Możesz też określić, które oferty są dostępne za pomocą tych metod, oznaczając je jako zgodne ze starszymi wersjami.
Oprócz zachowania starszych metod Biblioteka płatności w Play w wersji 5 zawiera teraz nowy obiekt ProductDetails i odpowiadającą mu metodę queryProductDetailsAsync() do obsługi nowych typów i funkcji. ProductDetails obsługuje teraz też istniejące produkty w aplikacji (produkty kupowane raz 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 dostępnych dla użytkownika niezależnie od zgodności wstecznej.
getSubscriptionOfferDetails() zwrotów null w przypadku produktów bez subskrypcji. W przypadku zakupów jednorazowych możesz użyć getOneTimePurchaseOfferDetails().
Biblioteka płatności Play w wersji 5 zawiera zarówno nowe, jak i stare metody uruchamiania 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 z abonamentu podstawowego lub oferty zgodnej wstecznie 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ące konkretny token oferty dla oferty, która jest kupowana, system używa tych informacji 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 zawierający wartość BillingClient.ProductType, która reprezentuje nowe encje subskrypcji.
Zalecamy zaktualizowanie aplikacji do wersji 5 biblioteki, aby móc korzystać z nowych funkcji subskrypcji.
Zarządzanie stanem subskrypcji
W tej sekcji opisano główne zmiany w komponentach backendu integracji z systemem rozliczeniowym Google Play, które należy wdrożyć w ramach migracji do wersji 5.
Powiadomienia w czasie rzeczywistym dla deweloperów
Wkrótce obiekt SubscriptionNotification nie będzie już zawierać atrybutu subscriptionId. Jeśli to pole służy do identyfikowania produktu subskrypcji, 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óra jest zwracana w ramach stanu zakupu, będzie zawierać odpowiedni identyfikator productId.
Interfejs API Subscriptions Purchases: pobieranie stanu subskrypcji
W poprzednich wersjach interfejsu API Subscriptions Purchases można było zapytać o stan subskrypcji za pomocą interfejsu purchases.subscriptions:get.
Ten punkt końcowy pozostaje niezmieniony i nadal działa w przypadku zakupów subskrypcji zgodnych ze starszymi wersjami. Ten punkt końcowy nie obsługuje żadnych nowych funkcji wprowadzonych w maju 2022 r.
W nowej wersji interfejsu Subscriptions Purchases API użyj parametru purchases.subscriptionsv2:get, aby uzyskać stan zakupu subskrypcji. Ten interfejs API jest zgodny z przeniesionymi subskrypcjami, nowymi subskrypcjami (zarówno przedpłaconymi, jak i z automatycznym odnawianiem) oraz zakupami wszystkich typów. Za pomocą tego punktu końcowego możesz sprawdzić stan subskrypcji podczas otrzymywania powiadomień. Zwracany obiekt SubscriptionPurchaseV2 zawiera nowe pola, ale nadal zawiera również starsze dane, które są potrzebne do obsługi dotychczasowych subskrypcji.
Pola SubscriptionPurchaseV2 w przypadku abonamentów przedpłaconych
Dodano nowe pola, aby obsługiwać abonamenty przedpłacone, które są przedłużane przez użytkownika zamiast automatycznie odnawiane. Wszystkie pola są stosowane do abonamentów przedpłaconych tak samo jak w przypadku abonamentów automatycznie odnawianych, z tymi wyjątkami:
- [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ż użytkownik może mieć tylko jedno niewykorzystane doładowanie w danym momencie.
- [Nowe pole] SubscriptionState: określa stan obiektu subskrypcji.
W przypadku abonamentów przedpłaconych ta wartość to zawsze
ACTIVE,PENDINGlubCANCELED. - lineItems[0].expiryTime: to pole jest zawsze obecne w przypadku planów przedpłaconych.
- paused_state_context: to pole nigdy nie występuje, ponieważ abonamentów 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 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 dla subskrypcji cyklicznych
purchases.subscriptionv2 zawiera nowe pola, które zawierają więcej informacji o nowych obiektach subskrypcji. Poniższa tabela pokazuje, jak pola z końcowego punktu obsługi subskrypcji w starszej wersji mapują się na odpowiadające im pola w purchases.subscriptionv2.
| SubscriptionPurchase | SubscriptionPurchaseV2 |
|---|---|
countryCode |
regionCode |
orderId |
latestOrderId |
| (brak pola odpowiadającego temu polu) | lineItems (lista SubscriptionPurchaseLineItem) reprezentująca produkty nabyte w ramach zakupu |
| (brak pola odpowiadającego temu polu) | lineItems.offerDetails.basePlanId |
| (brak pola odpowiadającego temu polu) | lineItems.offerDetails.offerId |
| (brak pola odpowiadającego temu polu) | lineItems.offerDetails.offerTags |
startTimeMillis |
startTime |
expiryTimeMillis |
lineItems.expiryTime (każda subskrypcja uzyskana w ramach zakupu ma własne expiryTime) |
| (brak pola odpowiadającego temu polu) | subscriptionState (wskazuje
stan subskrypcji) |
| (brak pola odpowiadającego temu) | pausedStateContext (obecny tylko wtedy, gdy stan subskrypcji to SUBSCRIPTION_STATE_PAUSED) |
autoResumeTimeMillis |
pausedStateContext.autoResumeTime |
| (brak pola odpowiadającego temu polu) | canceledStateContext (obecny tylko wtedy, gdy stan subskrypcji to SUBSCRIPTION_STATE_CANCELED) |
| (brak pola odpowiadającego temu polu) | testPurchase (tylko w przypadku zakupów dokonywanych przez licencjonowanych testerów) |
autoRenewing |
lineItems.autoRenewingPlan.autoRenewEnabled |
priceCurrenceCode,
priceAmountMicros |
lineItems.autoRenewingPlan.recurringPrice |
introductoryPriceInfo |
(brak pola odpowiadającego) Informacje te można znaleźć w offer każdej z kupionych subskrypcji. |
| developerPayload | (brak odpowiednika) Dane dewelopera zostały wycofane |
| paymentState | (brak pola odpowiadającego) Stan płatności możesz określić na podstawie pola subscriptionState:
|
cancelReason,
userCancellationTimeMillis,
cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken (bez zmian) |
purchaseType |
Test: przez testPurchasePromocja: 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 subskrypcją
Chociaż usługa purchases.subscriptions:get została ulepszona do wersji purchases.subscriptionsv2:get, pozostałe funkcje zarządzania subskrypcją dewelopera pozostają na razie bez zmian w usługach na poziomie purchases.subscriptions, więc możesz nadal używać opcji purchases.subscriptions:acknowledge, purchases.subscriptions:cancel, purchases.subscriptions:defer, purchases.subscriptions:refund i purchases.subscriptions:revoke.
Interfejs Pricing API
Użyj punktu końcowego monetization.convertRegionPrices, aby obliczyć ceny regionalne tak jak w Konsoli Play. Ta metoda akceptuje jedną cenę w dowolnej walucie obsługiwanej przez Google Play i zwraca ceny po przeliczeniu (w tym domyślną stawkę podatku, jeśli dotyczy) we wszystkich regionach, w których Google Play obsługuje zakupy.