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 PBL w wersji 9 i 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 usunięcie wcześniej wycofanych interfejsów API. Ta wersja biblioteki wprowadza też bogatszy kontekst błędu dzięki nowym kodom podrzędnym odpowiedzi.

Zgodność wsteczna w przypadku uaktualnienia PBL

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

Przechodzenie 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.0.0"
  implementation "com.android.billingclient:billing:$billing_version"
}

    Jeśli używasz języka Kotlin, moduł Biblioteki płatności w Google Play KTX 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 do pliku build.gradle aplikacji tę zależność:

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

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

    Nastąpiła zmiana sygnatury metody ProductDetailsResponseListener.onProductDetailsResponse, która wymaga wprowadzenia zmian w aplikacji w celu implementacji queryProductDetailsAsync. Więcej informacji znajdziesz w artykule Wyświetlanie produktów dostępnych do kupienia.

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

    W tabeli poniżej znajdziesz listę usuniętych interfejsów API i odpowiednich 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 Twoje wdrożenie korzysta z któregoś z tych usuniętych interfejsów API, w tabeli znajdziesz odpowiednie interfejsy API, które możesz wykorzystać zamiast nich.

    Usunięto wycofany wcześniej interfejs API Alternatywny interfejs API do użycia
    Interfejsy queryPurchaseHistoryAsync API Zobacz Wyświetlanie historii zakupów. Jeśli do określania, czy użytkownik kwalifikuje się do bezpłatnego okresu próbnego, używasz funkcji queryPurchaseHistoryAsync, teraz do określania, z których ofert może skorzystać użytkownik, używaj funkcji ProductDetails.getSubscriptionOfferDetails().
    BillingClient.SkuType BillingClient.ProductType. Stałe typu produktu INAPP i SUBS działają podobnie jak wycofane stałe typu SKU.
    SkuDetails ProductDetails Jest to nowy model danych, który obsługuje produkty jednorazowe.
    SkuDetailsParams Użyj QueryProductDetailsParams z funkcją queryProductDetailsAsync.
    SkuDetailsResponseListener Używaj interfejsu ProductDetailsResponseListener z funkcją queryProductDetailsAsync.
    QueryPurchaseHistoryParams
    • Użyj funkcji 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 metody 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 funkcją enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()).
    queryPurchasesAsync(String skuType, PurchasesResponseListener listener) queryPurchasesAsync

    Przejdź na wyższą wersję

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

    Usunięto wycofany wcześniej interfejs API Alternatywny interfejs API do użycia
    BillingClient.SkuType BillingClient.ProductType. Stałe typu produktu INAPP i SUBS działają podobnie jak wycofane stałe typu SKU.
    SkuDetails ProductDetails Jest to nowy model danych, który obsługuje produkty jednorazowe.
    SkuDetailsParams Użyj QueryProductDetailsParams z funkcją queryProductDetailsAsync.
    SkuDetailsResponseListener Używaj interfejsu ProductDetailsResponseListener z funkcją queryProductDetailsAsync.
    QueryPurchaseHistoryParams
    • W przypadku aktywnych lub oczekujących zakupów używaj funkcji queryProductDetailsAsync.
    • Śledź wykorzystane zakupy na serwerach backendu.
    • W przypadku anulowanych lub unieważnionych zakupów używaj interfejsu API po stronie serwera Voided Purchases API.
    getSkuDetailsList i setSkuDetailsList Użyj metody 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ługa nowych kodów odpowiedzi podrzędnej.

    Obiekt BillingResult zwracany przez interfejs launchBillingFlow() będzie teraz zawierać pole kodu podrzędnej odpowiedzi. To pole jest 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 kwalifikacji do oferty subskrypcji.
    • NO_APPLICABLE_SUB_RESPONSE_CODE – wartość domyślna zwracana, gdy nie ma zastosowania żaden inny kod podrzędnej odpowiedzi.

    Krok migracji: zaktualizuj obsługę wyników PurchasesUpdatedListener lub równoważną, aby rozpoznawać te konkretne kody odpowiedzi podrzędnych i na nie reagować, co pozwoli zwiększyć wygodę użytkowników. Może to być na przykład prośba o naprawienie form płatności lub wyświetlenie konkretnego komunikatu o błędzie.

  6. Rozpoznawanie przeklasyfikowanych kodów błędów.

    W przypadku, 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 nie polega na otrzymywaniu ogólnego błędu w tych konkretnych scenariuszach.

  7. Obsługa dopuszczalności wartości null DeveloperProvidedBillingDetails.getLinkUri().

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

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

    Kotlin

    val linkUri = details.getLinkUri()
if (!linkUri.isNullOrEmpty()) {
  val intent = Intent(Intent.ACTION_VIEW, Uri.parse(linkUri))
  context.startActivity(intent)
}

    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.