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

Z tego dokumentu dowiesz się, jak przejść z Biblioteki płatności w Google Play (PBL) w wersji 7 lub 8 na wersję 9 oraz jak zintegrować nowe funkcje.

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 usuwa wcześniej wycofane interfejsy API. Ta wersja biblioteki wprowadza też bogatszy kontekst błędów dzięki nowym kodom pododpowiedzi.

Zgodność wsteczna na potrzeby uaktualnienia PBL

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

Przejście z PBL 7 lub 8 na PBL 9

Aby przejść z PBL 7 lub 8 na PBL 9, wykonaj te czynności:

  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 Kotlina, moduł KTX Biblioteki płatności w Google Play zawiera rozszerzenia Kotlina i obsługę współprogramów, które umożliwiają pisanie idiomatycznego kodu Kotlina podczas korzystania z Biblioteki płatności w Google Play. Aby uwzględnić te rozszerzenia w projekcie, dodaj do pliku build.gradle aplikacji tę zależność:

    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 wprowadzenia zmian w aplikacji w celu implementacji queryProductDetailsAsync. Więcej informacji znajdziesz w artykule Wyświetlanie dostępności produktów do kupienia.

  3. Obsługa usuniętych interfejsów API.

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

    Przejdź na wyższą wersję

    PBL 9 nie obsługuje już interfejsów API wymienionych w tabeli poniżej. Jeśli Twoja implementacja korzysta z któregoś z tych usuniętych interfejsów API, zapoznaj się z tabelą, aby znaleźć odpowiednie alternatywne interfejsy API.

    Usunięcie wycofanego wcześniej interfejsu API Alternatywny interfejs API do użycia
    interfejsy API queryPurchaseHistoryAsync Zobacz Zapytanie o historię zakupów. Jeśli do określania, czy użytkownik kwalifikuje się do bezpłatnych okresów próbnych, używasz metody queryPurchaseHistoryAsync, teraz musisz używać metody 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
    • Używaj metody queryPurchasesAsync w przypadku aktywnych lub oczekujących zakupów.
    • Śledź wykorzystane zakupy na serwerach backendu.
    • W przypadku anulowanych lub unieważnionych zakupów używaj 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 metoda enablePendingPurchases() jest funkcjonalnie równoważna metodzie enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()).
    queryPurchasesAsync(String skuType, PurchasesResponseListener listener) queryPurchasesAsync

    Przejdź na wyższą wersję

    W tabeli poniżej znajdziesz interfejsy API, które zostały usunięte w PBL 9, oraz odpowiadające im alternatywne interfejsy API, których musisz używać w aplikacji.

    Usunięcie wycofanego wcześniej interfejsu API Alternatywny interfejs API do użycia
    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żywaj metody queryProductDetailsAsync.
    • Śledź wykorzystane zakupy na serwerach backendu.
    • W przypadku anulowanych lub unieważnionych zakupów używaj 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 spróbować automatycznie 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 o włączaniu automatycznego ponownego łączenia z usługą.

  5. Obsługa nowych kodów pododpowiedzi.

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

    • PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS – zwracany, gdy środki użytkownika są mniejsze niż cena produktu, który próbuje kupić.
    • USER_INELIGIBLE – zwracany, gdy użytkownik nie spełnia skonfigurowanych wymagań dotyczących oferty subskrypcji.
    • NO_APPLICABLE_SUB_RESPONSE_CODE – wartość domyślna zwracana, gdy nie ma zastosowania żaden inny kod pododpowiedzi.

    Krok migracji: zaktualizuj obsługę wyników PurchasesUpdatedListener lub równoważnych, aby rozpoznawać te konkretne kody pododpowiedzi i reagować na nie, co pozwoli zapewnić użytkownikom lepsze wrażenia. Może to być na przykład prośba o poprawienie form płatności lub konkretny komunikat o błędzie.

  6. świadomość zmiany klasyfikacji kodów błędów.

    W przypadkach, gdy aplikacja Sklep Play jest blokowana przez system (np. w trybie dziecięcym dostosowanym przez 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 nie polega na otrzymywaniu ogólnego błędu w tych konkretnych scenariuszach.

  7. Obsługuj wartości null w DeveloperProvidedBillingDetails.getLinkUri().

    Jeśli używasz DeveloperProvidedBillingDetails w ramach integracji z płatnościami zewnętrznymi, getLinkUri() to teraz @Nullable.

    Krok migracji: aby bezpiecznie obsłużyć tę zmianę, upewnij się, że kod integracji obsługuje zarówno wartości null, jak i puste ciągi znaków ("") z metody DeveloperProvidedBillingDetails.getLinkUri() przed analizą lub uruchomieniem intencji przeglądarki. 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. Zmiany opcjonalne.