Wskazówki dotyczące integracji płatności zewnętrznych w aplikacji

W tym dokumencie opisujemy, jak zintegrować interfejsy API Biblioteki płatności w Play, aby oferować płatności zewnętrzne w kwalifikujących się aplikacjach. Więcej informacji o tym programie, znajdziesz w sekcji Wymagania programu.

Konfigurowanie 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 płatności zewnętrznych, musisz używać wersji 8.3 lub nowszej. Jeśli musisz przeprowadzić migrację z wcześniejszej wersji, przed rozpoczęciem integracji postępuj zgodnie z instrukcjami w przewodniku migracji.

Inicjowanie klienta rozliczeniowego

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

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

Kotlin

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

val developerProvidedBillingListener =
    DeveloperProvidedBillingListener { details ->
        // Handle user selection for developer provided billing option.
    }

val billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
            .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
            .build())
    .build()

Java

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

private DeveloperProvidedBillingListener developerProvidedBillingListener =
    new DeveloperProvidedBillingListener() {
        @Override
        public void onUserSelectedDeveloperBilling(
            DeveloperProvidedBillingDetails details) {
            // Handle user selection for developer provided billing option.
        }
    };

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
            .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
            .build())
    .build();

Połącz z Google Play

Po zainicjowaniu BillingClient połącz się z Google Play zgodnie z opisem w Połącz z Google Play.

Sprawdzanie, czy użytkownik kwalifikuje się do programu

Po połączeniu z Google Play możesz sprawdzić, czy użytkownik kwalifikuje się do programu płatności zewnętrznych, wywołując metodę isBillingProgramAvailableAsync(). Jeśli użytkownik się kwalifikuje, ta metoda zwraca BillingResponseCode.OK. Poniższy przykład pokazuje, jak sprawdzić, czy użytkownik kwalifikuje się do programu:

Kotlin

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_PAYMENTS,
  object : BillingProgramAvailabilityListener {
    override fun onBillingProgramAvailabilityResponse(
      billingProgram: Int, billingResult: BillingResult) {
        if (billingResult.responseCode != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external payments unavailable, etc.
            return
        }

        // External payments are available. Can proceed with generating an
        // external transaction token.
})

Java

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_PAYMENTS,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      int billingProgram, BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external payments unavailable, etc.
            return;
        }

        // External payments are available. Can proceed with generating an external transaction token.
      }

    });

Szczegółowe informacje o tym, jak aplikacja powinna reagować na inne kody odpowiedzi, znajdziesz w sekcji Obsługa odpowiedzi. Jeśli używasz rozszerzeń Kotlin , możesz używać korutyn Kotlin, aby nie musieć definiować osobnego odbiornika.

Wyświetlanie dostępnych produktów

Dostępne produkty możesz wyświetlać użytkownikowi w taki sam sposób jak w przypadku integracji z systemem rozliczeniowym Google Play. Gdy użytkownik zobaczy produkty dostępne do kupienia i wybierze jeden z nich, uruchom proces płatności zewnętrznych zgodnie z opisem w sekcji Uruchamianie procesu płatności zewnętrznych.

Przygotowywanie tokena transakcji zewnętrznej

Aby zgłosić transakcję zewnętrzną w Google Play, musisz mieć token transakcji zewnętrznej wygenerowany przez Bibliotekę płatności w Play. Za każdym razem, gdy użytkownik odwiedza zewnętrzną witrynę lub aplikację za pomocą interfejsu API płatności zewnętrznych, należy wygenerować nowy token transakcji zewnętrznej. Można to zrobić, wywołując interfejs API createBillingProgramReportingDetailsAsync. Token należy wygenerować bezpośrednio przed wywołaniem launchBillingFlow.

Kotlin

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .build()

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  object : BillingProgramReportingDetailsListener {
    override fun onCreateBillingProgramReportingDetailsResponse(
      billingResult: BillingResult,
      billingProgramReportingDetails: BillingProgramReportingDetails?) {
        if (billingResult.responseCode != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            billingProgramReportingDetails?.externalTransactionToken
        // Persist the external transaction token locally. Pass it to
        // the external website using DeveloperBillingOptionParams when
        // launchBillingFlow is called.
    }
})

Java

BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  new BillingProgramReportingDetailsListener() {
    @Override
    public void onCreateBillingProgramReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable BillingProgramReportingDetails
        billingProgramReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          billingProgramReportingDetails.getExternalTransactionToken();

        // Persist the external transaction token locally. Pass it to
        // the external website using DeveloperBillingOptionParams when
        // launchBillingFlow is called.
      }
});

Jeśli używasz rozszerzeń Kotlin, możesz używać korutyn Kotlin, aby nie musieć definiować osobnego odbiornika.

Uruchamianie procesu płatności zewnętrznych

Uruchom proces płatności zewnętrznych, wywołując launchBillingFlow() podobnie do uruchamiania procesu zakupu w przypadku integracji z systemem rozliczeniowym Google Play, ale z dodatkowym parametrem DeveloperBillingOptionParams, który wskazuje, że aplikacja chce włączyć proces płatności zewnętrznych w przypadku tego zakupu.

DeveloperBillingOptionParams musi zawierać te elementy:

  • billingProgram ustawiony na program rozliczeniowy EXTERNAL_PAYMENTS.
  • linkURI ustawiony na miejsce docelowe linku.
  • launchMode ustawiony na LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, jeśli Google Play ma uruchomić link, lub CALLER_WILL_LAUNCH_LINK, jeśli link ma uruchomić Twoja aplikacja.

Gdy aplikacja wywoła launchBillingFlow() z podanym DeveloperBillingOptionParams, system rozliczeniowy Google Play wykona te czynności:

  • Sprawdzi, czy kraj użytkownika w Google Play jest krajem obsługującym płatności zewnętrzne (czyli obsługiwanym krajem). Jeśli kraj użytkownika w Google Play jest obsługiwany, Google Play sprawdzi, czy płatności zewnętrzne są włączone na podstawie konfiguracji BillingClient i czy podano DeveloperBillingOptionParams.
    • Jeśli płatności zewnętrzne są włączone, proces zakupu wyświetla interfejs wyboru użytkownika.
    • Jeśli płatności zewnętrzne nie są włączone, proces zakupu wyświetla standardowy interfejs systemu rozliczeniowego Google Play bez możliwości wyboru przez użytkownika.
  • Jeśli kraj użytkownika w Google Play nie jest obsługiwany, proces zakupu wyświetla standardowy interfejs systemu rozliczeniowego Google Play bez możliwości wyboru przez użytkownika.

Kraj użytkownika w Google Play jest obsługiwany

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

Płatności zewnętrzne są włączone (konfiguracja BillingClient i launchBillingFlow)

Użytkownik widzi interfejs wyboru użytkownika

Użytkownik widzi standardowy interfejs systemu rozliczeniowego Google Play

Płatności zewnętrzne nie są włączone (nie zostały włączone podczas konfiguracji BillingClient lub nie podano DeveloperBillingOptionParams w launchBillingFlow)

Użytkownik widzi standardowy interfejs systemu rozliczeniowego Google Play

Użytkownik widzi standardowy interfejs systemu rozliczeniowego Google Play

Poniższy fragment kodu pokazuje, jak utworzyć DeveloperBillingOptionParams:

Kotlin

val developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .setLinkUri(Uri.parse("https://www.example.com/external/purchase"))
        .setLaunchMode(
            DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
        .build()

Java

DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .setLinkUri(Uri.parse("https://www.example.com/external/purchase"))
        .setLaunchMode(
            DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
        .build();

Obsługa wyboru użytkownika

Sposób obsługi pozostałej części procesu zakupu różni się w zależności od tego, czy użytkownik wybrał system rozliczeniowy Google Play, czy płatność w Twojej witrynie.

Gdy użytkownik wybierze płatność w Twojej witrynie lub w aplikacji płatniczej

Jeśli użytkownik zdecyduje się zapłacić w Twojej witrynie, Google Play wywoła DeveloperProvidedBillingListener aby powiadomić aplikację, że użytkownik wybrał płatność w Twojej witrynie lub w aplikacji płatniczej. W szczególności wywoływana jest metoda onUserSelectedDeveloperBilling().

Jeśli aplikacja ustawi launchMode na LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, Google Play uruchomi link. Jeśli launchMode został ustawiony na CALLER_WILL_LAUNCH_LINK, Twoja aplikacja jest odpowiedzialna za uruchomienie linku. Gdy kierujesz użytkowników do aplikacji płatniczej, musisz sprawdzić, czy użytkownik ma już zainstalowaną aplikację płatniczą na swoim urządzeniu.

Użyj tego tokena, aby zgłosić każdą transakcję wynikającą z tego wyboru, zgodnie z opisem w przewodniku integracji z backendem.

Gdy użytkownik wybierze system rozliczeniowy Google Play

Jeśli użytkownik wybierze system rozliczeniowy Google Play, będzie kontynuować zakup w Google Play.

  • Więcej informacji o tym, jak obsługiwać nowe zakupy w aplikacji za pomocą systemu rozliczeniowego Google Play, znajdziesz w przewodniku integracji z biblioteką w sekcji Przetwarzanie zakupów.
  • Dodatkowe wskazówki dotyczące zakupów subskrypcji znajdziesz w przewodniku zarządzania subskrypcjami w sekcji Nowe subskrypcje.

Obsługa zmian w subskrypcji

W przypadku deweloperów korzystających z płatności zewnętrznych zakupy muszą być przetwarzane za pomocą systemu rozliczeniowego Google Play lub zgłaszane za pomocą externalTransactionId w zależności od wyboru użytkownika. Zmiany w dotychczasowych subskrypcjach, które zostały przetworzone w witrynie dewelopera, można wprowadzać za pomocą tego samego systemu rozliczeniowego do momentu wygaśnięcia subskrypcji.

W tej sekcji opisujemy, jak obsługiwać niektóre typowe scenariusze zmian w subskrypcji.

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

Zmiany planu subskrypcji, w tym procesy przejścia na wyższą i niższą wersję usługi, należy obsługiwać inaczej w zależności od tego, czy subskrypcja została pierwotnie kupiona za pomocą systemu rozliczeniowego Google Play, czy w witrynie dewelopera.

Dodatki, które zależą od istniejącej subskrypcji, korzystają z tej samej formy płatności i są zgodne z opłatami cyklicznymi, są traktowane jako przejście na wyższą wersję usługi. W przypadku innych dodatków użytkownicy powinni mieć możliwość wyboru systemu rozliczeniowego, którego chcą używać. Aby rozpocząć nowy proces zakupu, użyj launchBillingFlow() zgodnie z opisem w sekcji Uruchamianie procesu płatności zewnętrznych.

Subskrypcje kupione w witrynie dewelopera lub w aplikacji płatniczej

W przypadku subskrypcji, które zostały pierwotnie kupione w witrynie dewelopera lub w aplikacji płatniczej po wyborze użytkownika, użytkownicy proszący o przejście na wyższą lub niższą wersję usługi powinni przejść przez witrynę dewelopera lub aplikację płatniczą bez ponownego przechodzenia przez proces wyboru użytkownika.

Aby to zrobić, wywołaj launchBillingFlow() , gdy użytkownik poprosi o przejście na wyższą lub niższą wersję usługi. Zamiast określać inne parametry w obiekcie SubscriptionUpdateParams użyj setOriginalExternalTransactionId(), podając identyfikator transakcji zewnętrznej dla pierwotnego zakupu.

W tym wywołaniu należy też podać DeveloperBillingOptionParams. Nie wyświetla to ekranu wyboru użytkownika, ponieważ opcja wyboru w przypadku pierwotnego zakupu jest zachowywana w przypadku przejścia na wyższą i niższą wersję usługi. Musisz wygenerować nowy token transakcji zewnętrznej dla tej transakcji zgodnie z opisem tutaj.

Gdy przejście na wyższą lub niższą wersję usługi zostanie zakończone w witrynie dewelopera lub w aplikacji płatniczej, musisz zgłosić nową transakcję za pomocą tokena transakcji zewnętrznej uzyskanego w poprzednim wywołaniu w przypadku zakupu nowej subskrypcji.

Subskrypcje kupione za pomocą systemu rozliczeniowego Google Play

Podobnie użytkownicy, którzy kupili obecną subskrypcję za pomocą systemu rozliczeniowego Płatności w Google Play po wyborze użytkownika, powinni przejść przez standardowy proces Płatności w Google Play. W wywołaniu launchBillingFlow nie należy ustawiać DeveloperBillingOptionParams.

Anulowanie i przywracanie subskrypcji

Użytkownicy powinni mieć możliwość anulowania subskrypcji w dowolnym momencie. Gdy użytkownik anuluje subskrypcję, zakończenie uprawnienia może zostać odroczone do końca opłaconego okresu. 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 ok. 2 tygodnie, aż do momentu usunięcia dostępu. W tym okresie subskrypcja jest nadal technicznie aktywna, więc użytkownik może korzystać z usługi.

Nie jest niczym niezwykłym, że użytkownicy decydują się na cofnięcie anulowania w tym aktywnym okresie. W tym przewodniku nazywamy to przywróceniem. W kolejnych sekcjach opisujemy, jak obsługiwać scenariusze przywracania w integracji z interfejsem API płatności zewnętrznych.

Subskrypcje kupione w witrynie dewelopera

Jeśli masz identyfikator transakcji zewnętrznej dla anulowanej subskrypcji, nie musisz wywoływać launchBillingFlow() , aby przywrócić subskrypcję, więc nie należy go 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 kontynuować zgłaszanie odnowień, gdy bieżący cykl się skończy i nastąpi kolejne odnowienie. Dotyczy to przypadków, w których użytkownik otrzymuje środki lub specjalną cenę odnowienia w ramach przywrócenia (np. promocję zachęcającą użytkownika do kontynuowania subskrypcji).

Subskrypcje kupione za pomocą systemu rozliczeniowego Google Play

Zasadniczo użytkownicy mogą przywracać subskrypcje w systemie rozliczeniowym Google Play. W przypadku anulowanych subskrypcji, które zostały pierwotnie kupione za pomocą systemu rozliczeniowego Google Play, użytkownik może cofnąć anulowanie, gdy subskrypcja jest aktywna, za pomocą funkcji ponownej subskrypcji w Google Play. W takim przypadku otrzymasz w backendzie powiadomienie dewelopera w czasie rzeczywistym SUBSCRIPTION_RESTARTED, a nowy token zakupu nie zostanie wydany – do kontynuowania subskrypcji zostanie użyty pierwotny token. Aby dowiedzieć się, jak zarządzać przywracaniem w systemie rozliczeniowym Google Play, zapoznaj się z przewodnikiem zarządzania subskrypcjami w sekcji Przywracanie.

Możesz też wywołać przywrócenie w systemie rozliczeniowym Google Play z aplikacji, wywołując 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 jest nadal aktywny), system automatycznie wykrywa ich wybór i wyświetla interfejs przywracania tych zakupów. Użytkownicy są proszeni o potwierdzenie ponownego zakupu subskrypcji w Google Play, ale nie muszą ponownie przechodzić przez proces wyboru użytkownika. W tym przypadku użytkownik otrzymuje nowy token zakupu. Twój backend otrzymuje powiadomienie dewelopera w czasie rzeczywistym SUBSCRIPTION_PURCHASED, a wartość linkedPurchaseToken dla nowego stanu zakupu jest ustawiana tak jak w przypadku przejścia na wyższą lub niższą wersję usługi, ze starym tokenem zakupu anulowanej subskrypcji.

Ponowne subskrypcje

Jeśli subskrypcja całkowicie wygaśnie (z powodu anulowania lub odrzucenia płatności bez możliwości odzyskania środków – wygasłe zawieszenie konta), użytkownik musi ponownie subskrybować, jeśli chce ponownie uzyskać uprawnienie.

Ponowną subskrypcję można też włączyć w aplikacji, przetwarzając ją podobnie jak standardową rejestrację. Użytkownicy powinni mieć możliwość wyboru systemu rozliczeniowego, którego chcą używać. launchBillingFlow() można wywołać w tym przypadku, zgodnie z opisem w sekcji Uruchamianie procesu płatności zewnętrznych.

Obsługa odpowiedzi

Gdy wystąpi błąd, metody isBillingProgramAvailableAsync() , createBillingProgramReportingDetailsAsync(), launchBillingFlow() mogą zwrócić BillingResponseCode inny niż BillingResponseCode.OK. Rozważ obsługę tych kodów odpowiedzi w ten sposób:

  • BillingResponseCode.ERROR: to błąd wewnętrzny. Nie kontynuuj transakcji ani otwierania zewnętrznej witryny. Spróbuj ponownie, wywołując interfejs API.
  • BillingResponseCode.FEATURE_NOT_SUPPORTED: interfejsy API płatności zewnętrznych nie są obsługiwane przez Sklep Play na bieżącym urządzeniu. Nie kontynuuj transakcji ani otwierania zewnętrznej witryny.
  • BillingResponseCode.DEVELOPER_ERROR: wystąpił błąd w żądaniu. Przed kontynuowaniem użyj komunikatu debugowania, aby zidentyfikować i poprawić błąd.
  • BillingResponseCode.USER_CANCELED: nie kontynuuj otwierania zewnętrznej witryny ani aplikacji. Przy następnej próbie przekierowania użytkownika poza aplikację ponownie wywołaj launchBillingFlow(), aby wyświetlić użytkownikowi okno informacyjne.
  • BillingResponseCode.BILLING_UNAVAILABLE: transakcja nie kwalifikuje się do płatności zewnętrznych, dlatego rozliczenia dewelopera nie będą dostępne w ramach tego programu. Może to być spowodowane tym, że użytkownik nie znajduje się w kraju kwalifikującym się do tego programu lub Twoje konto nie zostało zarejestrowane w programie. Jeśli wystąpił ten drugi przypadek, sprawdź stan rejestracji w Konsoli Play.
  • BillingResponseCode.NETWORK_ERROR, BillingResponseCode.SERVICE_DISCONNECTED, BillingResponseCode.SERVICE_UNAVAILABLE: są to przejściowe błędy, które należy obsługiwać za pomocą odpowiedniej polityki ponawiania. W przypadku SERVICE_DISCONNECTED przed ponowieniem próby ponownie nawiąż połączenie z Google Play.

Testowanie zewnętrznych linków do płatności

Do testowania integracji płatności zewnętrznych należy używać testerów licencji. Nie otrzymasz faktury za transakcje zainicjowane przez konta testerów licencji. Więcej informacji o konfigurowaniu testerów licencji znajdziesz w sekcji Testowanie rozliczeń w aplikacji za pomocą licencjonowania.

Dalsze kroki

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