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

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

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

Inicjowanie klienta płatności

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:

• Aby wskazać, że chcesz oferować płatności zewnętrzne, musisz wywołać nową metodę enableBillingProgram(EnableBillingProgramParams).
• Musisz zarejestrować DeveloperProvidedBillingListener, aby obsługiwać przypadki, w których użytkownik zdecyduje się zapłacić w Twojej witrynie lub aplikacji do płatności.

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

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()

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 instrukcjami w sekcji Łączenie z Google Play.

Sprawdzanie, czy użytkownik spełnia wymagania

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(). Ta metoda zwraca wartość BillingResponseCode.OK, jeśli użytkownik kwalifikuje się do skorzystania z tej funkcji. Poniższy przykład pokazuje, jak sprawdzić, czy się kwalifikujesz:

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.
})

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.
      }

    });

Więcej informacji 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

Możesz wyświetlać użytkownikowi dostępne produkty 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 zewnętrzny proces płatności zgodnie z opisem w sekcji dotyczącej uruchamiania zewnętrznego procesu płatności.

Przygotowywanie tokena transakcji zewnętrznej

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

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.
    }
})

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ć współprogramów Kotlin, aby nie musieć definiować osobnego odbiornika.

Uruchamianie procesu płatności zewnętrznych

Uruchom proces płatności zewnętrznych, wywołując funkcję launchBillingFlow(), podobnie jak uruchamiasz proces zakupu z integracją systemu rozliczeniowego 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 informacje:

• billingProgram ustawiony na program rozliczeniowy EXTERNAL_PAYMENTS
• linkURI ustawione na miejsce docelowe linku
• launchMode ustaw na LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, jeśli link ma być otwierany w Google Play, lub CALLER_WILL_LAUNCH_LINK, jeśli ma być otwierany w Twojej aplikacji.

Gdy aplikacja wywołuje funkcję launchBillingFlow() z podanym parametrem DeveloperBillingOptionParams, system rozliczeniowy Google Play przeprowadza następujące sprawdzenie:

• System sprawdza, 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 sprawdza, czy płatności zewnętrzne są włączone na podstawie konfiguracji BillingClient i czy podano wartość DeveloperBillingOptionParams.
  • Jeśli płatności zewnętrzne zostały włączone, w procesie zakupu wyświetla się 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 opcji wyboru przez użytkownika.
• 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.

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

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

DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .setLinkUri("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 zależy 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 do płatności

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

Jeśli Twoja aplikacja ustawi wartość launchMode na LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, Google Play uruchomi link. Jeśli wartość launchMode została ustawiona na CALLER_WILL_LAUNCH_LINK, za uruchomienie linku odpowiada aplikacja. Łącząc użytkowników z aplikacją do płatności, musisz sprawdzić, czy użytkownik ma już zainstalowaną aplikację do płatności na swoim urządzeniu.

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

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 płatności zewnętrznych zakupy muszą być przetwarzane w systemie rozliczeniowym Google Play lub zgłaszane za pomocą externalTransactionId, w zależności od wyboru użytkownika. Zmiany w istniejących subskrypcjach, które zostały przetworzone na stronie dewelopera, można wprowadzać w tym samym systemie rozliczeniowym do momentu wygaśnięcia subskrypcji.

W tej sekcji opisujemy, jak postępować w przypadku typowych scenariuszy zmian subskrypcji.

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

Zmiany pakietu subskrypcji, w tym przejście na wyższy lub niższy pakiet, powinny być obsługiwane w różny sposób w zależności od tego, czy subskrypcja została pierwotnie kupiona za pomocą systemu rozliczeniowego Google Play czy na stronie internetowej dewelopera.

Dodatki, które zależą 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, z którego chcą korzystać. Rozpocznij nowy proces zakupu za pomocą launchBillingFlow(), jak opisano w artykule uruchamianie procesu płatności zewnętrznych.

Subskrypcje kupione na stronie dewelopera lub w aplikacji do płatności

W przypadku subskrypcji, które zostały pierwotnie kupione w witrynie dewelopera lub w aplikacji do płatności po wyborze użytkownika, użytkownicy, którzy chcą przejść na wyższy lub niższy pakiet, powinni to zrobić w witrynie dewelopera lub w aplikacji do płatności bez ponownego przechodzenia przez proces wyboru.

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ć inne parametry w obiekcie SubscriptionUpdateParams, użyj setOriginalExternalTransactionId(), podając zewnętrzny identyfikator transakcji pierwotnego zakupu.

W tym wywołaniu musi być też podany parametr DeveloperBillingOptionParams. Nie wyświetla to ekranu wyboru użytkownika, ponieważ wybór użytkownika dotyczący pierwotnego zakupu jest zachowywany w przypadku uaktualnień i obniżeń wersji. Musisz wygenerować nowy token transakcji zewnętrznej dla tej transakcji zgodnie z opisem tutaj.

Gdy przejście na wyższą lub niższą wersję zostanie zakończone w witrynie dewelopera lub w aplikacji do płatności, musisz zgłosić nową transakcję, używając zewnętrznego tokena transakcji 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 Google Play po wyborze użytkownika, powinni przejść przez standardowy proces rozliczeniowy Google Play. W wywołaniu funkcji launchBillingFlow nie można ustawić parametru DeveloperBillingOptionParams.

Anulowanie i przywracanie subskrypcji

Użytkownicy powinni mieć możliwość anulowania subskrypcji w dowolnym momencie. Gdy użytkownik anuluje subskrypcję, zakończenie uprawnień 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, dopóki nie zostanie mu odebrany dostęp. W tym okresie subskrypcja jest nadal technicznie 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 sekcjach poniżej opisujemy, jak obsługiwać scenariusze przywracania w integracji interfejsu API płatności zewnętrznych.

Subskrypcje kupione w witrynie dewelopera

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 kontynuować raportowanie odnowień, gdy bieżący cykl wygaśnie i nastąpi kolejne odnowienie. Dotyczy to sytuacji, w których użytkownik otrzymuje środki lub specjalną cenę odnowienia w ramach przywracania (np. promocja zachęcająca użytkownika 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 w backendzie powiadomienie w czasie rzeczywistym SUBSCRIPTION_RESTARTED, a nowy token zakupu nie zostanie wydany – do kontynuowania subskrypcji używany jest oryginalny token. Aby dowiedzieć się, jak zarządzać przywracaniem w systemie rozliczeniowym Google Play, zapoznaj się z sekcją 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(). Więcej informacji o tym, 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 użytkownika do przywracania tych zakupów. Użytkownik zostanie poproszony o potwierdzenie ponownego zakupu subskrypcji w Google Play, ale nie musi ponownie przechodzić procesu wyboru. W tym przypadku użytkownik otrzyma nowy token zakupu. Twój backend otrzymuje powiadomienie w czasie rzeczywistym SUBSCRIPTION_PURCHASED, a wartość linkedPurchaseToken dla nowego stanu zakupu jest ustawiana tak jak w przypadku przejścia na wyższy lub niższy poziom, 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 (zawieszenie konta z powodu wygaśnięcia), użytkownik musi ponownie wykupić subskrypcję, jeśli chce ponownie uzyskać dostęp do usługi.

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, z którego chcą korzystać. W tym przypadku może zostać wywołana funkcja launchBillingFlow(), jak opisano w artykule Uruchamianie procesu płatności zewnętrznych.

Obsługa odpowiedzi

Gdy wystąpi błąd, metody isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync() i launchBillingFlow() mogą zwrócić wartość BillingResponseCode inną niż BillingResponseCode.OK. Te kody odpowiedzi możesz obsługiwać w ten sposób:

• BillingResponseCode.ERROR: to błąd wewnętrzny. Nie przeprowadzaj transakcji ani nie otwieraj 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 tym urządzeniu. Nie przeprowadzaj transakcji ani nie otwieraj zewnętrznej witryny.
• BillingResponseCode.DEVELOPER_ERROR: Wystąpił błąd w żądaniu. Skorzystaj z komunikatu debugowania, aby zidentyfikować i naprawić błąd przed kontynuowaniem.
• BillingResponseCode.USER_CANCELED: nie otwieraj zewnętrznej witryny ani aplikacji. Ponownie wywołaj funkcję launchBillingFlow(), aby następnym razem, gdy spróbujesz przekierować użytkownika poza aplikację, wyświetlić mu okno dialogowe z informacjami.
• BillingResponseCode.BILLING_UNAVAILABLE: transakcja nie kwalifikuje się do płatności zewnętrznych, więc 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, 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.
• BillingResponseCode.NETWORK_ERROR, BillingResponseCode.SERVICE_DISCONNECTED, BillingResponseCode.SERVICE_UNAVAILABLE: są to błędy przejściowe, które należy obsługiwać za pomocą odpowiedniej strategii ponawiania. W przypadku SERVICE_DISCONNECTED przed ponowną próbą nawiąż połączenie z Google Play.

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

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 artykule Testowanie rozliczeń w aplikacji za pomocą licencjonowania.

Dalsze kroki

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