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

Z tego przewodnika dowiesz się, jak przeprowadzić integrację z interfejsami API, aby obsługiwać oferty zewnętrzne w kwalifikujących się aplikacjach i regionach. Aby dowiedzieć się więcej o programie ofert zewnętrznych, w tym o wymaganiach i zakresie geograficznym, zapoznaj się z wymaganiami programu.

Konfiguracja Biblioteki płatności w Play

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

Połącz z Google Play

Pierwsze kroki procesu integracji są takie same jak te opisane w przewodniku po integracji rozliczeń. Musisz jednak wywołać 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 po integracji.

Sprawdź dostępność

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

Ten interfejs API zwraca wartość BillingResponseCode.OK, jeśli dostępne są oferty zewnętrzne. Więcej informacji 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.
      }
  });

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. Ten token możesz uzyskać, wywołując interfejs API createBillingProgramReportingDetailsAsync. Nowy token musi być generowany bezpośrednio przed przekierowaniem użytkownika poza aplikację w przypadku każdej oferty zewnętrznej. Tokeny nie mogą być buforowane w przypadku różnych transakcji.

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 zawieszania createBillingProgramReportingDetailsAsync za pomocą rozszerzeń Kotlin, aby nie trzeba było definiować detektora:

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

Uruchamianie procesu oferty zewnętrznej

Aby rozpocząć proces oferty zewnętrznej, kwalifikująca się aplikacja musi wywołać interfejs 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 aplikacja do pobrania. 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 pobrań aplikacji musisz ustawić tę wartość na LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.
  • billingProgram – ustaw wartość BillingProgram.EXTERNAL_OFFER.

Gdy wywołasz launchExternalLink(), w zależności od ustawień użytkownika mogą się wyświetlać dodatkowe okna z informacjami. W zależności od parametru launchMode Play uruchamia identyfikator URI linku w zewnętrznej przeglądarce lub przekazuje sterowanie z powrotem 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 Google Play uruchomi za Ciebie identyfikator URI. Jeśli chcesz dostosować działanie, np. uruchomić identyfikator URI w widoku internetowym lub otworzyć go w określonej przeglądarce, możesz użyć trybu CALLER_WILL_LAUNCH_LINK. Aby chronić prywatność użytkowników, dopilnuj, aby w URI nie były przekazywane żadne informacje umożliwiające identyfikację.

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 wartość LaunchMode na CALLER_WILL_LAUNCH_LINK, użytkownika należy przekierowywać poza aplikację tylko wtedy, gdy onLaunchExternalLinkResponse udostępnia 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. Podczas zgłaszania transakcji musisz podać externalTransactionToken uzyskany z interfejsu createBillingProgramReportingDetailsAsync API. Jeśli użytkownik dokona kilku zakupów, możesz użyć tego samego parametru externalTransactionToken, aby zgłosić każdy z nich. Aby dowiedzieć się, jak zgłosić transakcję, zapoznaj się z przewodnikiem po integracji z backendem.

Obsługa odpowiedzi

Gdy wystąpi błąd, metody isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync() i launchExternalLink() mogą zwracać odpowiedzi inne 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 launchExternalLink(), aby wyświetlić użytkownikowi okno informacji 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 nie otwieraj zewnętrznej witryny.
  • USER_CANCELED: nie otwieraj zewnętrznej witryny. Wywołaj funkcję Call launchExternalLink() ponownie, aby wyświetlić użytkownikowi okno informacji przy następnej próbie przekierowania go poza aplikację.
  • BILLING_UNAVAILABLE: transakcja nie kwalifikuje się do ofert zewnętrznych, dlatego nie powinna być realizowana w ramach tego programu. 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 ofert 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.