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

Ten dokument opisuje, jak przejść z Biblioteki płatności w Google Play w wersji 4 lub 5 na Bibliotekę płatności w Google Play w wersji 6 oraz jak korzystać z nowych funkcji 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 bazuje na nowych funkcjach subskrypcji wprowadzonych w wersji 5 i dodaje kilka ulepszeń. Dzięki tym funkcjom możesz sprzedawać subskrypcje na więcej sposobów, co pozwala obniżyć koszty operacyjne, ponieważ nie musisz tworzyć coraz większej liczby kodów SKU i nimi zarządzać.

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

Uaktualnienie Biblioteki płatności w Play zgodne wstecznie

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

Poprzednie wersje aplikacji nadal działają

Jeśli masz katalog subskrypcji zgodny wstecznie, wszystkie dotychczasowe wersje aplikacji powinny nadal działać zgodnie z oczekiwaniami w przypadku tych produktów. Zakupy produktów kupowanych raz również powinny działać bez problemów w poprzednich wersjach.

Wersje aplikacji, które używają 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 w odpowiednim artykule w Centrum pomocy Konsoli Play.

Przejście na Bibliotekę płatności w Play w wersji 5 lub 6

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

Pierwszym krokiem migracji może być po prostu zaktualizowanie wersji biblioteki, pozostawienie katalogu i backendu bez zmian oraz przetestowanie aplikacji, gdy nadal używa ona wycofanych metod. Jeśli nie używasz queryPurchases, launchPriceChangeFlow ani setVrPurchaseFlow, wszystko powinno działać zgodnie z oczekiwaniami. Następnie możesz stopniowo wdrażać nowe funkcje subskrypcji opublikowane w maju 2022 r.

Jeśli te funkcje zostały już przez Ciebie wdrożone podczas migracji do Biblioteki płatności w Google Play w wersji 5, możesz przejść bezpośrednio do sekcji Aktualizowanie Biblioteki płatności w Google Play i Zmienianie zakupów subskrypcji użytkownika. Jeśli zaczynasz od wcześniejszej wersji lub nie korzystasz jeszcze w pełni z nowych funkcji, możesz przeczytać pełne instrukcje migracji, aby dowiedzieć się, jak je wdrożyć.

Kroki pełnej migracji

Tworzenie nowych subskrypcji w katalogu produktów w backendzie

Za pomocą Konsoli Play lub interfejsu Play Developer API możesz teraz skonfigurować jedną subskrypcję z wieloma abonamentami podstawowymi, z których każdy może zawierać wiele ofert. Oferty subskrypcji mają elastyczne modele cenowe i kryteria kwalifikacji. Oferty możesz tworzyć w całym cyklu życia subskrypcji, korzystając z różnych abonamentów przedpłaconych i odnawianych automatycznie.

Przed przeniesieniem aplikacji zalecamy utworzenie nowych produktów zgodnie ze strukturą encji na nowej platformie subskrypcji na potrzeby integracji z Biblioteką płatności w Play. Możesz skonsolidować produkty zduplikowane w starym katalogu, które reprezentują te same korzyści, w ramach jednej subskrypcji i użyć konfiguracji abonamentu podstawowego i oferty, aby przedstawić wszystkie opcje, które chcesz oferować. Więcej informacji o tej rekomendacji znajdziesz w sekcji Praca ze starszymi subskrypcjami w tym artykule pomocy w Centrum pomocy Konsoli Play.

Po wydaniu wersji z maja 2022 r. nie zmieniaj przekonwertowanych produktów objętych subskrypcją, aby wersje aplikacji korzystające z wycofanych metod (takich jak querySkuDetailsAsync()) mogły nadal je sprzedawać bez wpływu na te kompilacje.

W ramach procesu konwersji produkty objęte subskrypcją, które znajdowały się w Twoim katalogu przed majem 2022 r., zostały oznaczone jako tylko do odczytu, aby uniknąć przypadkowych zmian, które mogłyby spowodować problemy z dotychczasową integracją. Możesz wprowadzić zmiany w tych subskrypcjach, ale może to mieć wpływ na integracje frontendu i backendu:

  • W interfejsie użytkownika wersje aplikacji, które używają querySkuDetailsAsync() do uzyskiwania szczegółów produktu objętego subskrypcją, mogą sprzedawać tylko zgodne wstecznie abonamenty podstawowe i oferty. Może istnieć tylko 1 kombinacja zgodnego wstecznie abonamentu podstawowego i oferty, więc jeśli dodasz nowe abonamenty lub oferty do przekonwertowanych subskrypcji, nowe dodatkowe abonamenty podstawowe lub oferty nie będą mogły być sprzedawane w tych poprzednich wersjach aplikacji.

  • Jeśli w interfejsie Konsoli Play zmodyfikujesz przekonwertowane subskrypcje, nie będziesz mieć możliwości zarządzania nimi za pomocą punktu końcowego inappproducts, jeśli wywołasz go 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 zakupów abonamentów podstawowych i ofert zgodnych wstecznie. Więcej informacji znajdziesz w sekcji Zarządzanie stanem zakupu subskrypcji.

Zarządzanie katalogiem subskrypcji backendu za pomocą nowego interfejsu API

Jeśli automatycznie zarządzasz katalogiem produktów objętych subskrypcją za pomocą interfejsu Google Play Developer API, musisz używać nowych punktów końcowych definicji produktów objętych subskrypcją, aby tworzyć subskrypcje, abonamenty podstawowe i oferty oraz nimi zarządzać. Aby dowiedzieć się więcej o zmianach w interfejsie API katalogu produktów w tej wersji, przeczytaj przewodnik po funkcjach subskrypcji z maja 2022 r.

Aby przenieść moduł automatycznego zarządzania katalogiem produktów w przypadku subskrypcji w Płatnościach w Google Play, zastąp interfejs API inappproducts nowym interfejsem Subscription Publishing API, który umożliwia zarządzanie katalogiem subskrypcji i jego publikowanie. Dostępne są 3 nowe punkty końcowe:

Te nowe punkty końcowe mają wszystkie funkcje niezbędne do wykorzystania wszystkich nowych możliwości w katalogu: tagów abonamentu podstawowego i oferty, kierowania regionalnego, abonamentów przedpłaconych i innych.

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

Wersje aplikacji, które używają 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 w tym artykule pomocy w Centrum pomocy Konsoli Play.

Aktualizowanie Biblioteki płatności w Google Play

Po utworzeniu nowego katalogu produktów objętych subskrypcją możesz przenieść aplikację do Biblioteki płatności Google 5. Zastąp dotychczasową zależność Biblioteki płatności w Play zaktualizowaną wersją w pliku build.gradle aplikacji.

dependencies {
    def billingVersion = "6.0.0"

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

Projekt powinien od razu się skompilować, nawet jeśli nie zmodyfikujesz żadnych wywołań metod – Biblioteka płatności w Play 6 jest zgodna wstecznie. Koncepcja SKU jest uważana za przestarzałą, ale nadal jest obecna, aby ułatwić i przyspieszyć przenoszenie aplikacji.

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

Pierwsze kroki do uruchomienia zakupów z aplikacji na Androida pozostają takie same:

Wyświetlanie produktów dostępnych do kupienia

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

  • Zastąp SkuDetailsParams elementem QueryProductDetailsParams
  • Przełącz połączenie BillingClient.querySkuDetailsAsync() na BillingClient.queryProductDetailsAsync()

Zauważ, że wyniki zapytania to teraz ProductDetails zamiast SkuDetails. Każdy element ProductDetails zawiera informacje o produkcie (identyfikator, tytuł, typ itd.). W przypadku produktów objętych subskrypcją ProductDetails zawiera List<ProductDetails.SubscriptionOfferDetails>, czyli listę szczegółów oferty subskrypcji. W przypadku produktów jednorazowego zakupu ProductDetails zawiera ProductDetails.OneTimePurchaseOfferDetails. Można ich używać do decydowania, które oferty wyświetlać użytkownikom.

Poniższy przykład pokazuje, 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 produkty objęte subskrypcją zawierają teraz również 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 przekształca każdy kod SKU subskrypcji w 1 zgodny wstecznie abonament podstawowy i ofertę. Dostępne produkty jednorazowego zakupu są też przenoszone do obiektu ProductDetails. Szczegóły oferty produktu kupowanego raz można uzyskać za pomocą metody getOneTimePurchaseOfferDetails().

W rzadkich przypadkach niektóre urządzenia nie obsługują aplikacji ProductDetails i queryProductDetailsAsync(), zwykle z powodu nieaktualnych wersji Usług Google Play. Aby zapewnić prawidłową obsługę tego scenariusza, przed wywołaniem queryProductDetailsAsync wywołaj isFeatureSupported() dla funkcji PRODUCT_DETAILS. Jeśli odpowiedź to OK, urządzenie obsługuje tę funkcję i możesz wywołać metodę queryProductDetailsAsync(). Jeśli odpowiedź to FEATURE_NOT_SUPPORTED, możesz zamiast tego poprosić o listę dostępnych produktów zgodnych wstecznie za pomocą querySkuDetailsAsync(). Więcej informacji o korzystaniu z funkcji zgodności wstecznej znajdziesz w przewodniku po funkcjach subskrypcji z maja 2022 r.

Uruchamianie procesu zakupu oferty

Uruchamianie procesu zakupu oferty jest bardzo podobne do uruchamiania procesu zakupu SKU. Aby rozpocząć prośbę o zakup w wersji 6:

  • Zamiast SkuDetails dla BillingFlowParams użyj ProductDetailsParams.
  • Szczegóły oferty, takie jak identyfikator oferty czy identyfikator abonamentu podstawowego, można uzyskać za pomocą obiektu SubscriptionOfferDetails.

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

Po utworzeniu obiektu BillingFlowParams uruchomienie procesu płatności za pomocą BillingClient pozostaje takie samo.

Z poniższego przykładu dowiesz się, 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 za pomocą Biblioteki płatności w Google Play 6 jest podobne do poprzednich wersji.

Aby pobrać wszystkie aktywne zakupy należące do użytkownika i wysłać zapytanie o nowe zakupy:

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

Poniższy przykład pokazuje, jak może wyglądać aplikacja 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
        }
    }
);

Sposób zarządzania zakupami poza aplikacją i oczekującymi transakcjami nie uległ zmianie.

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

Aby móc obsługiwać zakupy nowych produktów utworzonych w poprzednich krokach, musisz przenieść komponent zarządzania stanem zakupu subskrypcji w backendzie. Twój obecny komponent zarządzania stanem zakupu subskrypcji powinien działać jak zwykle w przypadku przekonwertowanych produktów objętych subskrypcją, które zostały zdefiniowane przed wprowadzeniem zmian w maju 2022 r. Powinien też wystarczyć do zarządzania zakupami ofert zgodnych wstecznie, ale nie obsługuje żadnych nowych funkcji.

Musisz wdrożyć nowy interfejs Subscription Purchases API w module zarządzania stanem zakupów subskrypcji, który sprawdza stan zakupu i zarządza uprawnieniami do subskrypcji w Płatnościach w Play w Twoim backendzie. Stara wersja interfejsu API nie zwraca wszystkich szczegółów 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.

Podczas migracji modułu zarządzania stanem zakupów:

Ten nowy punkt końcowy zwraca stan wszystkich produktów objętych subskrypcją i wszystkich zakupów, niezależnie od wersji aplikacji, w której zostały sprzedane, i momentu zdefiniowania produktu (przed majem 2022 r. czy po tej dacie). Po migracji będziesz więc potrzebować tylko tej wersji modułu zarządzania stanem zakupów subskrypcji.

Zmienianie zakupów subskrypcji użytkownika

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

Obsługa zmian cen subskrypcji

Wycofany wcześniej interfejs API launchPriceConfirmationFlow został usunięty w Bibliotece płatności w Play 6. Alternatywne rozwiązania znajdziesz w przewodniku po zmianach cen.

Obsługa 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. Zmieniono też kody SERVICE_TIMEOUT i SERVICE_UNAVAILABLE. Więcej informacji znajdziesz w artykule o obsłudze kodów odpowiedzi BillingResult.

Obsługa oczekujących transakcji

Począwszy od wersji 6.0.0, Biblioteka płatności w Play nie tworzy identyfikatora zamówienia w przypadku oczekujących zakupów. W przypadku tych zakupów identyfikator zamówienia jest wypełniany po przeniesieniu zakupu do stanu PURCHASED. Upewnij się, że integracja oczekuje identyfikatora zamówienia dopiero po zakończeniu transakcji. Nadal możesz używać tokena zakupu do celów ewidencyjnych. Więcej informacji o obsłudze oczekujących zakupów znajdziesz w przewodniku po integracji z Biblioteką płatności w Play i w przewodniku po zarządzaniu cyklem życia zakupów.