Wskazówki dotyczące integracji w aplikacji w przypadku linków do treści zewnętrznych

W tym dokumencie opisujemy, jak zintegrować interfejsy API Biblioteki płatności w Google Play, aby oferować linki do treści zewnętrznych w kwalifikujących się aplikacjach. Obejmuje to możliwość kierowania użytkowników w Stanach Zjednoczonych poza aplikację w Google Play, aby przedstawiać im oferty dotyczące cyfrowych treści w aplikacji i pobierania aplikacji. 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 Google Play do aplikacji na Androida. Aby korzystać z interfejsów API linków zewnętrznych, musisz używać wersji 8.2 lub nowszej. Jeśli musisz przejść z wcześniejszej wersji, przed dodaniem linków do treści zewnętrznych postępuj zgodnie z instrukcjami w przewodniku migracji.

Inicjowanie klienta płatności

Aby zainicjować klienta rozliczeniowego, wykonaj te same czynności, które opisano w sekcji Inicjowanie BillingClient, z tymi zmianami:

  • Nie włączaj PurchasesUpdatedListener – ten odbiornik nie jest potrzebny w przypadku linków do treści zewnętrznych.
  • Wywołaj funkcję enableBillingProgram() z parametrem BillingProgram.EXTERNAL_CONTENT_LINK, aby wskazać, że aplikacja korzysta z linków do treści zewnętrznych.

Poniższy przykład pokazuje inicjowanie BillingClient z tymi zmianami:

Kotlin

val billingClient = BillingClient.newBuilder(context)
  .enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
  .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .build();

Połącz z Google Play

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

Sprawdzanie, czy użytkownik spełnia wymagania

Po połączeniu z Google Play musisz sprawdzić, czy użytkownik kwalifikuje się do programu linków do treści zewnętrznych, wywołując metodę isBillingProgramAvailableAsync(). Ta metoda zwraca wartość BillingResponseCode.OK, jeśli użytkownik kwalifikuje się do programu linków do treści zewnętrznych. W przykładzie poniżej pokazujemy, jak sprawdzić, czy użytkownik kwalifikuje się do korzystania z linków do treści zewnętrznych:

Kotlin

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_CONTENT_LINK,
  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 content links unavailable, etc.
            return
        }

        // External content links are available. Prepare an external
        // transaction token.
      }
    })

Java

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_CONTENT_LINK,
  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 content links unavailable, etc.
            return;
        }

        // External content links are available. Prepare 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.

Przygotowywanie tokena transakcji zewnętrznej

Następnie musisz wygenerować token transakcji zewnętrznej z biblioteki Rozliczeń Play. Za każdym razem, gdy użytkownik odwiedza zewnętrzną witrynę za pomocą interfejsu External Links API, musi zostać wygenerowany nowy token transakcji zewnętrznej. Można to zrobić, wywołując interfejs API createBillingProgramReportingDetailsAsync. Token powinien być generowany bezpośrednio przed przekierowaniem użytkownika.

Uwaga: zewnętrzny token transakcji nie powinien być nigdy przechowywany w pamięci podręcznej. Za każdym razem, gdy użytkownik zostanie przekierowany, należy wygenerować nowy token.

Kotlin

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .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 when launchExternalLink is called.
    }
  })

Java

BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .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 when launchExternalLink is called.
      }
  });

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

Uruchamianie linku zewnętrznego

Gdy token transakcji zewnętrznej będzie gotowy, użytkownik może zostać przekierowany poza aplikację do oferty treści cyfrowych lub pobierania aplikacji przez wywołanie metody launchExternalLink. Gdy wywołasz ten interfejs API, Google Play może wyświetlić użytkownikowi dodatkowe okna dialogowe z informacjami w zależności od jego ustawień.

Podczas wywoływania metody launchExternalLink szczegóły linku zewnętrznego muszą być podane za pomocą parametru LaunchExternalLinkParams. Ta klasa zawiera te parametry:

  • Identyfikator URI linku – link do zewnętrznej witryny, w której oferowane są treści cyfrowe lub aplikacja do pobrania. W przypadku pobierania aplikacji ten link musi być zarejestrowany i zatwierdzony w Konsoli Play.
  • Typ linku – typ treści oferowanych użytkownikowi.
  • Tryb uruchamiania – określa sposób uruchamiania linku. W przypadku pobrań aplikacji musisz ustawić tę wartość na LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.

  • Program rozliczeniowy – ustaw tę opcję na BillingProgram.EXTERNAL_CONTENT_LINK.

Kotlin

val params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

val listener : LaunchExternalLinkResponseListener =
    object : LaunchExternalLinkResponseListener {
      override fun onLaunchExternalLinkResponse(
        billingResult: BillingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
}

billingClient.launchExternalLink(activity, params, listener)

Java

LaunchExternalLinkParams params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

LaunchExternalLinkResponseListener listener =
  new LaunchExternalLinkResponseListener() {
    @Override
    public void onLaunchExternalLinkResponse(BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
  }

billingClient.launchExternalLink(activity, params, listener);

Obsługa odpowiedzi

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

  • ERROR: To błąd wewnętrzny. Nie kontynuuj transakcji ani nie otwieraj zewnętrznej witryny. Spróbuj ponownie, wywołując interfejs API jeszcze raz lub wywołując launchExternalLink() przy następnej próbie przekierowania użytkownika poza aplikację.
  • FEATURE_NOT_SUPPORTED: interfejsy API linków do treści zewnętrznych nie są obsługiwane przez Sklep Play na bieżącym urządzeniu. Nie kontynuuj transakcji ani nie otwieraj zewnętrznej witryny.
  • USER_CANCELED: nie otwieraj zewnętrznej witryny. Przy kolejnej próbie przekierowania użytkownika poza aplikację wywołaj funkcję Call launchExternalLink().
  • BILLING_UNAVAILABLE: transakcja nie kwalifikuje się do linków do treści zewnętrznych, więc nie jest objęta tym programem. 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 obsługiwać za pomocą odpowiednich zasad ponawiania. W przypadku SERVICE_DISCONNECTED przed ponowną próbą nawiąż połączenie z Google Play.

Testowanie linków do treści zewnętrznych

Testerzy licencji powinni być używani do testowania integracji ofert zewnętrznych. 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.