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 oparte na wyborze użytkownika.

Konfiguracja Biblioteki płatności w Play

Dodaj zależność Biblioteki płatności w Google Play do aplikacji na Androida. Aby korzystać z interfejsów API 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

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

  • Musisz wywołać nową metodę, aby wskazać, że chcesz zaoferować użytkownikowi wybór opcji rozliczeniowych: enableUserChoiceBilling.
  • Musisz zarejestrować UserChoiceBillingListener do obsługi przypadków, w których użytkownik wybierze rozliczenia alternatywne.

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

Kotlin

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

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

val 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 nawiązać połączenie z Google Play zgodnie z opisem w przewodniku po integracji.

Wyświetlanie dostępnych produktów

Możesz wyświetlać dostępne produkty użytkownikowi w taki sam sposób jak w przypadku integracji z systemem rozliczeniowym Google Play. Gdy użytkownik zobaczy produkty dostępne do zakupu i wybierze jeden z nich, uruchom proces systemu rozliczeniowego opartego na wyborze użytkownika opisany w następnej sekcji.

Uruchamianie procesu rozliczeniowego opartego na wyborze użytkownika

Uruchom proces systemu rozliczeniowego opartego na wyborze użytkownika, wywołując funkcję launchBillingFlow(). Działa to tak samo jak uruchamianie procesu zakupu z integracją systemu rozliczeniowego Google Play: podajesz instancję ProductDetails i offerToken odpowiadające produktowi i ofercie, które użytkownik chce kupić. Jeśli użytkownik wybierze system rozliczeniowy Google Play, te informacje zostaną użyte do kontynuowania procesu zakupu.

Gdy deweloperzy wywołują funkcję launchBillingFlow(), system rozliczeniowy Google Play przeprowadza te sprawdzenia:

  • System sprawdza, czy kraj w Google Play użytkownika jest krajem, w którym można korzystać z rozliczeń alternatywnych opartych na wyborze użytkownika (czyli krajem obsługiwanym). Jeśli kraj użytkownika w Google Play jest obsługiwany, Google Play sprawdza, czy włączono alternatywny system rozliczeniowy na podstawie konfiguracji BillingClient.
    • Jeśli włączono alternatywny system rozliczeniowy z opcją wyboru przez użytkowników, w procesie zakupu wyświetla się interfejs użytkownika z opcją wyboru.
    • Jeśli rozliczenia alternatywne z opcją wyboru przez użytkowników są wyłączone, proces zakupu wyświetla standardowy interfejs systemu rozliczeniowego Google Play bez opcji wyboru przez użytkowników.
  • Jeśli kraj użytkownika w Google Play nie jest obsługiwany, proces zakupu będzie wyświetlać standardowy interfejs systemu rozliczeniowego Google Play bez możliwości wyboru przez użytkownika.

Kraj w Google Play użytkownika jest obsługiwany

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

wywołanie enableUserChoiceBilling podczas konfiguracji BillingClient

Użytkownik widzi interfejs opcji do wyboru przez użytkownika

Użytkownik widzi standardowy interfejs systemu rozliczeniowego Google Play

Funkcja enableUserChoiceBilling nie została wywołana podczas konfiguracji BillingClient

Użytkownik widzi standardowy interfejs systemu rozliczeniowego Google Play

Użytkownik widzi standardowy interfejs systemu rozliczeniowego Google Play

Obsługa wyboru użytkownika

Dalszy proces 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 wybierze alternatywny system rozliczeniowy

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

Token transakcji zewnętrznej podany w obiekcie UserChoiceDetails reprezentuje podpis potwierdzający wybór użytkownika dotyczący przejścia do alternatywnego systemu rozliczeniowego. Użyj tego tokena, aby zgłosić dowolną transakcję wynikającą z tego wyboru, zgodnie z opisem w przewodniku po integracji backendu.

UserChoiceBillingListener powinien wykonać te działania:

  • Pobierz produkt lub produkty kupowane przez użytkownika, aby można je było wyświetlić w procesie zakupu w alternatywnym systemie rozliczeniowym.
  • Zbierz ciąg znaków otrzymany jako token transakcji zewnętrznej i wyślij go do backendu, aby go zapisać. Jest on później używany do zgłaszania transakcji zewnętrznej do 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ę do Google Play, wywołując interfejs API Google Play Developer z backendu w ciągu 24 godzin, podając externalTransactionToken i dodatkowe szczegóły transakcji. Więcej informacji znajdziesz w przewodniku po integracji z backendem.

Poniższy 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ł dokonać zakupu w Google Play.

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

Obsługa zmian w subskrypcji

W przypadku deweloperów korzystających z alternatywnego systemu rozliczeniowego opartego na wyborze użytkownika zakupy muszą być przetwarzane w ramach systemu rozliczeniowego Google Play lub zgłaszane za pomocą parametru externalTransactionId, w zależności od wyboru użytkownika. Zmiany w przypadku istniejących subskrypcji, które zostały przetworzone w ramach procesu wyboru użytkownika, można wprowadzać w tym samym systemie rozliczeniowym do momentu wygaśnięcia subskrypcji.

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

Przechodzenie na wyższą lub niższą wersję usługi

Zmiany planu subskrypcji, w tym przejście na wyższy lub niższy plan, powinny być obsługiwane w inny sposób w zależności od tego, czy subskrypcja została pierwotnie kupiona za pomocą systemu rozliczeniowego Google Play czy systemu alternatywnego.

Dodatki, które są zależne od istniejącej subskrypcji, korzystają z tej samej formy płatności i mają takie same opłaty cykliczne, są traktowane jako uaktualnienia. W przypadku innych dodatków użytkownicy powinni mieć możliwość wyboru systemu rozliczeniowego, którego chcą używać. Rozpocznij nowy proces zakupu za pomocą launchBillingFlow() zgodnie z opisem w artykule Uruchamianie procesu rozliczeniowego opartego na wyborze użytkownika.

Subskrypcje kupione za pomocą alternatywnego systemu rozliczeniowego

W przypadku subskrypcji, które zostały pierwotnie kupione za pomocą alternatywnego systemu rozliczeniowego dewelopera po wyborze użytkownika, użytkownicy proszący o przejście na wyższy lub niższy pakiet powinni skorzystać z alternatywnego systemu rozliczeniowego dewelopera bez ponownego przechodzenia przez proces wyboru użytkownika.

Aby to zrobić, wywołaj funkcję launchBillingFlow(), gdy użytkownik poprosi o przejście na wyższą lub niższą wersję usługi. Zamiast określać obiekt SubscriptionUpdateParams w parametrach, użyj parametru setOriginalExternalTransactionId, podając zewnętrzny identyfikator transakcji pierwotnego zakupu. Nie wyświetla to ekranu wyboru użytkownika, ponieważ wybór użytkownika dotyczący pierwotnego zakupu jest zachowywany w przypadku przejścia na wyższy lub niższy poziom. Wywołanie funkcji launchBillingFlow() w tym przypadku generuje nowy token transakcji zewnętrznej, 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 using queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in
                // ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .build()
        )
    .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 using 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.

Gdy przejście na wyższą lub niższą wersję zostanie zakończone w alternatywnym systemie rozliczeniowym, musisz zgłosić nową transakcję, używając tokena transakcji zewnętrznej uzyskanego w poprzednim wywołaniu w przypadku zakupu nowej subskrypcji.

Subskrypcje kupione przy użyciu systemu rozliczeniowego Google Play

Podobnie użytkownikom, którzy kupili obecną subskrypcję za pomocą systemu rozliczeniowego Google Play po wprowadzeniu wyboru użytkownika, należy wyświetlać proces uaktualniania lub obniżania wersji w systemie rozliczeniowym Google Play. Poniżej znajdziesz instrukcje, jak uruchomić proces zakupu uaktualnienia lub obniżenia wersji w systemie rozliczeniowym Google Play:

  1. Określ offerToken wybranej oferty dla nowego planu:

    Kotlin

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

    Java

    String offerTokenNewPlan = productDetailsNewPlan
        .getSubscriptionOfferDetails(selectedOfferIndex)
        .getOfferToken();

  2. Prześlij do systemu rozliczeniowego Google Play prawidłowe informacje, aby przetworzyć nowy zakup, w tym token zakupu istniejącej subskrypcji:

    Kotlin

    val billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(
            listOf(
                BillingFlowParams.ProductDetailsParams.newBuilder()
                    // Fetched using queryProductDetailsAsync
                    .setProductDetails(productDetailsNewPlan)
                    // offerIdToken can be found in
                    // ProductDetails=>SubscriptionOfferDetails.
                    .setOfferToken(offerTokenNewPlan)
                    .build()
                )
        )
        .setSubscriptionUpdateParams(
            BillingFlowParams.SubscriptionUpdateParams.newBuilder()
                // purchaseToken can be found in
                // Purchase#getPurchaseToken
                .setOldPurchaseToken(oldToken)
                .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
                .build()
        )
        .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

    Java

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

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

Zakup jest realizowany w systemie rozliczeniowym Google Play, a aplikacja otrzymuje wywołanie PurchasesUpdatedListener.onPurchaseUpdated z wynikiem zakupu. Jeśli zakup się powiódł, metoda onPurchaseUpdated() również otrzymuje nowe informacje o zakupie, a Twój backend otrzymuje SUBSCRIPTION_PURCHASED powiadomienie w czasie rzeczywistym dla deweloperów. Podczas pobierania stanu nowego zakupu atrybut linkedPurchaseToken jest połączony ze starym zakupem 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ę, zakończenie dostępu może zostać odroczone do końca okresu płatności. Jeśli na przykład użytkownik anuluje subskrypcję miesięczną w połowie miesiąca, może nadal korzystać z usługi przez pozostałe 2 tygodnie, aż do momentu usunięcia dostępu. W tym okresie subskrypcja jest nadal aktywna, więc użytkownik może korzystać z usługi.

Często zdarza się, że użytkownicy decydują się na wycofanie anulowania w tym okresie aktywności. W tym przewodniku nazywamy to przywracaniem. W kolejnych sekcjach opisujemy, jak obsługiwać scenariusze przywracania w ramach integracji interfejsu API do rozliczeń alternatywnych.

Subskrypcje kupione za pomocą alternatywnego systemu rozliczeniowego

Jeśli masz zewnętrzny identyfikator transakcji anulowanej subskrypcji, nie musisz wywoływać funkcji launchBillingFlow(), aby przywrócić subskrypcję, więc nie należy jej używać do tego typu aktywacji. Jeśli użytkownik przywróci subskrypcję w okresie aktywności anulowanej subskrypcji, w tym czasie nie nastąpi żadna transakcja. Możesz po prostu nadal raportować odnowienia, gdy bieżący cykl wygaśnie i nastąpi kolejne odnowienie. Dotyczy to przypadków, w których użytkownik otrzymuje środki lub specjalną cenę odnowienia w ramach przywracania (np. promocję zachęcającą do kontynuowania subskrypcji).

Subskrypcje kupione przy użyciu systemu rozliczeniowego Google Play

Użytkownicy mogą zazwyczaj 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 subskrypcja jest aktywna, korzystając z funkcji Ponowna subskrypcja w Google Play. W takim przypadku otrzymasz SUBSCRIPTION_RESTARTEDpowiadomienie w czasie rzeczywistym dla deweloperówSUBSCRIPTION_RESTARTED na serwerze backendu, a nowy token zakupu nie zostanie wydany – do kontynuowania subskrypcji używany jest pierwotny token. Informacje o zarządzaniu przywracaniem w systemie rozliczeniowym Google Play znajdziesz w sekcji Przywracanie w przewodniku po zarządzaniu subskrypcjami.

Możesz też wywołać przywracanie w systemie rozliczeniowym Google Play z poziomu aplikacji, wywołując funkcję launchBillingFlow(). Wyjaśnienie, jak to zrobić, znajdziesz w sekcji Przed wygaśnięciem subskrypcji – w aplikacji. W przypadku użytkowników, którzy przeszli proces wyboru użytkownika w przypadku pierwotnego zakupu (który został anulowany, ale nadal jest aktywny), system automatycznie wykrywa ich wybór i wyświetla interfejs użytkownika do przywracania tych zakupów. Użytkownicy są proszeni o potwierdzenie ponownego zakupu subskrypcji w Google Play, ale nie muszą ponownie przechodzić procesu wyboru. W tym przypadku zostanie wydany nowy token zakupu. Twój backend otrzymuje SUBSCRIPTION_PURCHASEDpowiadomienie w czasie rzeczywistym dla deweloperów, a linkedPurchaseTokenwartość nowego zakupu jest ustawiana tak jak w przypadku przejścia na wyższy lub niższy poziom, ze starym tokenem zakupu dla anulowanej subskrypcji.

Ponowne subskrypcje

Jeśli subskrypcja całkowicie wygaśnie z powodu anulowania lub odrzucenia płatności bez możliwości odzyskania (zawieszenie konta z powodu wygaśnięcia), użytkownik musi ponownie wykupić subskrypcję, jeśli chce ponownie uzyskać dostęp do treści.

Ponowne subskrybowanie można też włączyć w aplikacji, przetwarzając je podobnie jak standardową rejestrację. Użytkownicy powinni mieć możliwość wyboru systemu rozliczeniowego, z którego chcą korzystać. launchBillingFlow() może być w tym przypadku wywoływana zgodnie z opisem w artykule Uruchamianie procesu rozliczeniowego opartego na wyborze użytkownika.

Testowanie alternatywnego systemu rozliczeniowego

Testerzy licencji powinni testować integrację rozliczeń alternatywnych. Nie będziemy wystawiać 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.