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:
Kotlin
var billingClient = BillingClient.newBuilder(context)
.enableExternalOffer()
.build()
Java
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.
Kotlin
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.
})
Java
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ę.
Kotlin
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.
}
})
Java
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.
Kotlin
// 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)
Java
// 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ącshowExternalOfferInformationDialog()
, 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 ponownieshowExternalOfferInformationDialog()
, 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łęduSERVICE_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.