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

Ten dokument opisuje, jak zintegrować interfejsy API Biblioteki płatności w 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 oferować im treści cyfrowe w aplikacji i pobieranie aplikacji. Więcej informacji o tym programie znajdziesz w sekcji Wymagania 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 linków zewnętrznych, musisz używać wersji 8.2.1 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 płatności, wykonaj te same czynności co w przypadku inicjowania BillingClient, ale z tymi zmianami:

  • Nie włączaj PurchasesUpdatedListener – ten odbiornik nie jest potrzebny w przypadku linków do treści zewnętrznych.
  • Wywołaj enableBillingProgram() z BillingProgram.EXTERNAL_CONTENT_LINK, aby wskazać, że Twoja 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 kwalifikuje się do programu

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(). Jeśli użytkownik kwalifikuje się do programu linków do treści zewnętrznych, ta metoda zwraca BillingResponseCode.OK. Poniższy przykład pokazuje, jak sprawdzić, czy użytkownik kwalifikuje się do programu 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 płatności w Play. Za każdym razem, gdy użytkownik odwiedza zewnętrzną witrynę za pomocą interfejsu API linków 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 przekierowaniem użytkownika.

Uwaga: tokena transakcji zewnętrznej nie należy nigdy zapisywać w pamięci podręcznej. Za każdym razem, gdy użytkownik jest przekierowywany, 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 jest gotowy, użytkownik może zostać przekierowany poza aplikację do oferty treści cyfrowych lub pobrania aplikacji przez wywołanie metody launchExternalLink. Gdy wywołasz ten interfejs API, Google Play może wyświetlić użytkownikowi dodatkowe okna informacyjne w zależności od jego ustawień.

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

  • Identyfikator URI linku – link do zewnętrznej witryny, w której oferowane są treści cyfrowe lub pobieranie aplikacji. 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 pobierania aplikacji musisz ustawić tę wartość na LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.

  • Program rozliczeniowy – ustaw tę wartość 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(), i createBillingProgramReportingDetailsAsync(), i onLaunchExternalLinkResponse() mogą zwrócić BillingResponseCode inny niż BillingResponseCode.OK. Rozważ obsługę tych kodów odpowiedzi w ten sposób:

  • ERROR: to błąd wewnętrzny. Nie kontynuuj transakcji ani otwierania zewnętrznej witryny. Spróbuj ponownie, wywołując interfejs API lub metodę 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 otwierania zewnętrznej witryny.
  • USER_CANCELED: nie kontynuuj otwierania zewnętrznej witryny. Przy następnej próbie przekierowania użytkownika poza aplikację ponownie wywołaj metodę launchExternalLink().
  • BILLING_UNAVAILABLE: transakcja nie kwalifikuje się do programu linków do treści zewnętrznych, dlatego nie kontynuuj jej w ramach tego programu. Może to być spowodowane tym, że użytkownik nie mieszka w kraju objętym tym programem lub Twoje konto nie zostało zarejestrowane w programie. Jeśli to drugie, sprawdź stan rejestracji w Konsoli Play.
  • DEVELOPER_ERROR: wystąpił błąd w żądaniu. Przed kontynuowaniem użyj komunikatu debugowania, aby zidentyfikować i poprawić błąd.
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: są to błędy przejściowe, które należy obsługiwać za pomocą odpowiedniej strategii ponawiania. W przypadku błędu SERVICE_DISCONNECTED przed ponowieniem próby ponownie nawiąż połączenie z Google Play.

Testowanie linków do treści zewnętrznych

Do testowania integracji ofert 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 .