Wskazówki dotyczące integracji w aplikacji na potrzeby programu ofert zewnętrznych

W tym przewodniku opisujemy, jak zintegrować interfejsy API, aby obsługiwać oferty zewnętrzne w kwalifikujących się aplikacjach i regionach. Więcej informacji o programie ofert zewnętrznych w tym o wymaganiach kwalifikacyjnych i zasięgu geograficznym, znajdziesz w sekcji Wymagania programu.

Konfigurowanie Biblioteki płatności w Play

Aby korzystać z interfejsów API ofert zewnętrznych, dodaj do aplikacji na Androida zależność od Biblioteki płatności w Play w wersji 8.2.1 lub nowszej. Jeśli musisz przeprowadzić migrację ze starszej wersji, przed zaimplementowaniem ofert zewnętrznych postępuj zgodnie z instrukcjami w przewodniku migracji.

Połącz z Google Play

Pierwsze kroki procesu integracji są takie same jak te opisane w przewodniku integracji rozliczeń. Musisz jednak wywołać funkcję enableBillingProgram, aby wskazać, że chcesz korzystać z ofert zewnętrznych podczas inicjowania BillingClient:

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

Kotlin

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

Java

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

Po zainicjowaniu BillingClient musisz nawiązać połączenie z Google Play zgodnie z opisem w przewodniku integracji.

Sprawdź dostępność

Aby potwierdzić, że oferty zewnętrzne są dostępne dla bieżącego użytkownika, wywołaj funkcję isBillingProgramAvailableAsync.

Jeśli oferty zewnętrzne są dostępne, ten interfejs API zwraca BillingResponseCode.OK. Szczegółowe informacje o tym, jak aplikacja powinna reagować na inne kody odpowiedzi, znajdziesz w sekcji Obsługa odpowiedzi.

Kotlin


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

        // External offers are available. Continue with steps in the
        // guide.
      }
  })

Java


billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_OFFER,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      BillingResult billingResult,
      BillingProgramAvailabilityDetails billingProgramAvailabilityDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external offers being unavailable, etc.
            return;
        }
        // External offers are available. Continue with steps in the
        // guide.
      }
  });

Przygotuj token transakcji zewnętrznej

Aby zgłosić transakcję zewnętrzną do Google Play, musisz mieć token transakcji zewnętrznej wygenerowany przez Bibliotekę płatności w Play. Możesz go uzyskać, wywołując interfejs API createBillingProgramReportingDetailsAsync. Nowy token musi zostać wygenerowany bezpośrednio przed przekierowaniem użytkownika poza aplikację w przypadku każdej oferty zewnętrznej. Tokeny nie mogą być buforowane w różnych transakcjach.

Kotlin

val params =
  BillingProgramReportingDetailsParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .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 transaction token in your backend. You may pass it
        // to the external website when calling the launchExternalLink API.
    }
})

Java

BillingProgramReportingDetailsParams params =
  BillingProgramReportingDetailsParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .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 transaction token in your backend. You may pass it
        // to the external website when calling the launchExternalLink API.
      }
});

Możesz też wysłać zapytanie do funkcji zawieszenia createBillingProgramReportingDetailsAsync za pomocą rozszerzeń Kotlin, aby nie trzeba było definiować odbiornika:

  val createBillingProgramReportingDetailsResult =
    withContext(context) {
      billingClient
        .createBillingProgramReportingDetails(params)
    }
  // Process the result

Uruchom proces ofert zewnętrznych

Aby rozpocząć proces ofert zewnętrznych, kwalifikująca się aplikacja musi wywołać interfejs API launchExternalLink() z głównego wątku aplikacji. Ten interfejs API przyjmuje jako dane wejściowe obiekt LaunchExternalLinkParams. Aby utworzyć obiekt LaunchExternalLinkParams, użyj klasy LaunchExternalLinkParams.Builder. Ta klasa zawiera te parametry:

  • linkUri – link do zewnętrznej strony, na której oferowane są treści cyfrowe lub pobieranie aplikacji. W przypadku pobierania aplikacji ten link musi być zarejestrowany i zatwierdzony w Konsoli Play.
  • linkType – typ treści oferowanych użytkownikowi.
  • launchMode – określa sposób uruchamiania linku. W przypadku pobierania aplikacji musisz ustawić tę wartość na LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.
  • billingProgram – ustaw tę wartość na BillingProgram.EXTERNAL_OFFER.

Gdy wywołasz funkcję launchExternalLink(), może ona wyświetlać użytkownikowi dodatkowe okna informacyjne na podstawie jego ustawień. W zależności od parametru launchMode usługa Play uruchamia identyfikator URI linku w przeglądarce zewnętrznej lub przekierowuje proces do aplikacji, aby uruchomić identyfikator URI. W większości przypadków możesz użyć trybu LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, w którym usługa Play uruchomi identyfikator URI za Ciebie. Jeśli chcesz mieć bardziej dostosowane działanie, np. uruchamiać identyfikator URI w widoku WebView lub otwierać go w określonej przeglądarce, możesz użyć trybu CALLER_WILL_LAUNCH_LINK. Aby chronić prywatność użytkowników, upewnij się, że w identyfikatorze URI nie są przekazywane żadne informacje umożliwiające identyfikację.

wykonaj wszelkie niezbędne zadania w aplikacji.

Kotlin


// An activity reference from which the external offers flow will be launched.
val activity = ...;

val params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    // You can pass along the external transaction token from
    // BillingProgramReportingDetails as a URL parameter in the URI
    .setLinkUri(yourLinkUri)
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

val listener : LaunchExternalLinkResponseListener =
  LaunchExternalLinkResponseListener {
      override fun onLaunchExternalLinkResponse(billingResult: BillingResult) {
    if (billingResult.responseCode == BillingResponseCode.OK) {
      // Proceed with the rest of the external offer flow. If the user
      // purchases an item, be sure to report the transaction to Google Play.
    } else {
      // Handle failures such as retrying due to network errors.
    }
  }
}

billingClient.launchExternalLink(activity, params, listener)

Java


// An activity reference from which the external offers flow will be launched.
Activity activity = ...;

LaunchExternalLinkParams params = LaunchExternalLinkParams.newBuilder()
  .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
  // You can pass along the external transaction token from  
  // BillingProgramReportingDetails as a URL parameter in the URI
  .setLinkUri(yourLinkUri)
  .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.responseCode == BillingResponseCode.OK) {
        // Proceed with the rest of the external offer flow. If the user
        // purchases an item, be sure to report the transaction to Google
        // Play.
      } else {
        // Handle failures such as retrying due to network errors.
      }
    }
  }

billingClient.launchExternalLink(activity, params, listener);

Jeśli ustawisz LaunchMode na CALLER_WILL_LAUNCH_LINK, przekieruj użytkownika poza aplikację tylko wtedy, gdy funkcja onLaunchExternalLinkResponse zwróci wartość BillingResponseCode.OK.

Zgłaszanie transakcji do Google Play

Wszystkie transakcje zewnętrzne musisz zgłaszać do Google Play, wywołując interfejs Google Play Developer API z backendu. Gdy zgłaszasz a transakcję, musisz podać externalTransactionToken uzyskany z createBillingProgramReportingDetailsAsync interfejsu API. Jeśli użytkownik dokona kilku zakupów, możesz użyć tego samego externalTransactionToken, aby zgłosić każdy z nich. Więcej informacji o tym, jak zgłosić transakcję, znajdziesz w przewodniku integracji backendu.

Obsługa odpowiedzi

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

  • ERROR: jest to błąd wewnętrzny. Nie kontynuuj transakcji ani otwierania zewnętrznej strony. Spróbuj ponownie, wywołując funkcję launchExternalLink(), aby wyświetlić użytkownikowi okno informacyjne przy następnej próbie przekierowania go poza aplikację.
  • FEATURE_NOT_SUPPORTED: interfejsy API ofert zewnętrznych nie są obsługiwane przez Sklep Play na bieżącym urządzeniu. Nie kontynuuj transakcji ani otwierania zewnętrznej strony.
  • USER_CANCELED: nie kontynuuj otwierania zewnętrznej strony. Wywołaj ponownie funkcję launchExternalLink(), aby wyświetlić użytkownikowi okno informacyjne przy następnej próbie przekierowania go poza aplikację.
  • BILLING_UNAVAILABLE: transakcja nie kwalifikuje się do ofert zewnętrznych i dlatego nie powinna być realizowana 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 zidentyfikuj i popraw błąd za pomocą komunikatu debugowania.
  • 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 nawiąż ponownie połączenie z Google Play.

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

Dalsze kroki

Gdy skończysz integrację w aplikacji, możesz zintegrować backend.