Wskazówki dotyczące integracji w aplikacji w przypadku rozliczeń alternatywnych z możliwością wyboru przez użytkownika

Z tego przewodnika dowiesz się, jak zintegrować interfejsy API, aby oferować w aplikacji rozliczenia alternatywne z możliwością wyboru przez użytkownika.

Konfiguracja Biblioteki płatności w Play

Dodaj zależność Biblioteki płatności w Play do aplikacji na Androida. Aby korzystać z interfejsów API do rozliczeń alternatywnych, musisz używać wersji 5.2 lub nowszej. Jeśli musisz przeprowadzić migrację ze starszej wersji, przed wdrożeniem rozliczeń alternatywnych postępuj zgodnie z instrukcjami w przewodniku po migracji.

Połącz z Google Play

Pierwszy krok procesu integracji jest taki sam jak w przewodniku po integracji z Płatnościami w Google Play, ale podczas inicjowania klienta BillingClient występuje kilka zmian:

  • Musisz wywołać nową metodę, aby wskazać użytkownikowi, że chcesz zaoferować użytkownikowi wybór opcji płatności: enableUserChoiceBilling.
  • Musisz zarejestrować UserChoiceBillingListener na potrzeby obsługi zgłoszeń, w których użytkownik wybiera rozliczenia alternatywne.

Poniższy przykład pokazuje inicjowanie elementu BillingClient za pomocą tych modyfikacji:

Kotlin

val purchasesUpdatedListener =
   PurchasesUpdatedListener { billingResult, purchases ->
       // Handle new Google Play purchase.
   }

val userChoiceBillingListener =
   UserChoiceBillingListener { userChoiceDetails ->
       // Handle alternative billing choice.
   }

var billingClient = BillingClient.newBuilder(context)
   .setListener(purchasesUpdatedListener)
   .enablePendingPurchases()
   .enableUserChoiceBilling(userChoiceBillingListener)
   .build()

Java

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
    @Override
    public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
        // Handle new Google Play purchase.
    }
};

private UserChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
        UserChoiceDetails userChoiceDetails) {
        // Handle new Google Play purchase.
    }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableUserChoiceBilling(userChoiceBillingListener)
    .build();

Po zainicjowaniu BillingClient musisz połączyć się z Google Play zgodnie z opisem w przewodniku po integracji.

Wyświetl dostępne produkty

Możesz wyświetlać użytkownikom dostępne produkty tak samo jak w przypadku integracji z systemem rozliczeniowym Google Play. Gdy użytkownik zobaczy produkt, który jest dostępny do zakupu, wybierze go, aby uruchomić proces systemu rozliczeniowego opartego na wyborze użytkownika zgodnie z opisem w następnej sekcji.

Uruchamianie procesu systemu rozliczeniowego opartego na wyborze użytkownika

Uruchom proces systemu rozliczeniowego opartego na wyborze użytkownika, dzwoniąc pod numer launchBillingFlow(). Działa to tak samo jak uruchamianie procesu zakupu z integracją z systemem rozliczeniowym Google Play: podajesz wystąpienie ProductDetails oraz offerToken odpowiadające produktowi i ofercie, którą użytkownik chce pozyskać. Jeśli użytkownik wybierze system rozliczeniowy Google Play, te informacje będą używane do kontynuowania procesu zakupu.

Gdy deweloperzy wywołują launchBillingFlow(), system rozliczeniowy Google Play wykonuje tę kontrolę:

  • System sprawdza, czy kraj użytkownika w Google Play obsługuje alternatywny system rozliczeniowy z wyborem użytkownika (czyli jest to obsługiwany kraj). Jeśli kraj użytkownika w Google Play jest obsługiwany, Google Play sprawdza, czy włączono rozliczenia alternatywne na podstawie konfiguracji BillingClient.
    • Jeśli włączono alternatywny system rozliczeniowy z wyborem użytkownika, w procesie zakupu widoczny będzie UX.
    • Jeśli alternatywny system rozliczeniowy z wyborem użytkownika nie jest włączony, w procesie zakupu widoczny jest standardowy interfejs systemu rozliczeniowego Google Play, ale bez opcji wyboru przez użytkownika.
  • Jeśli kraj użytkownika w Google Play nie jest obsługiwanym krajem, proces zakupu odzwierciedla wrażenia użytkownika związane ze standardowym systemem rozliczeniowym Google Play (bez wyboru użytkownika).

Kraj użytkownika w Google Play jest obsługiwany

Kraj użytkownika w Google Play nie jest obsługiwany

Wywołanie elementu allowUserChoiceBilling podczas konfiguracji BillingClient

Użytkownik widzi wybór użytkownika

Użytkownik widzi standardowy interfejs systemu rozliczeniowego Google Play

Metoda allowUserChoiceBilling nie została wywołana podczas konfiguracji interfejsu BillingClient

Użytkownik widzi standardowy interfejs systemu rozliczeniowego Google Play

Użytkownik widzi standardowy interfejs systemu rozliczeniowego Google Play

Wybierz użytkownika

Sposób, w jaki obsługujesz pozostałą część procesu zakupu, różni się w zależności od tego, czy użytkownik wybrał system rozliczeniowy Google Play czy alternatywny system rozliczeniowy.

Gdy użytkownik wybiera alternatywny system rozliczeniowy

Jeśli użytkownik wybierze alternatywny system rozliczeniowy, Google Play wywołuje UserChoiceBillingListener, aby powiadomić aplikację, że musi uruchomić proces zakupu w tym systemie. W szczególności jest wywoływana metoda userSelectedAlternativeBilling().

Zewnętrzny token transakcji podany w obiekcie UserChoiceDetails reprezentuje podpis, który decyduje o włączeniu procesu rozliczeń alternatywnych. Użyj tego tokena, aby zgłosić wszystkie transakcje wynikające z tego wyboru, zgodnie z opisem w przewodniku po integracji backendu.

UserChoiceBillingListener powinien wykonać te działania:

  • Pobierz produkty, które kupujesz przez użytkownika, aby były one przedstawione podczas procesu zakupu w alternatywnym systemie rozliczeniowym.
  • Zbierz ciąg znaków odebrany jako zewnętrzny token transakcji i wyślij go do backendu, aby go zachować. Służy ona później do raportowania transakcji zewnętrznej w Google Play, jeśli użytkownik dokona tego konkretnego zakupu.
  • Uruchom alternatywny proces zakupu dewelopera.

Jeśli użytkownik dokona zakupu za pomocą alternatywnego systemu rozliczeniowego, musisz zgłosić transakcję w Google Play, wywołując interfejs Google Play Developer API z backendu w ciągu 24 godzin, podając externalTransactionToken oraz dodatkowe szczegóły transakcji. Więcej informacji znajdziesz w przewodniku po integracji backendu.

Ten przykład pokazuje, jak wdrożyć UserChoiceBillingListener:

Kotlin

private val userChoiceBillingListener =
    UserChoiceBillingListener { userChoiceDetails ->
        // Get the products being purchased by the user.
        val products = userChoiceDetails.products

        // Send external transaction token to developer backend server
        // this devBackend object is for demonstration purposes,
        // developers can implement this step however best fits their
        // app to backend communication.
        devBackend.sendExternalTransactionStarted(
            userChoiceDetails.externalTransactionToken,
            user
        )

        // Launch alternative billing
        // ...
        // The developer backend handles reporting the transaction
        // to Google Play's backend once the alternative billing
        // purchase is completed.
    }

Java

private userChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
           UserChoiceDetails userChoiceDetails) {
       // Get the products being purchased by the user.
       List<Product> products =
              userChoiceDetails.getProducts();

       // Send external transaction token to developer backend server
       // this devBackend object is for demonstration purposes,
       // developers can implement this step however best fits their
       // app to backend communication.
       devBackend.sendExternalTransactionStarted(
              userChoiceDetails.getExternalTransactionToken(),
              user
       );

       // Launch alternative billing
       // ...
       // The developer backend handles reporting the transaction
       // to Google Play's backend once the alternative billing
       // purchase is completed.
    }
};

Gdy użytkownik wybierze system rozliczeniowy Google Play

Jeśli użytkownik wybierze system rozliczeniowy Google Play, będzie mógł kontynuować zakup w tej usłudze.

  • Więcej informacji o obsłudze nowych zakupów w aplikacji za pomocą systemu rozliczeniowego Google Play znajdziesz w sekcji Przetwarzanie zakupów w przewodniku po integracji z biblioteką.
  • Dodatkowe wskazówki dotyczące zakupu subskrypcji znajdziesz w sekcji Nowe subskrypcje w przewodniku po zarządzaniu subskrypcjami.

Obsługuj zmiany w subskrypcji

W przypadku deweloperów korzystających z alternatywnego systemu rozliczeniowego z opcją wyboru przez użytkownika zakupy muszą być przetwarzane w systemie rozliczeniowym Google Play lub zgłaszane przy użyciu funkcji externalTransactionId (w zależności od wyboru użytkownika). Zmiany w dotychczasowych subskrypcjach, które zostały przetworzone w ramach procesu wyboru użytkownika, można wprowadzić w tym samym systemie rozliczeniowym do czasu ich wygaśnięcia.

W tej sekcji opisano, jak postępować w przypadku niektórych typowych scenariuszy zmiany subskrypcji.

Procesy przejścia na wyższą lub niższą wersję usługi

Proces przekształcania i przechodzenia na niższą wersję powinien przebiegać w różny sposób w zależności od tego, czy subskrypcja została pierwotnie kupiona w systemie rozliczeniowym Google Play czy przy użyciu alternatywnego systemu rozliczeniowego.

Subskrypcje kupione przy użyciu alternatywnego systemu rozliczeniowego

W przypadku subskrypcji, które zostały pierwotnie zakupione po wybraniu przez użytkownika alternatywnego systemu rozliczeniowego dewelopera, użytkownicy proszący o przejście na wyższą lub niższą wersję usługi powinni przejść przez alternatywny system rozliczeniowy dewelopera bez ponownego przechodzenia przez proces wyboru.

Aby to zrobić, wywołaj launchBillingFlow(), gdy użytkownik poprosi o zmianę wersji. Zamiast podawać w parametrach obiekt SubscriptionUpdateParams, użyj parametru setOriginalExternalTransactionId, aby podać zewnętrzny identyfikator transakcji pierwotnego zakupu. Nie wyświetla się ekran wyboru użytkownika, ponieważ wybór użytkownika dotyczący pierwotnego zakupu jest zachowywany w przypadku przejścia na wyższą lub niższą wersję usługi. Wywołanie launchBillingFlow() w tym przypadku generuje nowy zewnętrzny token transakcji dla transakcji, który możesz pobrać z wywołania zwrotnego.

Kotlin

// The external transaction ID from the current
// alternative billing subscription.
val externalTransactionId = //... ;

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                // Fetched via queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in
                // ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

Java

// The external transaction ID from the current
// alternative billing subscription.
String externalTransactionId = //... ;

BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(
                ImmutableList.of(
                    ProductDetailsParams.newBuilder()
                        // Fetched via queryProductDetailsAsync.
                        .setProductDetails(productDetailsNewPlan)
                        // offerIdToken can be found in
                        // ProductDetails=>SubscriptionOfferDetails
                        .setOfferToken(offerTokenNewPlan)
                    .build()
                )
            )
            .setSubscriptionUpdateParams(
                SubscriptionUpdateParams.newBuilder()
                    .setOriginalExternalTransactionId(externalTransactionId)
                    .build()
            )
            .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

Po zakończeniu uaktualniania lub przechodzenia na niższą wersję w alternatywnym systemie rozliczeniowym musisz zgłosić nową transakcję przy użyciu zewnętrznego tokena transakcji uzyskanego w ramach poprzedniego wywołania związanego z zakupem nowej subskrypcji.

Subskrypcje kupione przy użyciu systemu rozliczeniowego Google Play

I podobnie, użytkownicy, którzy kupili swoją bieżącą subskrypcję w systemie rozliczeniowym Google Play po wybraniu przez użytkownika opcji, powinni zobaczyć proces przechodzenia na wyższą lub niższą wersję usługi w systemie rozliczeniowym Google Play. Z tych instrukcji dowiesz się, jak rozpocząć proces zakupu przejścia na wyższą lub niższą wersję usługi w systemie rozliczeniowym Google Play:

  1. Odszukaj offerToken wybranej oferty w nowym abonamencie:

val offerTokenNewPlan = productDetailsNewPlan
             .getSubscriptionOfferDetails(selectedOfferIndex)
             .getOfferToken()

String offerTokenNewPlan = productDetailsNewPlan
                     .getSubscriptionOfferDetails(selectedOfferIndex)
                     .getOfferToken();
  1. Prześlij do systemu rozliczeniowego Google Play prawidłowe informacje, w tym token zakupu istniejącej subskrypcji, aby umożliwić przetworzenie nowego zakupu:

val billingFlowParams =
    BillingFlowParams.newBuilder().setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                .setProductDetails(productDetailsNewPlan)
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOldPurchaseToken(oldToken)
            .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
            .build()
        )
        .build()

BillingClient.launchBillingFlow(activity, billingFlowParams)

BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(
                ImmutableList.of(
                    ProductDetailsParams.newBuilder()
                        // Fetched via queryProductDetailsAsync
                        .setProductDetails(productDetailsNewPlan)
                        // offerIdToken can be found in
                        // ProductDetails=>SubscriptionOfferDetails.
                        .setOfferToken(offerTokenNewPlan)
                        .build()
                )
            )
            .setSubscriptionUpdateParams(
                SubscriptionUpdateParams.newBuilder()
                    // purchaseToken can be found in
                    // Purchase#getPurchaseToken
                    .setOldPurchaseToken("old_purchase_token")
                    .setReplaceProrationMode(ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
                    .build()
            )
            .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

Ten zakup zostanie zrealizowany w systemie rozliczeniowym Google Play, a po dokonaniu zakupu Twoja aplikacja otrzyma wywołanie PurchasesUpdatedListener.onPurchaseUpdated. Jeśli zakup się uda, metoda onPurchaseUpdated() również otrzyma nowe informacje o zakupie, a Twój backend otrzyma powiadomienie dla dewelopera SUBSCRIPTION_PURCHASED w czasie rzeczywistym. Podczas pobierania stanu nowego zakupu atrybut linkedPurchaseToken kieruje do starego zakupu subskrypcji, dzięki czemu możesz go wycofać zgodnie z zaleceniami.

Anulowanie i przywracanie subskrypcji

Użytkownicy powinni mieć możliwość anulowania subskrypcji w dowolnym momencie. Gdy użytkownik anuluje subskrypcję, jej wygaśnięcie może zostać odroczone do końca okresu obowiązywania płatnej subskrypcji. Jeśli na przykład użytkownik anuluje subskrypcję miesięczną, może nadal korzystać z usługi przez około 2 tygodnie, dopóki nie zostanie usunięty. W tym czasie subskrypcja jest wciąż aktywna technicznie, więc użytkownik może korzystać z usługi.

Często w tym czasie użytkownicy decydują się na anulowanie subskrypcji. W tym przewodniku jest to tzw. przywracanie. W sekcjach poniżej opisujemy, jak postępować w przypadku scenariuszy przywracania w ramach integracji interfejsu API rozliczeń alternatywnych.

Subskrypcje kupione przy użyciu alternatywnego systemu rozliczeniowego

Jeśli masz zewnętrzny identyfikator transakcji w przypadku anulowanej subskrypcji, nie musisz wywoływać launchBillingFlow() w celu przywrócenia subskrypcji, więc nie należy go używać w przypadku tego typu aktywacji. Jeśli użytkownik przywróci subskrypcję w aktywnym okresie anulowanej subskrypcji, w tym czasie nie zostanie dokonana żadna transakcja. Możesz po prostu kontynuować raportowanie odnowień, gdy bieżący cykl dobiegnie końca i dojdzie do następnego odnowienia. Obejmuje to przypadki, gdy użytkownik otrzymuje środki lub specjalną cenę za odnowienie w ramach przywracania (na przykład w ramach promocji zachęcającej użytkownika do kontynuowania subskrypcji).

Subskrypcje kupione przy użyciu systemu rozliczeniowego Google Play

Zazwyczaj użytkownicy mogą przywracać subskrypcje w systemie rozliczeniowym Google Play. W przypadku anulowanych subskrypcji, które zostały pierwotnie kupione w systemie rozliczeniowym Google Play, użytkownik może cofnąć anulowanie, gdy jest ona aktywna, za pomocą funkcji Odnów subskrypcję w Google Play. W takim przypadku otrzymasz w backendzie powiadomienie dla dewelopera SUBSCRIPTION_RESTARTED w czasie rzeczywistym, a nowy token zakupu nie zostanie wydany. Pierwotny token będzie używany do kontynuowania subskrypcji. Aby dowiedzieć się, jak zarządzać przywracaniem w systemie rozliczeniowym Google Play, przeczytaj sekcję Przywracanie w przewodniku po zarządzaniu subskrypcjami.

Możesz też wywołać przywrócenie w systemie rozliczeniowym Google Play z poziomu aplikacji, wywołując launchBillingFlow(). Instrukcje znajdziesz w sekcji Przed wygaśnięciem subskrypcji w aplikacji. W przypadku użytkowników, którzy przeszli proces wyboru przy pierwotnym zakupie (który został anulowany, ale nadal jest aktywny), system automatycznie wykryje swój wybór i wyświetli interfejs umożliwiający przywrócenie zakupów. Jest proszony o potwierdzenie zakupu subskrypcji w Google Play, ale nie musi ponownie przechodzić przez proces wyboru. W takim przypadku użytkownik otrzymuje nowy token zakupu. Backend otrzymuje powiadomienie dla deweloperów w czasie rzeczywistym SUBSCRIPTION_PURCHASED. Wartość linkedPurchaseToken dla nowego stanu zakupu jest ustawiana tak jak w przypadku przejścia na wyższą lub niższą wersję z dotychczasowym tokenem zakupu dla anulowanej subskrypcji.

Ponowne subskrypcje

Jeśli subskrypcja wygaśnie całkowicie, niezależnie od tego, czy jest to spowodowane anulowaniem czy odrzuceniem płatności bez odzyskania (zawieszenie konta, które wygasło), użytkownik musi ponownie wykupić subskrypcję, aby wznowić subskrypcję.

Subskrypcję można też włączyć w aplikacji, przetwarzając ją podobnie jak w przypadku standardowej rejestracji. Użytkownicy powinni mieć możliwość wyboru systemu rozliczeniowego, którego chcą używać. W tym przypadku może być wywoływana usługa launchBillingFlow() zgodnie z opisem w sekcji Wdrażanie systemu rozliczeniowego opartego na wyborze użytkownika.

Testowanie alternatywnego systemu rozliczeniowego

Do przetestowania integracji rozliczeń alternatywnych należy używać testerów licencji. Nie obciążymy Cię płatnością 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 aplikacji.

Dalsze kroki

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