Wskazówki dotyczące integracji w aplikacji tylko w przypadku rozliczeń alternatywnych

Z tego przewodnika dowiesz się, jak zintegrować interfejsy API, aby oferować tylko rozliczenia alternatywne (tj. bez opcji wyboru przez użytkowników) w kwalifikujących się aplikacjach. Więcej informacji o tych programach, w tym o wymaganiach i zakresie geograficznym, znajdziesz w artykule Informacje o alternatywnych metodach płatności.

Konfiguracja Biblioteki płatności w Play

Dodaj zależność Biblioteki płatności w Play do aplikacji na Androida. Aby korzystać z rozliczeń alternatywnych, musisz używać wersji 6.1 lub nowszej.

Połącz z Google Play

Pierwsze kroki procesu integracji są takie same jak te opisane w przewodniku po integracji z płatnościami w Google Play. W przypadku inicjowania BillingClient należy jednak wprowadzić kilka modyfikacji:

  • Musisz wywołać nową metodę, aby wskazać, że Twoja aplikacja korzysta tylko z alternatywnego systemu rozliczeniowego: enableAlternativeBillingOnly.

Poniższy przykład pokazuje, jak zainicjować BillingClient z tymi zmianami:

Kotlin


var billingClient = BillingClient.newBuilder(context)
    .enableAlternativeBillingOnly()
    .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableAlternativeBillingOnly()
    .build();

Po zainicjowaniu BillingClient musisz nawiązać połączenie z Google Play zgodnie z opisem w przewodniku po integracji.

Sprawdzanie dostępności

Aplikacja powinna potwierdzać, że dostępne są tylko rozliczenia alternatywne, wywołując funkcję isAlternativeBillingOnlyAvailableAsync.

Ten interfejs API zwróci wartość BillingResponseCode.OK, jeśli dostępne są tylko rozliczenia alternatywne. Więcej informacji o tym, jak aplikacja powinna reagować na inne kody odpowiedzi, znajdziesz w sekcji Obsługa odpowiedzi.

Kotlin


billingClient.isAlternativeBillingOnlyAvailableAsync(object:
    AlternativeBillingOnlyAvailabilityListener {
        override fun onAlternativeBillingOnlyAvailabilityResponse(
            billingResult: BillingResult) {
            if (billingResult.responseCode !=  BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors,
                // handling alternative billing only being unavailable, etc.
                return
            }

            // Alternative billing only is available. Continue with steps in
            // the guide.
        }
    });

Java


billingClient.isAlternativeBillingOnlyAvailable(
    new AlternativeBillingOnlyAvailabilityListener() {
        @Override
        public void onAlternativeBillingOnlyAvailabilityResponse(
            BillingResult billingResult) {
            if (billingResult.getResponseCode() != BillingResponseCode.OK) {
                 // Handle failures such as retrying due to network errors,
                 // handling alternative billing only being unavailable,
                 // etc.
                return;
            }

            // Alternative billing only is available. Continue with steps in
            // the guide.
        }
    });

Okno informacyjne dla użytkowników

Aby zintegrować aplikację tylko z rozliczeniami alternatywnymi, Twoja kwalifikująca się aplikacja musi wyświetlać ekran informacyjny, który pomoże użytkownikom zrozumieć, że rozliczenia nie będą zarządzane przez Google Play. Ekran z informacjami musi być wyświetlany użytkownikom przez wywołanie interfejsu API showAlternativeBillingOnlyInformationDialog przed każdym rozpoczęciem procesu rozliczeń alternatywnych. Jeśli użytkownik potwierdził już wyświetlenie okna, użycie tego interfejsu API zwykle nie spowoduje ponownego wyświetlenia okna. W niektórych sytuacjach okno dialogowe może wyświetlić się ponownie, np. gdy użytkownik wyczyści pamięć podręczną na urządzeniu.

Kotlin


// An activity reference from which the alternative billing only information
// dialog will be launched.
val activity : Activity = ...;

val listener : AlternativeBillingOnlyInformationDialogListener =
    AlternativeBillingOnlyInformationDialogListener { 
        override fun onAlternativeBillingOnlyInformationDialogResponse(
            billingResult: BillingResult) {
            // check billingResult
        }
}

val billingResult =
    billingClient.showAlternativeBillingOnlyInformationDialog(activity,
        listener)

Java


// An activity reference from which the alternative billing only information
// dialog will be launched.
Activity activity = ...;

AlternativeBillingOnlyInformationDialogListener listener =
    new AlternativeBillingOnlyInformationDialogListener() {
        @Override
        public void onAlternativeBillingOnlyInformationDialogResponse(
            BillingResult billingResult) {
                // check billingResult
            }
    };

BillingResult billingResult =
    billingClient.showAlternativeBillingOnlyInformationDialog(activity,
        listener);

Jeśli ta metoda zwraca wartość BillingResponseCode.OK, aplikacja może kontynuować transakcję. W przypadku kodu BillingResponseCode.USER_CANCELED aplikacja powinna wywołać funkcję showAlternativeBillingOnlyInformationDialog, aby ponownie wyświetlić użytkownikowi okno. Inne kody odpowiedzi znajdziesz w sekcji dotyczącej obsługi odpowiedzi.

Zgłaszanie transakcji do Google Play

Wszystkie transakcje dokonane za pomocą alternatywnego systemu rozliczeniowego muszą być zgłaszane do Google Play przez wywołanie interfejsu Google Play Developer API z backendu w ciągu 24 godzin. Należy podać externalTransactionToken, który jest uzyskiwany za pomocą interfejsu API opisanego poniżej. Nowy token externalTransactionToken należy generować w przypadku każdego jednorazowego zakupu, każdej nowej subskrypcji oraz każdej zmiany na wyższą lub niższą wersję istniejącej subskrypcji. Aby dowiedzieć się, jak zgłaszać transakcje po uzyskaniu externalTransactionToken, zapoznaj się z przewodnikiem po integracji backendu.

Kotlin

billingClient.createAlternativeBillingOnlyReportingDetailsAsync(object:
    AlternativeBillingOnlyReportingDetailsListener {
        override fun onAlternativeBillingOnlyTokenResponse(
            billingResult: BillingResult,
            alternativeBillingOnlyReportingDetails:
                AlternativeBillingOnlyReportingDetails?) {
            if (billingResult.responseCode !=  BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return
            }

            val externalTransactionToken =
                alternativeBillingOnlyReportingDetails?
                    .externalTransactionToken

            // Send transaction token to backend and report to Google Play.
        }
    });

Java


billingClient.createAlternativeBillingOnlyReportingDetailsAsync(
    new AlternativeBillingOnlyReportingDetailsListener() {
        @Override
        public void onAlternativeBillingOnlyTokenResponse(
            BillingResult billingResult,
            @Nullable AlternativeBillingOnlyReportingDetails
                alternativeBillingOnlyReportingDetails) {
            if (billingResult.getResponseCode() != BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return;
            }

            String transactionToken =
                alternativeBillingOnlyReportingDetails
                .getExternalTransactionToken();

            // Send transaction token to backend and report to Google Play.
        }
    });

Obsługa odpowiedzi

Powyższe metody isAlternativeBillingOnlyAvailableAsync(), showAlternativeBillingOnlyInformationDialog() i createAlternativeBillingOnlyReportingDetailsAsync() mogą w przypadku błędów zwracać odpowiedzi inne niż BillingResponseCode.OK. Zalecane postępowanie w przypadku błędów opisano poniżej:

  • ERROR: To błąd wewnętrzny. Nie przeprowadzaj transakcji. Spróbuj ponownie, wywołując showAlternativeBillingOnlyInformationDialog(), aby wyświetlić użytkownikowi okno informacji przy następnej próbie dokonania zakupu.
  • FEATURE_NOT_SUPPORTED: interfejsy API do rozliczeń alternatywnych nie są obsługiwane przez Sklep Play na bieżącym urządzeniu. Nie przeprowadzaj transakcji.
  • USER_CANCELED: nie realizuj transakcji. Ponownie wywołaj funkcję showAlternativeBillingOnlyInformationDialog(), aby wyświetlić użytkownikowi okno informacji przy następnej próbie zakupu.
  • BILLING_UNAVAILABLE: transakcja nie kwalifikuje się tylko do alternatywnego rozliczenia, dlatego nie powinna być realizowana w ramach tego programu. Może to być spowodowane tym, że użytkownik nie mieszka w kraju, w którym ten program jest dostępny, lub Twoje konto nie zostało zarejestrowane w programie. Jeśli tak jest, sprawdź stan rejestracji w Konsoli Play.
  • DEVELOPER_ERROR: wystąpił błąd w żądaniu. Skorzystaj z komunikatu debugowania, aby zidentyfikować i poprawić błąd przed kontynuowaniem.
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: są to błędy przejściowe, które należy ponowić. W przypadku SERVICE_DISCONNECTED przed ponowną próbą nawiąż połączenie z Google Play.

Testowanie rozliczeń alternatywnych

Testerzy licencji powinni testować integrację rozliczeń alternatywnych. Nie będziesz otrzymywać faktur za transakcje zainicjowane przez konta testerów licencji. Więcej informacji o konfigurowaniu testerów licencji znajdziesz w artykule Testowanie rozliczeń w aplikacji za pomocą licencjonowania.

Dalsze kroki

Po zakończeniu integracji w aplikacji możesz zintegrować backend.