Przechodzenie z wersji 4 lub 5 do Biblioteki płatności w Google Play 6

Z tego artykułu dowiesz się, jak przejść z Biblioteki płatności w Google Play 4 lub 5 na Bibliotekę płatności w Google Play 6 oraz jak korzystać z nowych możliwości subskrypcji.

Pełną listę zmian w wersji 6.0.0 znajdziesz w informacjach o wersji.

Przegląd

Biblioteka płatności w Google Play 6 to nowe funkcje subskrypcji wprowadzone w wersji 5 i zawierające kilka dodatkowych ulepszeń. Funkcje te umożliwiają sprzedaż subskrypcji na więcej sposobów, a tym samym ograniczanie kosztów operacyjnych przez wyeliminowanie konieczności tworzenia coraz większej liczby kodów SKU i zarządzania nimi.

Więcej informacji o nowych funkcjach wprowadzonych w Bibliotece płatności w Play znajdziesz w artykule Najnowsze zmiany w subskrypcjach w Konsoli Play.

Zgodna wstecznie aktualizacja Biblioteki płatności w Play

Wszystkie dotychczasowe usługi objęte subskrypcjami zostały automatycznie przekonwertowane na nowy model w maju 2022 r. w ramach Biblioteki płatności w Google Play 5 i nowej platformy subskrypcji. Oznacza to, że nie musisz wprowadzać żadnych zmian w konfiguracji usług objętych subskrypcją, aby mieć katalog zgodny z nowymi wersjami Biblioteki płatności w Play. Więcej informacji o przekształcaniu kodów SKU subskrypcji w subskrypcje zgodne wstecznie znajdziesz w sekcji Praca ze starszymi subskrypcjami w artykule pomocy na temat Konsoli Play.

Starsze wersje Twojej aplikacji nadal działają

Jeśli masz zgodny wstecznie katalog subskrypcji, wszystkie istniejące wersje Twojej aplikacji powinny nadal działać zgodnie z oczekiwaniami w przypadku tych usług. Jednorazowe zakupy produktów również powinny działać bez problemów w starszych wersjach.

Wersje aplikacji korzystające z wycofanych metod (np. querySkuDetailsAsync()) nie będą mogły sprzedawać abonamentów podstawowych ani ofert, które nie są zgodne wstecznie. Informacje o ofertach zgodnych wstecznie znajdziesz w odpowiednim artykule w Centrum pomocy Konsoli Play.

Przejdź na Bibliotekę płatności w Google Play w wersji 5 lub 6

Biblioteka płatności w Google Play 5 i 6 zawiera wycofane metody querySkuDetailsAsync i BillingFlowParams.Builder.setSkuDetails, które wykorzystują SkuDetails jako parametr procesu płatności. Oznacza to, że możesz stopniowo przejść na Bibliotekę płatności w Play 6, planując różne etapy migracji.

W pierwszym kroku migracji możesz po prostu zaktualizować wersję biblioteki, pozostawić katalog i backend bez zmian, a potem przetestować aplikację z wykorzystaniem wycofanych metod. Jeśli nie używasz queryPurchases, launchPriceChangeFlow lub setVrPurchaseFlow, powinno ono nadal działać zgodnie z oczekiwaniami. Potem możesz przeprowadzić iterację, aby w pełni wdrożyć nowe funkcje subskrypcji opublikowane w maju 2022 r.

Jeśli korzystasz już z tych funkcji w ramach migracji Biblioteki płatności w Google Play 5, możesz przejść bezpośrednio do sekcji Aktualizowanie biblioteki płatności w Google Play i Zmienianie subskrypcji subskrypcji użytkownika. Jeśli zaczynasz od wcześniejszej wersji lub nie korzystasz jeszcze w pełni z nowych funkcji, możesz zapoznać się z dalszymi instrukcjami migracji, aby dowiedzieć się, jak je wdrożyć.

Pełne kroki migracji

Utwórz nowe subskrypcje w katalogu produktów backendu

Za pomocą Konsoli Play lub interfejsu Play Developer API możesz teraz skonfigurować 1 subskrypcję z wieloma abonamentami podstawowymi, z których każdy może zawierać wiele ofert. Oferty subskrypcji mają elastyczne modele cenowe i opcje kwalifikacji. Możesz tworzyć oferty przez cały cykl życia subskrypcji za pomocą różnych automatycznie odnawianych i przedpłaconych abonamentów.

Przed przeniesieniem aplikacji zalecamy utworzenie nowych usług zgodnie ze strukturą encji na nowej platformie subskrypcji na potrzeby integracji Biblioteki płatności w Play 6. Możesz skonsolidować zduplikowane produkty w starym katalogu i reprezentować te same korzyści związane z uprawnieniami w ramach 1 subskrypcji oraz użyć abonamentu podstawowego i konfiguracji oferty, aby reprezentować wszystkie opcje, które chcesz oferować. Więcej informacji o tej rekomendacji znajdziesz w sekcji Korzystanie ze starszych subskrypcji w artykule pomocy na temat Konsoli Play.

Po wprowadzeniu zmian w maju 2022 r. nie modyfikuj przekonwertowanych usług objętych subskrypcją. Nie wprowadzaj zmian, które mają zostać sprzedane wraz z wersjami Twojej aplikacji, z wykorzystaniem wycofanych metod (np. querySkuDetailsAsync()) bez wprowadzania zmian, które mogłyby mieć wpływ na starsze kompilacje.

Proces konwersji sprawił, że usługi objęte subskrypcją, które były w Twoim katalogu przed majem 2022 r., były dostępne tylko do odczytu, aby uniknąć przypadkowych zmian, które mogłyby spowodować problemy z Twoją dotychczasową integracją. Wprowadzanie zmian w tych subskrypcjach jest możliwe, ale wiążą się z tym pewne konsekwencje, które mogą wpłynąć na integracje frontendu i backendu:

  • We frontendzie wersje aplikacji korzystające z querySkuDetailsAsync() do uzyskiwania informacji o subskrypcji mogą sprzedawać tylko zgodne wstecznie abonamenty podstawowe i oferty. Może istnieć tylko 1 kombinacja abonamentu podstawowego i ofert. Jeśli więc dodasz do przekształconych subskrypcji nowe abonamenty podstawowe lub oferty, nowe abonamenty podstawowe i oferty nie będą dostępne w tych starszych wersjach aplikacji.

  • Jeśli w interfejsie Konsoli Play zmodyfikujesz przekonwertowane subskrypcje w backendzie, nie będzie można nimi zarządzać za pomocą punktu końcowego inappproducts, jeśli ten punkt końcowy był wywoływany w tym celu. Aby zarządzać zakupami tych subskrypcji, musisz też przejść na nowy punkt końcowy stanu zakupu subskrypcji (purchases.subscriptionsv2.get), ponieważ stary punkt końcowy stanu zakupu (purchases.subscriptions.get) zwraca tylko dane niezbędne do obsługi zgodnych wstecznie abonamentów podstawowych i ofert. Więcej informacji znajdziesz w sekcji Zarządzanie stanem zakupu subskrypcji.

Zarządzanie katalogiem subskrypcji backendu przy użyciu nowego interfejsu API

Jeśli automatycznie zarządzasz katalogiem produktów objętych subskrypcją za pomocą interfejsu Google Play Developer API, do tworzenia subskrypcji, abonamentów podstawowych i ofert oraz zarządzania nimi musisz używać nowych punktów końcowych definicji produktów objętych subskrypcją. Aby dowiedzieć się więcej o zmianach interfejsu API katalogu produktów w tej wersji, przeczytaj przewodnik po funkcjach subskrypcji w maju 2022 roku.

Aby przenieść moduł automatycznego zarządzania katalogiem produktów w przypadku subskrypcji w usłudze Płatności w Google Play, zastąp inappproducts nowym interfejsem Subscription Publishing API nowym, aby zarządzać katalogiem subskrypcji i je publikować. Dostępne są 3 nowe punkty końcowe:

Te nowe punkty końcowe zapewniają wszystkie funkcje niezbędne do korzystania z nowych funkcji dostępnych w katalogu: m.in. tagów abonamentu podstawowego i ofert, kierowania na region czy abonamentów przedpłaconych.

Do zarządzania katalogiem produktów w aplikacji w przypadku produktów do jednorazowego zakupu należy nadal używać interfejsu API inappproducts.

Wersje aplikacji korzystające z wycofanych metod (np. querySkuDetailsAsync()) nie będą mogły sprzedawać abonamentów podstawowych ani ofert, które nie są zgodne wstecznie. Więcej informacji o ofertach zgodnych wstecznie znajdziesz tutaj.

Aktualizowanie Biblioteki płatności w Google Play

Gdy utworzysz katalog nowych produktów objętych subskrypcją, możesz przenieść swoją aplikację do Biblioteki płatności Google 5. Zastąp istniejącą zależność Biblioteki płatności w Play zaktualizowaną wersją pliku build.gradle aplikacji.

dependencies {
    def billingVersion = "6.0.0"

    implementation "com.android.billingclient:billing:$billingVersion"
}

Projekt powinien zostać od razu skompilowany nawet wtedy, gdy nie masz zmodyfikowanych żadnych wywołań metod – Biblioteka płatności w Play 6 jest zgodna wstecznie. Kod SKU jest uważany za wycofany, ale wciąż dostępny, aby uprościć proces przenoszenia aplikacji i zwiększać jego przyrost.

Inicjowanie klienta rozliczeniowego i nawiązywanie połączenia z Google Play

Pierwsze kroki w generowaniu zakupów w aplikacji na Androida pozostają takie same:

Pokaż produkty dostępne do kupienia

Aby uzyskać wszystkie oferty, które użytkownik może kupić:

  • Zamień SkuDetailsParams na QueryProductDetailsParams
  • Przełącz wywołanie BillingClient.querySkuDetailsAsync() na BillingClient.queryProductDetailsAsync()

Zwróć uwagę, że wyniki zapytania to teraz ProductDetails, a nie SkuDetails. Każdy element ProductDetails zawiera informacje o produkcie (identyfikator, tytuł, typ itd.). W przypadku produktów objętych subskrypcją ProductDetails zawiera element List<ProductDetails.SubscriptionOfferDetails>, który jest listą szczegółów oferty subskrypcji. W przypadku produktów do jednorazowego zakupu właściwość ProductDetails zawiera ProductDetails.OneTimePurchaseOfferDetails. Na podstawie tych informacji możesz zdecydować, które oferty wyświetlać użytkownikom.

Na przykładzie poniżej możesz zobaczyć, jak może wyglądać aplikacja przed wprowadzeniem tych zmian i po ich wprowadzeniu:

Przed

Kotlin

val skuList = ArrayList<String>()

skuList.add("up_basic_sub")

val params = SkuDetailsParams.newBuilder()

params.setSkusList(skuList).setType(BillingClient.SkuType.SUBS).build()

billingClient.querySkuDetailsAsync(params) {
    billingResult,
    skuDetailsList ->
    // Process the result
}

Java

List<String> skuList = new ArrayList<>();

skuList.add("up_basic_sub");

SkuDetailsParams.Builder params = SkuDetailsParams.newBuilder();

params.setSkusList(skuList).setType(SkuType.SUBS).build();

billingClient.querySkuDetailsAsync(params,
    new SkuDetailsResponseListener() {
        @Override
        public void onSkuDetailsResponse(BillingResult billingResult,
                List<SkuDetails> skuDetailsList) {
            // Process the result.
        }
    }
);

Po

Kotlin

val productList =
    listOf(
        QueryProductDetailsParams.Product.newBuilder()
            .setProductId("up_basic_sub")
            .setProductType(BillingClient.ProductType.SUBS)
            .build()
    )

val params = QueryProductDetailsParams.newBuilder().setProductList(productList).build()

billingClient.queryProductDetailsAsync(params) {
    billingResult,
    productDetailsList ->
    // Process the result
}

Java

ImmutableList<Product> productList = ImmutableList.of(Product.newBuilder()
                                            .setProductId("up_basic_sub")
                                            .setProductType(ProductType.SUBS)
                                            .build());

QueryProductDetailsParams params = QueryProductDetailsParams.newBuilder()
    .setProductList(productList)
    .build();

billingClient.queryProductDetailsAsync(
        params,
        new ProductDetailsResponseListener() {
                public void onProductDetailsResponse(BillingResult billingResult, List<ProductDetails> productDetailsList) {
                    // Process the result
                }
        }
);

Wywołanie zwrotne dla queryProductDetailsAsync zwraca wartość List<ProductDetails>. Każdy element ProductDetails zawiera informacje o produkcie (identyfikator, tytuł, typ itd.). Główna różnica polega na tym, że usługi objęte subskrypcją zawierają teraz także atrybut List<ProductDetails.SubscriptionOfferDetails>, który zawiera wszystkie oferty dostępne dla użytkownika.

Poprzednie wersje Biblioteki płatności w Play nie obsługują nowych obiektów (subskrypcji, abonamentów podstawowych, ofert itp.), dlatego nowy system konwertuje każdy kod SKU subskrypcji na jeden zgodny wstecznie abonament podstawowy i ofertę. Dostępne produkty do jednorazowego zakupu są też przenoszone do obiektu ProductDetails. Szczegóły oferty dotyczące jednorazowego zakupu można uzyskać za pomocą metody getOneTimePurchaseOfferDetails().

Rzadko niektóre urządzenia nie obsługują ProductDetails i queryProductDetailsAsync(). Zazwyczaj dzieje się tak z powodu nieaktualnych wersji Usług Google Play. Aby zapewnić odpowiednią pomoc w przypadku tego scenariusza, wywołaj funkcję isFeatureSupported() dla funkcji PRODUCT_DETAILS przed wywołaniem metody queryProductDetailsAsync. Jeśli odpowiedź to OK, urządzenie obsługuje tę funkcję i możesz kontynuować wywoływanie funkcji queryProductDetailsAsync(). Jeśli odpowiedź to FEATURE_NOT_SUPPORTED, możesz zamiast tego poprosić o dostępną listę usług zgodnych wstecznie za pomocą metody querySkuDetailsAsync(). Więcej informacji o korzystaniu z funkcji zgodności wstecznej znajdziesz w przewodniku po funkcjach subskrypcji z maja 2022 roku.

Uruchamianie procesu zakupu oferty

Rozpoczęcie procesu zakupu oferty jest bardzo podobne do uruchomienia procesu dla kodu SKU. Aby wysłać prośbę o zakup w wersji 6:

  • Zamiast SkuDetails w przypadku elementu BillingFlowParams użyj ProductDetailsParams.
  • Szczegóły ofert, takie jak identyfikator oferty, identyfikator abonamentu podstawowego i inne, można uzyskać za pomocą obiektu SubscriptionOfferDetails.

Aby kupić produkt z ofertą wybraną przez użytkownika, pobierz offerToken z wybranej oferty i przekaż ją do obiektu ProductDetailsParams.

Po utworzeniu obiektu BillingFlowParams uruchamianie procesu płatności za pomocą BillingClient pozostaje bez zmian.

Na przykładzie poniżej możesz zobaczyć, jak może wyglądać aplikacja przed wprowadzeniem tych zmian i po ich wprowadzeniu:

Przed

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...
// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync().
val billingFlowParams = BillingFlowParams.newBuilder()
                            .setSkuDetails(skuDetails)
                            .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Java

// An activity reference from which the billing flow will be launched.
Activity activity = ...;
// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync().
BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
        .setSkuDetails(skuDetails)
        .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Po

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...;

val productDetailsParamsList = listOf(
    BillingFlowParams.ProductDetailsParams.newBuilder()
        // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
        .setProductDetails(productDetails)
        // For One-time product, "setOfferToken" method shouldn't be called.
        // For subscriptions, to get the offer token corresponding to the selected
        // offer call productDetails.subscriptionOfferDetails?.get(selectedOfferIndex)?.offerToken
        .setOfferToken(selectedOfferToken)
        .build()
)

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .build()

// Launch the billing flow
val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Java

// An activity reference from which the billing flow will be launched.
Activity activity = ...;

ImmutableList<ProductDetailsParams> productDetailsParamsList =
    ImmutableList.of(
        ProductDetailsParams.newBuilder()
             // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
            .setProductDetails(productDetails)
            // For one-time products, "setOfferToken" method shouldn't be called.
            // For subscriptions, to get the offer token corresponding to the selected
            // offer call productDetails.getSubscriptionOfferDetails().get(selectedOfferIndex).getOfferToken()
            .setOfferToken(selectedOfferToken)
            .build()
    );

BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .build();

// Launch the billing flow
BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

Przetwarzanie zakupów

Przetwarzanie zakupów w Bibliotece płatności w Google Play 6 działa podobnie jak w poprzednich wersjach.

Aby pobrać wszystkie aktywne zakupy należące do użytkownika i zapytać o nowe zakupy:

  • Zamiast przekazywać wartość BillingClient.SkuType do queryPurchasesAsync(), przekaż obiekt QueryPurchasesParams, który zawiera wartość BillingClient.ProductType.

Z przykładu poniżej możesz zobaczyć, jak aplikacja może wyglądać przed wprowadzeniem tych zmian i po ich wprowadzeniu:

Przed

Kotlin

billingClient.queryPurchasesAsync(BillingClient.SkuType.SUBS) {
    billingResult,
    purchaseList -> {
        // Process the result
    }
}

Java


billingClient.queryPurchasesAsync(
    BillingClient.SkuType.SUBS,
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                List<Purchase> purchases) {
            // process the result
        }
    }
);

Po

Kotlin

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder()
        .setProductType(BillingClient.ProductType.SUBS)
        .build()
) { billingResult, purchaseList ->
    // Process the result
}

Java

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder().setProductType(ProductType.SUBS).build(),
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                List<Purchase> purchases) {
            // Process the result
        }
    }
);

Czynności, które musisz wykonać, aby zarządzać zakupami poza aplikacją i transakcjami oczekującymi na zatwierdzenie, nie uległy zmianie.

Zarządzanie stanem zakupu subskrypcji za pomocą nowego interfejsu API w backendzie

Aby móc obsługiwać zakupy nowych usług utworzonych w poprzednich krokach, musisz przenieść w backendzie komponent zarządzania stanem zakupu subskrypcji. Twój obecny komponent do zarządzania stanem zakupu subskrypcji powinien działać normalnie w przypadku przekonwertowanych usług subskrypcji zdefiniowanych przed majem 2022 r. powinien Ci wystarczać do zarządzania zakupami zgodnych wstecznie ofert, ale nie obsługuje żadnej z nowych funkcji.

Musisz wdrożyć na potrzeby modułu zarządzania stanem zakupu subskrypcji nowy interfejs Subscription Purchases API, który służy do sprawdzania stanu zakupu i zarządzania uprawnieniami dotyczącymi subskrypcji w Płatnościach w Play w naszym backendzie. Stara wersja interfejsu API nie zawiera wszystkich informacji niezbędnych do zarządzania zakupami na nowej platformie. Szczegółowe informacje o zmianach w porównaniu z poprzednimi wersjami znajdziesz w przewodniku po nowych funkcjach subskrypcji z maja 2022 roku.

Zwykle wywołujesz interfejs Subscription Purchases API za każdym razem, gdy otrzymujesz powiadomienie dla deweloperów SubscriptionNotification w czasie rzeczywistym, aby pobrać najnowsze informacje o stanie subskrypcji. Musisz zastąpić wywołania purchases.subscriptions.get nową wersją interfejsu Subscription Purchases API (purchases.subscriptionsv2.get). Dostępny jest nowy zasób o nazwie SubscriptionPurchaseV2, który zawiera wystarczającą ilość informacji do zarządzania uprawnieniami do zakupu subskrypcji w nowym modelu.

Ten nowy punkt końcowy zwraca stan wszystkich subskrypcji i zakupów niezależnie od wersji aplikacji, w której zostały one sprzedane, oraz daty zdefiniowania produktu (przed wydaniem wersji z maja 2022 r. lub później). Po migracji będzie Ci więc potrzebna tylko ta wersja modułu zarządzania stanem zakupu subskrypcji.

Zmienianie zakupów subskrypcji użytkownika

W Bibliotece płatności w Play w wersji 5 i starszych usługa ProrationMode służyła do wprowadzania zmian w zakupach subskrypcji przez użytkowników, takich jak przejście na wyższą lub niższą wersję usługi. Ta funkcja została wycofana i zastąpiona w wersji 6 kodem ReplacementMode.

Obsługa zmian cen subskrypcji

Wycofany wcześniej interfejs launchPriceConfirmationFlow API został usunięty z Biblioteki płatności w Play 6. Inne opcje znajdziesz w przewodniku po zmianach cen.

Naprawianie błędów Biblioteki płatności w Play

W Bibliotece płatności w Play 6 dodaliśmy nowy kod NETWORK_ERROR, który wskazuje problemy z połączeniem sieciowym między urządzeniem użytkownika a systemem Google Play. Zmianie uległy też kody SERVICE_TIMEOUT i SERVICE_UNAVAILABLE. Więcej informacji znajdziesz w sekcji Obsługa kodów odpowiedzi BillingResult.

Obsługa oczekujących transakcji

Od wersji 6.0.0 Biblioteka płatności w Play nie tworzy identyfikatorów zamówień w przypadku oczekujących zakupów. W przypadku takich zakupów identyfikator zamówienia jest wypełniany po przeniesieniu zakupu do stanu PURCHASED. Dopilnuj, aby integracja wymagała identyfikatora zamówienia dopiero po zakończeniu transakcji. Nadal możesz używać tokena zakupu w swoich rekordach. Więcej informacji o obsłudze oczekujących zakupów znajdziesz w przewodniku po integracji Biblioteki płatności w Play i w przewodniku po zarządzaniu cyklem życia zakupów.