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

Z tego przewodnika dowiesz się, jak przeprowadzić integrację z interfejsami API w celu obsługi ofert zewnętrznych w odpowiednich aplikacjach i regionach. Więcej informacji o programie ofert zewnętrznych, w tym o wymaganiach i zakresie geograficznym, znajdziesz w wymaganiach programu.

Konfiguracja Biblioteki płatności w Play

Aby korzystać z interfejsów API ofert zewnętrznych, dodaj do aplikacji na Androida zależność z Biblioteki płatności w Play w wersji 6.2.1 lub nowszej. Jeśli chcesz przeprowadzić migrację z wcześniejszej wersji, zanim spróbujesz wdrożyć oferty zewnętrzne, postępuj zgodnie z instrukcjami podanymi w przewodniku po migracji.

Połącz z Google Play

Pierwszy krok procesu integracji jest taki sam jak w przewodniku po integracji rozliczeń, ale przy inicjowaniu BillingClient występuje kilka zmian:

• Aby wskazać, że chcesz korzystać z ofert zewnętrznych, musisz wywołać nową metodę: enableExternalOffer.

Poniższy przykład pokazuje inicjowanie elementu BillingClient za pomocą tych modyfikacji:

var billingClient = BillingClient.newBuilder(context)
  .enableExternalOffer()
  .build()

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableExternalOffer()
    .build();

Po zainicjowaniu BillingClient musisz połączyć się z Google Play zgodnie z opisem w przewodniku po integracji.

Sprawdź dostępność

Aplikacja powinna potwierdzić dostępność ofert zewnętrznych, wywołując metodę isExternalOfferAvailableAsync.

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

billingClient.isExternalOfferAvailableAsync(
  object : ExternalOfferAvailabilityListener {
    override fun onExternalOfferAvailabilityResponse(
      billingResult: BillingResult) {
        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.
})

billingClient.isExternalOfferAvailableAsync(
  new ExternalOfferAvailabilityListener() {
    @Override
    public void onExternalOfferAvailabilityResponse(
      BillingResult billingResult) {
        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 zewnętrznego tokena transakcji

Aby zgłosić transakcję zewnętrzną w Google Play, musisz mieć zewnętrzny token transakcji wygenerowany w Bibliotece płatności w Play. Za każdym razem, gdy użytkownik odwiedza zewnętrzną witrynę za pomocą interfejsu API ofert zewnętrznych, musi być generowany nowy zewnętrzny token transakcji. Możesz to zrobić, wywołując interfejs API createExternalOfferReportingDetailsAsync. Token należy wygenerować bezpośrednio przed przekierowaniem użytkownika poza aplikację. Nie może on być zapisywany w pamięci podręcznej i powinien zostać wygenerowany nowy za każdym razem, gdy użytkownik zostanie przekierowany poza aplikację.

billingClient.createExternalOfferReportingDetailsAsync(
  object : ExternalOfferReportingDetailsListener {
    override fun onExternalOfferReportingDetailsResponse(
      billingResult: BillingResult,
      externalOfferReportingDetails: ExternalOfferReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            externalOfferReportingDetails?.externalTransactionToken
        // Persist the transaction token locally. Pass it to the external
        // website when showExternalOfferInformationDialog is called.
    }
})

billingClient.createExternalOfferReportingDetailsAsync(
  new ExternalOfferReportingDetailsListener() {
    @Override
    public void onExternalOfferReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable ExternalOfferReportingDetails
        externalOfferReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          externalOfferReportingDetails.getExternalTransactionToken();

        // Persist the external transaction token locally. Pass it to the
        // external website when showExternalOfferInformationDialog is
        // called.
      }
});

Okno z informacjami dla użytkowników

Aby można było przeprowadzić integrację z ofertami zewnętrznymi, kwalifikująca się aplikacja musi wyświetlać ekran z informacjami, który pomaga użytkownikom zrozumieć, że zostaną przekierowani poza nią do witryny zewnętrznej. Ekran z informacjami musi zostać wyświetlony użytkownikom przez wywołanie interfejsu API showExternalOfferInformationDialog przed każdorazowym połączeniem oferty zewnętrznej.

// An activity reference from which the external offers information dialog
// will be launched.
val activity : Activity = ...;

val listener : ExternalOfferInformationDialogListener =
  ExternalOfferInformationDialogListener {
      override fun onExternalOfferInformationDialogResponse(
        billingResult: BillingResult){
        // Check billingResult
    }
}

val billingResult = billingClient.showExternalOfferInformationDialog(
  activity, listener)

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

ExternalOfferInformationDialogListener listener =
  new ExternalOfferInformationDialogListener() {
    @Override
    public void onExternalOfferInformationDialogResponse(
      BillingResult billingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
          // Handle failures such as retrying due to network errors.
        }
        // Open the external website, passing along the external transaction
        // token as a URL parameter. If the user purchases an item, be sure
        // to report the transaction to Google Play.
      }
}

BillingResult billingResult =
  billingClient.showExternalOfferInformationDialog(activity, listener);

Jeśli ta metoda zwraca wartość BillingResponseCode.OK, aplikacja może przekierowywać użytkownika na stronę zewnętrzną. Jeśli metoda zwraca wartość BillingResponseCode.USER_CANCELED, aplikacja nie może dalej otwierać witryny.

Zgłaszanie transakcji w Google Play

Wszystkie transakcje zewnętrzne muszą być zgłaszane do Google Play przez wywołanie interfejsu Google Play Developer API z backendu. Transakcje zewnętrzne należy raportować wraz z podaniem parametru externalTransactionToken uzyskanego za pomocą interfejsu API createExternalOfferReportingDetailsAsync. Jeśli użytkownik dokonał kilku zakupów, możesz użyć tego samego atrybutu externalTransactionToken do raportowania każdego z nich. Aby dowiedzieć się, jak raportować transakcję, zapoznaj się z przewodnikiem po integracji backendu.

Obsługiwanie odpowiedzi

Gdy wystąpi błąd, metody isExternalOfferAvailableAsync, createExternalOfferReportingDetailsAsync i showExternalOfferInformationDialog mogą zwracać odpowiedzi inne niż BillingResponseCode.OK. Rozważ postępowanie z tymi kodami odpowiedzi w ten sposób:

• ERROR: to jest błąd wewnętrzny. Nie kontynuuj transakcji ani nie otwieraj zewnętrznej strony internetowej. Spróbuj ponownie, wywołując showExternalOfferInformationDialog(), aby wyświetlić użytkownikowi okno z informacjami, gdy następnym razem spróbujesz przekierować go na zewnątrz aplikacji.
• FEATURE_NOT_SUPPORTED: interfejsy API ofert zewnętrznych nie są obsługiwane przez Sklep Play na tym urządzeniu. Nie kontynuuj transakcji ani nie otwieraj zewnętrznej strony internetowej.
• USER_CANCELED: nie otwieraj witryny zewnętrznej. Wywołaj ponownie showExternalOfferInformationDialog(), aby wyświetlić użytkownikowi okno z informacjami przy następnej próbie przekierowania go poza aplikację.
• BILLING_UNAVAILABLE: transakcja nie kwalifikuje się do ofert zewnętrznych, więc nie powinna być kontynuowana w ramach tego programu. Wynika to z faktu, że użytkownik nie znajduje się w kraju kwalifikującym się do tego programu lub Twoje konto nie zostało do niego zarejestrowane. W przeciwnym razie sprawdź stan rejestracji w Konsoli Play.
• DEVELOPER_ERROR: wystąpił błąd z żądaniem. Zanim przejdziesz dalej, 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łużyć za pomocą odpowiedniej zasady ponawiania. W przypadku błędu SERVICE_DISCONNECTED ponownie połącz się z Google Play i spróbuj ponownie.

Testuj oferty zewnętrzne

Do przetestowania integracji ofert zewnętrznych należy używać testerów licencji. Nie obciążymy Cię płatnością 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 aplikacji.

Dalsze kroki

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