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 w wersji 4 lub 5 do Biblioteka płatności w Google Play 6 oraz korzystanie z nowych funkcji związanych z subskrypcjami.

Pełną listę zmian wprowadzonych w wersji 6.0.0 znajdziesz w wersji notatki.

Omówienie

Biblioteka płatności w Google Play 6 uzupełnia nowe funkcje subskrypcji w wersji 5 i zawiera kilka innych ulepszeń. Te funkcje umożliwiają sprzedaż subskrypcji na więcej sposobów, zmniejszając koszty operacyjne, eliminując potrzebę aby tworzyć coraz więcej kodów SKU i nimi zarządzać.

Dowiedz się więcej o nowych funkcjach wprowadzonych w Bibliotece płatności w Play 5. Najnowsze zmiany w subskrypcjach w Google Play Konsola.

Uaktualnienie Biblioteki płatności w Play o niezgodności wstecznej

Wszystkie istniejące produkty objęte subskrypcją zostały automatycznie przekonwertowane na nowy format są częścią modelu, w ramach którego w maju 2022 r. udostępniliśmy Bibliotekę płatności w Play 5 platformie subskrypcji. Oznacza to, że nie musisz korzystać z żadnej subskrypcji. konfiguracji usługi, aby uzyskać katalog zgodny z nową wersją Biblioteki płatności w Play. Więcej informacji o subskrypcji Kody SKU zostały przekonwertowane na subskrypcje zgodne wstecznie. Zobacz Działające ze starszymi subskrypcjami w Centrum pomocy Konsoli Play. artykule.

Starsze wersje aplikacji nadal działają

Jeśli masz katalog subskrypcji zgodny wstecznie, wszystkie istniejące wersje powinna nadal działać w tych usługach zgodnie z oczekiwaniami. Produkt kupowany raz w starszych wersjach systemu powinny działać bez problemów.

Wersje Twojej aplikacji korzystające z wycofanych metod (np. querySkuDetailsAsync()) nie będzie mieć możliwości sprzedaży abonamentów podstawowych ani ofert, które nie są wsteczne są zgodne. Informacje o ofertach zgodnych wstecznie znajdziesz w odpowiednim Google Play Centrum pomocy konsoli .

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

Biblioteka płatności w Play 5 i 6 obejmuje wycofane metody querySkuDetailsAsync i BillingFlowParams.Builder.setSkuDetails, do których zajdzie SkuDetails jako rozliczenia przepływu. Oznacza to, że możesz stopniowo przechodzić na Bibliotekę płatności w Play 6 planując różne etapy migracji.

Pierwszym krokiem do migracji może być zaktualizowanie biblioteki , pozostaw katalog i backend bez zmian, a następnie przetestuj w czasie, gdy nadal używa ona wycofanych metod. Jeśli nie używasz queryPurchases, launchPriceChangeFlow lub setVrPurchaseFlow, powinna które nadal działają zgodnie z oczekiwaniami. Następnie można dokonać iteracji, by w pełni zastosować nową funkcji subskrypcji udostępnionych w maju 2022 r.

Jeśli korzystasz już z tych funkcji w Bibliotece płatności w Google Play 5, możesz przejść bezpośrednio do sekcji Aktualizowanie Google Biblioteka płatności w Play i zmienianie subskrypcji użytkownika zakupów. Jeśli rozpoczynasz korzystanie z wcześniejszej wersji lub nie korzystają jeszcze z nowych funkcji, zapoznaj się z pełną treścią migracji czynności opisane poniżej, aby dowiedzieć się, jak je wdrożyć.

Pełne kroki migracji

Utwórz nowe subskrypcje w katalogu produktów backendu

Korzystając z Konsoli Play lub interfejsu Play Developer API, możesz teraz skonfigurować 1 subskrypcję z wieloma abonamentami podstawowymi, z których każdy ma wiele oferty. Oferty subskrypcji mają elastyczne modele cenowe i opcje kwalifikacji. Możesz tworzyć oferty dotyczące cyklu życia subskrypcji za pomocą różnych z automatycznym odnawianiem i abonamentem przedpłaconym.

Zalecamy tworzenie nowych usług zgodnie ze strukturą encji w nowej platformy subskrypcji na potrzeby integracji Biblioteki płatności w Play 6 przed migracji aplikacji. Możesz skonsolidować duplikaty produktów w starym katalogu reprezentują te same korzyści w ramach jednej subskrypcji abonament podstawowy i konfiguracje ofert, aby uwzględnić wszystkie wybrane opcje co chcemy zaoferować. Więcej informacji o tej rekomendacji znajdziesz w artykule Praca z w sekcji dotyczącej starszych subskrypcji w Centrum pomocy Konsoli Play. artykule.

Nie zalecamy modyfikowania przekonwertowanych produktów objętych subskrypcją po Wersja z maja 2022 r.; pozostawiaj je w postaci, w jakiej są sprzedawane z wersjami aplikację za pomocą wycofanych metod (np. querySkuDetailsAsync()) bez wprowadzania zmian, które co może mieć wpływ na starsze kompilacje.

Proces konwersji sprawił, że w ramach subskrypcji znajdowały się produkty z Twojego katalogu do maja 2022 r. tylko do odczytu, aby uniknąć przypadkowych zmian, które mogłyby spowodować w przypadku istniejących problemów z integracją. Wprowadzenie zmian w tych subskrypcjach jest ale może to mieć wpływ na frontend oraz integracje backendowe:

  • We frontendzie wersje aplikacji korzystające z metody querySkuDetailsAsync() w celu uzyskania szczegóły produktu objętego subskrypcją mogą sprzedawać tylko zgodne wstecznie abonamenty podstawowe i oferty. Może być tylko 1 zgodny wstecznie abonament podstawowy i oferta więc jeśli dodasz do przekonwertowanych subskrypcji nowe abonamenty lub oferty, w przypadku starszych abonamentów nie będzie można sprzedawać nowych dodatkowych abonamentów podstawowych ani ofert. wersji Twojej aplikacji.

  • Jeśli w backendzie edytujesz przekonwertowane subskrypcje w interfejsu Konsoli Play; nie będzie można nimi zarządzać na koncie inappproducts. punktu końcowego, jeśli w tym celu wywołujesz punkt końcowy. Wykonaj też przejdź do nowego punktu końcowego stanu zakupu subskrypcji (purchases.subscriptionsv2.get), aby zarządzać zakupami dla tych subskrypcji, 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 zakupów. Przeczytaj artykuł 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ą Google Play Developer API, musisz używać nowej usługi subskrypcyjnej punktów końcowych definicji do tworzenia subskrypcji, abonamentów podstawowych i ofert oraz zarządzania nimi. Przeczytaj funkcje subskrypcji wprowadzone w maju 2022 r. przewodnik , by dowiedzieć się więcej o zmianach w interfejsie API katalogu produktów w tej wersji.

Migrację modułu automatycznego zarządzania katalogiem produktów Subskrypcje w Płatnościach w Google Play zastępują inappproducts Interfejs API z nowym interfejsem Subscription Publishing API do zarządzania i publikowania do katalogu subskrypcji. Dostępne są 3 nowe punkty końcowe:

Te nowe punkty końcowe mają wszystkie funkcje niezbędne do korzystania ze wszystkich nowe funkcje w Twoim katalogu: tagi abonamentu podstawowego i oferty, kierowanie na region, abonamenty przedpłacone.

Mimo to należy używać parametru inappproducts Interfejs API do zarządzania katalogiem produktów w aplikacji w przypadku produktów kupowanych raz.

Wersje aplikacji korzystające z wycofanych metod (np. querySkuDetailsAsync()) nie będzie można sprzedawać w ramach abonamentów podstawowych ani ofert, które nie są zgodne wstecznie. Informacje o ofertach zgodnych wstecznie znajdziesz tutaj.

Zaktualizuj Bibliotekę płatności w Google Play

Gdy utworzysz nowy katalog produktów objętych subskrypcją, możliwość przeniesienia aplikacji do Biblioteki płatności Google 5. Zastąp istniejącą Zależność Biblioteki płatności w Play w nowej wersji build.gradle z aplikacji.

dependencies {
    def billingVersion = "6.0.0"

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

Projekt powinien zostać skompilowany od razu, nawet jeśli nie zmodyfikowano żadnych wywołań funkcji metod – Biblioteka płatności w Play 6 jest zgodna wstecznie. Kod SKU to są uznawane za wycofane, ale nadal obecne w celu uproszczenia przenoszenia aplikacji proces przyrostowy.

Zainicjuj klienta rozliczeniowego i nawiąż połączenie z Google Play

Pierwsze kroki prowadzące do wprowadzenia 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 połączenie BillingClient.querySkuDetailsAsync() aby użyć: BillingClient.queryProductDetailsAsync()

Pamiętaj, ż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 List<ProductDetails.SubscriptionOfferDetails>, który jest z listą szczegółów oferty subskrypcji. W przypadku produktów zamawianych raz ProductDetails zawiera ProductDetails.OneTimePurchaseOfferDetails. Te pozwalają zdecydować, które oferty mają być wyświetlane użytkownikom.

Ten przykład pokazuje, jak aplikacja może wyglądać przed i po wprowadzenie tych zmian:

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 subskrypcja produkty zawierają teraz także atrybut List<ProductDetails.SubscriptionOfferDetails> ze wszystkimi ofertami dostępnymi dla użytkownika.

Poprzednie wersje Biblioteki płatności w Play nie obsługują nowych obiekty (subskrypcje, abonamenty podstawowe, oferty itp.), nowy system przekształca każdy kod SKU subskrypcji w jeden kod zgodny wstecznie abonament podstawowy i oferta. Dostępne produkty dostępne w ramach jednorazowego zakupu została przeniesiona do obiektu ProductDetails. Szczegóły oferty jednorazowej Kupiony produkt jest dostępny za pomocą Metoda getOneTimePurchaseOfferDetails().

Rzadko niektóre urządzenia nie obsługują funkcji ProductDetails i queryProductDetailsAsync(). zwykle z powodu nieaktualnych wersji Usługi Google Play. Aby zapewnić odpowiednie wsparcie w tym scenariuszu, zadzwoń do isFeatureSupported() dla PRODUCT_DETAILS przed wywołaniem funkcji queryProductDetailsAsync. Jeśli odpowiedź to OK urządzenie obsługuje tę funkcję i możesz zadzwonić pod numer 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 ze zgodności wstecznej można znaleźć w przewodniku po funkcjach subskrypcji w maju 2022 r.

Uruchamianie procesu zakupu oferty

Uruchamianie procesu zakupu w przypadku oferty jest bardzo podobne do uruchamiania procesu dla danego kodu SKU. Aby wysłać prośbę o zakup w wersji 6, wykonaj te czynności:

  • Zamiast używać atrybutu SkuDetails w parametrze BillingFlowParams: użyj metody ProductDetailsParams.
  • Szczegóły ofert, takie jak identyfikator oferty czy identyfikator abonamentu podstawowego, możesz uzyskać za pomocą SubscriptionOfferDetails obiektu.

Aby kupić produkt w ramach oferty wybranej przez użytkownika, pobierz offerToken wybranej oferty i przekazać ją do obiektu ProductDetailsParams.

Uruchamiam proces płatności po utworzeniu obiektu BillingFlowParams z BillingClient pozostaje bez zmian.

Ten przykład pokazuje, jak aplikacja może wyglądać przed i po wprowadzenie tych zmian:

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 przy użyciu Biblioteki płatności w Google Play 6 wygląda podobnie do poprzednich wersji.

Aby pobrać wszystkie aktywne zakupy należące do użytkownika i zapytać o nowe wykonaj te czynności:

  • Zamiast przekazywać wartość BillingClient.SkuType do queryPurchasesAsync(), przekaż obiekt QueryPurchasesParams zawierający wartość BillingClient.ProductType.
.

Poniższy przykład pokazuje, jak aplikacja może wyglądać przed po wprowadzeniu tych zmian:

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,
                ListP<urchase >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
        }
    }
);

Jak zarządzać zakupami poza aplikacją i transakcje oczekujące nie uległy zmianie.

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

Musisz przenieść komponent zarządzania stanem zakupu subskrypcji aby przygotować się do obsługi zakupów nowo utworzonych produktów. w poprzednich krokach. Zarządzanie obecnymi stanami zakupu subskrypcji powinien działać w zwykły sposób w przypadku przekonwertowanych produktów objętych subskrypcją określone przed wprowadzeniem w maju 2022 r., powinny pozwolić na zarządzanie zakupami ofert zgodnych wstecznie, ale nie obsługuje żadnych nowych funkcji.

Musisz wdrożyć nowy Subscription Purchases API na swojej moduł zarządzania stanem zakupu subskrypcji, który sprawdza zakup stanu subskrypcji w usłudze Płatności w Play i zarządzanie tymi uprawnieniami w Twoim backendzie. Stara wersja interfejsu API nie zwraca wszystkich informacji niezbędnych do zarządzania. zakupów na nowej platformie. Więcej informacji o zmianach w porównaniu z poprzednimi wersjami przeczytaj przewodnik po nowych funkcjach dotyczących subskrypcji, które zostaną wprowadzone w maju 2022 roku.

Zwykle musisz wywoływać interfejs Subscription Purchases API za każdym razem, gdy otrzymasz SubscriptionNotification Powiadomienia dla deweloperów w czasie rzeczywistym, aby pobrać najnowsze informacje o stanie subskrypcji. Musisz wymienić połączeń z numerem purchases.subscriptions.get z nową wersją interfejsu Subscription Purchases API purchases.subscriptionsv2.get. Dostępny jest nowy zasób o nazwie SubscriptionPurchaseV2 który zapewnia wystarczającą ilość informacje do zarządzania uprawnieniami do zakupu subskrypcji w nowym modelu.

Ten nowy punkt końcowy zwraca stan wszystkich produktów objętych subskrypcją oraz wszystkich Twoich zakupów niezależnie od wersji aplikacji, w której zostały sprzedane, gdy produkt został zdefiniowany (przed wprowadzeniem w maju 2022 r. lub później), więc po migracji będziesz potrzebować tylko tej wersji subskrypcji modułem zarządzania stanem zakupu.

Zmienianie subskrypcji kupionych przez użytkownika

W Bibliotece płatności w Play w wersji 5 lub starszej ProrationMode została użyta do wprowadzenia zmian w zakupach subskrypcji użytkownika, np. licencji. lub przejść na niższą wersję. Ta nazwa 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: Biblioteka płatności w Play 6. Alternatywy znajdziesz w artykule o zmianach cen .

Postępowanie w przypadku błędów w Bibliotece płatności w Play

W Bibliotece płatności w Play 6 dodaliśmy nowy kod NETWORK_ERROR, aby wskazać, problemy z połączeniem sieciowym między urządzeniem użytkownika a usługą Google, System Play. Zmieniono też kody SERVICE_TIMEOUT i SERVICE_UNAVAILABLE Więcej informacji znajdziesz w artykule Obsługa odpowiedzi BillingResult .

Obsługa oczekujących transakcji

Od wersji 6.0.0 Biblioteka płatności w Play nie tworzy zamówień Identyfikator oczekujących zakupów. W przypadku takich zakupów identyfikator zamówienia jest wypełniany po zakup jest przenoszony na PURCHASED stanu. Upewnij się, że integracja oczekuje identyfikatora zamówienia dopiero po została zrealizowana. Nadal możesz używać tokena zakupu . Więcej informacji o obsłudze oczekujących zakupów znajdziesz w Google Play Przewodnik po integracji Biblioteki płatności i przewodnika po zarządzaniu cyklem życia zakupu.