Przechodzenie z wersji 7 lub 8 na Bibliotekę płatności w Google Play w wersji 9

Z tego dokumentu dowiesz się, jak przeprowadzić migrację z Biblioteki płatności w Google Play (PBL) w wersji 7 lub 8 do wersji 9 oraz jak zintegrować ją z nowymi funkcjami.

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

Przegląd

PBL 9 zawiera ulepszenia istniejących interfejsów API oraz usunięcie wcześniej wycofanych interfejsów API. Ta wersja biblioteki wprowadza też bogatszy kontekst błędów dzięki nowym kodom podrzędnych odpowiedzi.

Zgodność wsteczna w przypadku uaktualnienia PBL

Aby przeprowadzić migrację do PBL 9, musisz zaktualizować lub usunąć niektóre z dotychczasowych odwołań do interfejsu API w aplikacji, zgodnie z opisem w informacjach o wersji i w dalszej części tego przewodnika migracji.

Uaktualnianie z PBL 7 lub 8 do PBL 9

Aby uaktualnić PBL 7 lub 8 do PBL 9:

  1. Zaktualizuj wersję zależności Biblioteki płatności w Play w pliku build.gradle aplikacji.

    dependencies {
  def billing_version = "9.1.0"
  implementation "com.android.billingclient:billing:$billing_version"
}

    Jeśli używasz języka Kotlin, moduł KTX Biblioteki płatności w Google Play zawiera rozszerzenia Kotlin i obsługę współprogramów, które umożliwiają pisanie idiomatycznego kodu Kotlin podczas korzystania z Biblioteki płatności w Google Play. Aby uwzględnić te rozszerzenia w projekcie, dodaj tę zależność do pliku build.gradle aplikacji:

    dependencies {
  val billing_version = "9.1.0"
  implementation("com.android.billingclient:billing-ktx:$billing_version")
}

  2. (Dotyczy tylko uaktualnienia z PBL 7 do PBL 9). Zaktualizuj implementację metody queryProductDetailsAsync.

    Zmieniła się sygnatura metody ProductDetailsResponseListener.onProductDetailsResponse, co wymaga zmian w aplikacji w przypadku implementacji queryProductDetailsAsync. Więcej informacji znajdziesz w artykule Wyświetlanie produktów dostępnych do kupienia.

  3. Obsłuż usunięte interfejsy API.

    W tabeli poniżej znajdziesz listę usuniętych interfejsów API oraz odpowiadających im alternatywnych interfejsów API, których musisz używać w aplikacji.

    Uaktualnianie z

    PBL 9 nie obsługuje już interfejsów API wymienionych w tabeli poniżej. Jeśli Twoja implementacja używa któregoś z tych usuniętych interfejsów API, w tabeli znajdziesz odpowiadające im alternatywne interfejsy API.

    Usunięto wcześniej wycofany interfejs API Alternatywny interfejs API
    Interfejsy API queryPurchaseHistoryAsync Zobacz sekcję Sprawdzanie historii zakupów. Jeśli używasz queryPurchaseHistoryAsync do określania, czy użytkownik kwalifikuje się do bezpłatnego okresu próbnego, teraz musisz używać ProductDetails.getSubscriptionOfferDetails(), aby określić, do których ofert kwalifikuje się użytkownik.
    BillingClient.SkuType BillingClient.ProductType. Stałe typu produktu INAPP i SUBS pozostają funkcjonalnie podobne do wycofanych stałych typu SKU.
    SkuDetails ProductDetails. To nowy model danych, który obsługuje produkty kupowane raz.
    SkuDetailsParams Użyj QueryProductDetailsParams z queryProductDetailsAsync.
    SkuDetailsResponseListener Użyj ProductDetailsResponseListener z queryProductDetailsAsync.
    QueryPurchaseHistoryParams
    • W przypadku aktywnych lub oczekujących zakupów użyj queryPurchasesAsync.
    • Śledź wykorzystane zakupy na serwerach backendu.
    • W przypadku anulowanych lub unieważnionych zakupów użyj interfejsu Voided Purchases API po stronie serwera.
    getSkuDetailsList i setSkuDetailsList Użyj BillingFlowParams.Builder.setProductDetailsParamsList.
    querySkuDetailsAsync queryProductDetailsAsync
    enablePendingPurchases() (interfejs API bez parametrów) enablePendingPurchases(PendingPurchasesParams params)
    Pamiętaj, że wycofana funkcja enablePendingPurchases() jest funkcjonalnie równoważna z enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()).
    queryPurchasesAsync(String skuType, PurchasesResponseListener listener) queryPurchasesAsync

    Uaktualnianie z

    W tabeli poniżej znajdziesz listę interfejsów API usuniętych w PBL 9 oraz odpowiadających im alternatywnych interfejsów API, których musisz używać w aplikacji.

    Usunięto wcześniej wycofany interfejs API Alternatywny interfejs API
    BillingClient.SkuType BillingClient.ProductType. Stałe typu produktu INAPP i SUBS pozostają funkcjonalnie podobne do wycofanych stałych typu SKU.
    SkuDetails ProductDetails. To nowy model danych, który obsługuje produkty kupowane raz.
    SkuDetailsParams Użyj QueryProductDetailsParams z queryProductDetailsAsync.
    SkuDetailsResponseListener Użyj ProductDetailsResponseListener z queryProductDetailsAsync.
    QueryPurchaseHistoryParams
    • W przypadku aktywnych lub oczekujących zakupów użyj queryProductDetailsAsync.
    • Śledź wykorzystane zakupy na serwerach backendu.
    • W przypadku anulowanych lub unieważnionych zakupów użyj interfejsu Voided Purchases API po stronie serwera.
    getSkuDetailsList i setSkuDetailsList Użyj BillingFlowParams.Builder.setProductDetailsParamsList.

  4. (Zalecane) Włącz automatyczne ponowne łączenie z usługą.

    Biblioteka płatności w Play może automatycznie próbować ponownie nawiązać połączenie z usługą, jeśli wywołanie interfejsu API zostanie wykonane, gdy usługa jest odłączona. Więcej informacji znajdziesz w artykule Włączanie automatycznego ponownego łączenia z usługą.

  5. Obsłuż nowe kody podrzędnych odpowiedzi.

    Obiekt BillingResult zwracany przez launchBillingFlow() będzie teraz zawierać pole kodu podrzędnej odpowiedzi. To pole będzie wypełniane tylko w niektórych przypadkach, aby podać bardziej szczegółowy powód niepowodzenia. Pole podrzędnej odpowiedzi może mieć te wartości:

    • PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS – zwracana, gdy środki użytkownika są mniejsze niż cena produktu, który próbuje kupić.
    • USER_INELIGIBLE – zwracana, gdy użytkownik nie spełnia skonfigurowanych wymagań kwalifikacyjnych dotyczących oferty subskrypcji.
    • NO_APPLICABLE_SUB_RESPONSE_CODE – wartość domyślna zwracana, gdy nie ma innego odpowiedniego kodu podrzędnej odpowiedzi.

    Krok migracji: zaktualizuj PurchasesUpdatedListener lub równoważną obsługę wyników, aby rozpoznawać te konkretne kody podrzędnych odpowiedzi i na nie reagować, co pozwoli zapewnić lepszą obsługę. Możesz na przykład wyświetlić prośbę o naprawienie form płatności lub wyświetlić konkretny komunikat o błędzie.

  6. Informacje o ponownej klasyfikacji kodów błędów.

    W przypadkach, gdy aplikacja Sklep Play jest blokowana przez system (np. w trybie dla dzieci dostosowanym przez producenta OEM), kod odpowiedzi z PBL zmienił się z ERROR na BILLING_UNAVAILABLE.

    Krok migracji: upewnij się, że logika obsługi błędów uwzględnia tę zmianę i w tych konkretnych scenariuszach nie polega na otrzymywaniu ogólnego błędu.

  7. Obsłuż dopuszczalność wartości null w przypadku DeveloperProvidedBillingDetails.getLinkUri().

    Jeśli używasz DeveloperProvidedBillingDetails w ramach integracji płatności zewnętrznych, getLinkUri() jest teraz @Nullable.

    Krok migracji: aby bezpiecznie obsłużyć tę zmianę, przed przeanalizowaniem lub uruchomieniem intencji przeglądarki upewnij się, że kod integracji obsługuje zarówno wartości null, jak i puste ciągi ("") z metody DeveloperProvidedBillingDetails.getLinkUri(). Przykład:

    Kotlin

    Java

    String linkUri = details.getLinkUri();
if (!android.text.TextUtils.isEmpty(linkUri)) {
  Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(linkUri));
  context.startActivity(intent);
}

  8. Opcjonalne zmiany.