Wdrażanie płatności w Google Play w progresywnej aplikacji internetowej

Jeśli Twoja progresywna aplikacja internetowa jest dostępna w Google Play i chcesz na niej zarabiać, sprzedając produkty w aplikacji lub subskrypcje, zasady Google Play będą wymagać wdrożenia Płatności w Google Play. W progresywnej aplikacji internetowej musisz zaimplementować 2 interfejsy API: Digital Goods API i Payment Request API.

Digital Goods API

Digital Goods API to interfejs między Twoją aplikacją a Google Play. Umożliwia pobieranie produktów cyfrowych i szczegółów wprowadzonych w Konsoli Play w przypadku produktów w aplikacji i subskrypcji, a także pobieranie informacji o zakupach dokonanych przez użytkownika. Jeśli nie masz jeszcze produktów w aplikacji ani subskrypcji w Konsoli Play, zapoznaj się z konfiguracją Konsoli Play na potrzeby rozliczeń w Google Play.

30 listopada 2021 r. wydaliśmy ChromeOS 96 z implementacją interfejsu Digital Goods API 2.0.

Testowanie origin pierwszej wersji interfejsu Digital Goods API zakończyło się 30 stycznia 2022 r. Dlatego jest on obecnie wycofany i dostępna jest tylko wersja 2 interfejsu API.

23 czerwca 2022 r. wydaliśmy ChromeOS 103 z implementacją interfejsu Digital Goods API 2.1. Ta wersja nie zawiera żadnych zmian powodujących niezgodność wsteczną, a jedynie nowe metody i pola dodatkowe: listPurchaseHistory() i itemType.

Rejestracja w programie testowania origin

Uwaga: interfejs Digital Goods API jest obecnie dostępny w ramach testu pochodzenia – mechanizmu, który umożliwia deweloperom wcześniejszy dostęp do nowych interfejsów Web API. Musisz zarejestrować się w ramach testu pochodzenia interfejsu Digital Goods API w wersji 2 i poprosić o token, który musisz podawać na wszystkich stronach w swojej domenie.

Po zarejestrowaniu się w programie testów pochodzenia zobaczysz datę „Ważne do”, do której token będzie działać. Pamiętaj, aby odnowić tokeny, gdy zbliża się data ich wygaśnięcia, aby nadal uczestniczyć w okresie próbnym. Interfejsy API oferowane w ramach testów pochodzenia mogą ulec zmianie, dlatego warto być na bieżąco z najnowszymi zmianami w każdym teście pochodzenia, w którym uczestniczysz. W razie problemów zapoznaj się z dokumentacją interfejsu Digital Goods API.

Payment Request API

Payment Request API obsługuje rzeczywistą transakcję płatności, gdy dokonywany jest zakup. Wykorzystuje ona szczegóły produktu dostarczone przez Digital Goods API, aby dokonać zakupu w aplikacji za pomocą odpowiedniej formy płatności, w naszym przypadku systemu rozliczeniowego Google Play.

Wykrywanie funkcji interfejsu Digital Goods API

Możesz sprawdzić, czy interfejs API został prawidłowo włączony w Twojej witrynie w ramach testu origin, sprawdzając, czy w obiekcie window znajduje się metoda getDigitalGoodsService.

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
} else {
  console.log('DigitalGoodsService is not available.');
  // Use another payment method
}

Łączenie z usługą rozliczeniową Google Play

Interfejs Digital Goods API został zaprojektowany tak, aby był zgodny z różnymi przeglądarkami i sklepami cyfrowymi, podobnie jak interfejs Payment Request API, który jest niezależny od przeglądarki i może być używany z różnymi dostawcami płatności. Aby uzyskać instancję usługi powiązanej z płatnościami w Google Play, przekaż ciąg znaków "https://play.google.com/billing" jako formę płatności do funkcji getDigitalGoodsService().

Jeśli metoda zwróci błąd, forma płatności w Płatnościach w Google Play jest niedostępna (np. użytkownik uzyskuje dostęp do Twojej progresywnej aplikacji internetowej w przeglądarce). Zamiast tego powinieneś oferować inną formę płatności za transakcje.

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
  try {
    const service = await window.getDigitalGoodsService('https://play.google.com/billing');
    // Google Play Billing service is available
  } catch (error) {
    // Google Play Billing service is not available. Use another payment flow.
  }
}

Wyświetlanie szczegółów produktu

Po połączeniu usługi Towary cyfrowe z Google Play możesz używać interfejsu API do pobierania informacji o produktach i zakupach.

Metoda getDetails() umożliwia uzyskiwanie informacji o produktach skonfigurowanych w Konsoli Play. Informacje takie jak tytuł produktu, opis i cena powinny być wyświetlane użytkownikowi w interfejsie aplikacji, aby wiedział, co jest dostępne do zakupu i za ile.

getDetails() wymaga listy identyfikatorów produktów, które odpowiadają identyfikatorom produktów w aplikacji i subskrypcji utworzonych w Konsoli Play.

const itemDetails = await service.getDetails(['product_1', 'product_2', 'product_3']);
for (const item of itemDetails) {
  // Display item information to user
  displayItem(item.title, item.description, item.price);
}

Aby uzyskać odpowiednią cenę dla lokalizacji użytkownika, musisz zastosować dodatkowe formatowanie:

const localePrice = new Intl.NumberFormat(navigator.language, {
  style: 'currency',
  currency: item.price.currency,
}).format(item.price.value);

Uwaga: interfejs Digital Goods API nie udostępnia metody pobierania listy identyfikatorów produktów. Zamiast tego musisz zakodować je na stałe w aplikacji klienta lub pobrać z serwera backendu. Interfejs Google Play Developer API umożliwia wysyłanie zapytań o listę identyfikatorów produktów z backendu. (Więcej informacji o wdrażaniu kluczowych komponentów Płatności w Google Play na serwerze backendowym. Niezależnie od wybranego rozwiązania upewnij się, że identyfikatory produktów są zgodne z tymi w Konsoli Play.

W wersji 2.1 interfejsu API jednym z pól zwracanych przez getDetails() jest itemType. Jest to wyliczenie, w którym wartość ”product” oznacza produkt w aplikacji, a wartość ”subscription” oznacza subskrypcję. Możliwość rozróżniania tych dwóch typów produktów może być przydatna, jeśli chcesz zastosować różne metody w przypadku każdego typu produktu. Możesz na przykład mieć osobną stronę dla użytkowników, którzy chcą się zarejestrować, i inną stronę dla pozostałych produktów, które nie wymagają subskrypcji. Jest to też przydatne, aby poznać odpowiednie zasoby interfejsu Google Play Developer API REST, których możesz używać w backendzie (purchases.products lub purchases.subscriptions).

Kupowanie produktu

Gdy użytkownik zobaczy Twoje produkty i szczegóły, możesz utworzyć proces zakupu za pomocą interfejsu Payment Request API. W przypadku używania w połączeniu z interfejsem Digital Goods API wymagany jest tylko 1 parametr wejściowy: methodData.

System rozliczeniowy Google Play umożliwia zakup tylko jednego produktu naraz. Cena i szczegóły produktu są już znane serwerowi Google Play, więc parametr details nie jest potrzebny. Bardziej szczegółowe wyjaśnienie znajdziesz w tym artykule.

Użyj parametru supportedMethods member w parametrze methodData w parametrze PaymentRequest, aby zidentyfikować Płatności w Google Play jako formę płatności za pomocą ciągu znaków "https://play.google.com/billing". Następnie w parametrze data przekaż identyfikator produktu jako sku.

const paymentMethodData = [
  {
    supportedMethods: 'https://play.google.com/billing',
    data: {
      sku: item.itemId,
    },
  },
];

Następnie utwórz żądanie płatności i wywołaj interfejs show(), aby rozpocząć proces płatności:

const request = new PaymentRequest(paymentMethodData);
const paymentResponse = await request.show();

Wyświetli to interfejs zakupu w Google Play, w którym użytkownik zobaczy szczegóły produktu, który chce kupić. Mogą zrezygnować z transakcji lub dokonać płatności. Jeśli użytkownik anuluje płatność, obietnica zwrócona przez show() zostanie odrzucona z błędem. Jeśli użytkownikowi uda się zapłacić i sfinalizować zakup, obietnica zostanie spełniona i zwróci wartość PaymentResponse. W właściwości details odpowiedzi dotyczącej płatności zwracany jest token zakupu.

Aby zapobiec oszustwom, musisz zweryfikować zakup i token zakupu na serwerze backendu. Warto też śledzić użytkowników i powiązane z nimi tokeny zakupu. Dowiedz się, jak wdrożyć weryfikację na serwerze backendu.

Po zweryfikowaniu zakupu wywołaj funkcję complete() w odpowiedzi dotyczącej płatności, aby zakończyć proces płatności i zamknąć interfejs rozliczeniowy. Możesz też przekazać opcjonalny result ciąg znaków, aby wskazać stan procesu płatności. To przeglądarka decyduje, czy wyświetlić użytkownikowi informację o tym wyniku. Chrome nie tworzy żadnych widocznych dla użytkownika wskazówek, dlatego zalecamy wyświetlanie własnych komunikatów o błędach lub sukcesach w PWA.

/* Changes were recently made so that the PaymentResponse `details` property returns the purchase token as `purchaseToken` instead of `token`. Note that `token` will be deprecated at some point in the future. To ensure that your app won't be affected by this, make the change to `purchaseToken` in your client code and use the latest version of Bubblewrap (v1.13.5 and later) to update and generate a new app package to upload to the Play Console. */
const { purchaseToken } = paymentResponse.details;

let paymentComplete;
if (validatePurchaseOnBackend(purchaseToken)) {
  paymentComplete = await paymentResponse.complete('success');
  // Let user know their purchase transaction has successfully completed and been verified
} else {
  paymentComplete = await paymentResponse.complete('fail');
  // Let user know their purchase transaction failed to verify
}

Przechodzenie na wyższą lub niższą wersję subskrypcji

Proces zakupu jest taki sam w przypadku produktów w aplikacji i subskrypcji. W przypadku subskrypcji Google Play oferuje jednak dodatkowe opcje zakupu, które możesz wdrożyć: przejście na wyższą lub niższą wersję. Podczas tworzenia data dla formy płatności musisz przekazać te informacje, aby zainicjować proces przejścia na wyższy lub niższy pakiet:

  • sku: Jest to identyfikator produktu nowej subskrypcji, na którą ma zostać uaktualniona lub obniżona obecna subskrypcja.
  • oldSku: Jest to identyfikator produktu w bieżącej subskrypcji użytkownika.
  • purchaseToken: to token zakupu bieżącej subskrypcji użytkownika. Jak wspomnieliśmy wcześniej, warto śledzić tokeny zakupu na serwerze backendu. W tym i innych przypadkach należy też powiązać użytkownika z jego bieżącymi zakupami i tokenami zakupu.
  • prorationMode: w ten sposób zostanie naliczona opłata za nową subskrypcję, gdy zastąpi ona obecną subskrypcję użytkownika.
Tryb proporcjonalny Opis

immediateAndChargeProratedPrice

Subskrypcja zostanie od razu uaktualniona, a cykl rozliczeniowy pozostanie bez zmian. Różnica w cenie za pozostały okres zostanie następnie obciążona użytkownika.

immediateAndChargeFullPrice

Subskrypcja zostanie przeniesiona na wyższą lub niższą wersję, a użytkownik od razu zapłaci pełną cenę za nowe uprawnienia. Pozostała wartość poprzedniej subskrypcji jest proporcjonalnie przeliczana na czas trwania nowej subskrypcji. Ten tryb proporcjonalnego rozliczania został niedawno dodany w wersji 4.0 Biblioteki płatności w Google Play. Jest ona teraz dostępna w Bubblewrap od wersji 1.13.5.

immediateWithoutProration

CZASOWO WYŁĄCZONY W tym trybie proporcjonalnego rozliczania istnieje potencjalna możliwość oszustwa, w której użytkownicy mogą uzyskać wyższą subskrypcję bez dodatkowej płatności za jeden okres rozliczeniowy. Pamiętaj, że tymczasowo wyłączyliśmy ten tryb, aby móc pracować nad rozwiązaniem problemu.

immediateWithTimeProration

Subskrypcja zostanie natychmiast zmieniona na wyższą lub niższą wersję. Pozostały czas zostanie dostosowany na podstawie różnicy w cenie i dodany do nowej subskrypcji przez przesunięcie daty następnej płatności. Jest to zachowanie domyślne.

odroczone

Subskrypcja jest zmieniana na wyższą lub niższą wersję tylko w momencie jej odnowienia. Jest to szczególnie przydatne w przypadku obniżenia wersji.

unknownSubscriptionUpgradeDowngradePolicy

Brak ustawionych zasad. Nie jest to zalecane.

Więcej informacji o różnych trybach proporcjonalnego rozliczania znajdziesz w dokumentacji referencyjnej Biblioteki płatności w Google Play. Więcej informacji o aktualizacji i obniżaniu wersji subskrypcji oraz zaleceniach dotyczących trybu proporcjonalnego rozliczania znajdziesz w dokumentacji dla deweloperów aplikacji na Androida.

Użycie tych dodatkowych pól będzie wyglądać mniej więcej tak:

const paymentMethod = [
  {
    supportedMethods: 'https://play.google.com/billing',
    data: {
      sku: item.itemId,
      oldSku: oldPurchase.itemId,
      purchaseToken: oldPurchase.purchaseToken,
      prorationMode: 'immediateAndChargeProratedPrice',
    },
  },
];

W tym przypadku item to ItemDetails nowej subskrypcji, na którą użytkownik chce przejść, a oldPurchase to PurchaseDetails obecnej subskrypcji użytkownika.

Potwierdzanie zakupu

Po zakupie produktu przez użytkownika należy przyznać mu odpowiednie uprawnienia (dostęp do zakupionego produktu lub treści). Następnie potwierdź zakup. Potwierdzenie zakupu informuje Google Play, że zakup został odebrany i odpowiednio przetworzony.

Uwaga: jeśli zakup nie zostanie potwierdzony w ciągu 72 godzin od jego dokonania, płatność zostanie zwrócona użytkownikowi, a zakup zostanie anulowany. Token zakupu straci ważność, więc gdy zapytasz o istniejące zakupy, odwołany zakup nie zostanie zwrócony. Dzięki temu użytkownik nie zostanie nieprawidłowo obciążony w przypadku błędu sieci, który uniemożliwi mu uzyskanie dostępu do produktu.

Zakupy należy potwierdzać na serwerze backendu za pomocą interfejsu Google Play Developer API. Zalecamy przyznanie uprawnień i potwierdzenie zakupu na serwerze backendu.

  1. Gdy użytkownik dokona zakupu po stronie klienta, wyślij token zakupu i identyfikator produktu w żądaniu do serwera backendu.
  2. Aby uzyskać szczegóły zakupu i go zweryfikować, wywołaj na serwerze backendu to polecenie:
  3. Przyznaj odpowiednie uprawnienia w bazie danych backendu.
  4. Następnie potwierdź zakup, dzwoniąc pod numer:

Wykorzystanie zakupu

Gdy potwierdzisz zakup, Google Play będzie wiedzieć, że użytkownik jest właścicielem produktu i nie powinien mieć możliwości ponownego zakupu. Jeśli jest to produkt, który użytkownik musi kupić tylko raz i będzie go posiadać na zawsze (np. skórka postaci w grze), nie jest to produkt konsumpcyjny.

Może to być też produkt, który użytkownik może mieć tylko w jednej kopii. Następnie użytkownik musi wykorzystać produkt, zanim będzie mógł kupić kolejny. Gdy użytkownik „użyje” produktu, aby poinformować Google Play, że go wykorzystał, wywołaj metodę consume(). Google Play udostępni wtedy produkt użytkownikowi, aby mógł go ponownie kupić.

W przypadku produktów, których użytkownik może mieć wiele, musi on mieć możliwość wielokrotnego zakupu bez konieczności wcześniejszego użycia (nazywamy je produktami powtarzalnymi). Podobnie te produkty muszą zostać „wykorzystane”, zanim Google Play umożliwi użytkownikowi ponowny zakup. Dlatego nawet jeśli użytkownik nie użył jeszcze produktu, musisz wywołać metodę consume(), aby oznaczyć go jako wykorzystany.

// After the user purchases the item, send the purchase token and item ID to your backend to grant the entitlement and acknowledge it right away

. . .
// When the user uses the item or if it is a repeatable item, consume it so it’s available for purchase again.
service.consume(purchaseToken);
}

Sprawdzanie dotychczasowych zakupów

Ostatni kluczowy proces użytkownika to sprawdzenie istniejących zakupów (produktów w aplikacji, które nie zostały jeszcze wykorzystane, i aktywnych subskrypcji), aby poinformować użytkowników o posiadanych przez nich subskrypcjach lub produktach. Te istniejące zakupy to poprzednie zakupy w Google Play na dowolnym urządzeniu dokonane w aplikacji lub w Sklepie Play. Zakupy dokonane poza aplikacją w Sklepie Play nazywane są zakupami poza aplikacją.

Podczas pobierania istniejących zakupów należy też sprawdzić stan potwierdzenia i potwierdzić wszystkie zakupy, które zostały dokonane wcześniej, ale nie zostały prawidłowo potwierdzone. Zalecamy potwierdzanie zakupów jak najszybciej, aby uprawnienia użytkownika były aktualne i prawidłowo odzwierciedlone w aplikacji.

Metoda interfejsu Digital Goods API listPurchases() zwróci listę PurchaseDetails, która zawiera itemId i purchaseToken dla każdego zakupu. Aby sprawdzić stan zakupów i odpowiednio je potwierdzić, musisz użyć interfejsu Google Play Developer API na serwerze backendu. Wykonaj wtedy te czynności:

  1. Wywołaj po stronie klienta metodę listPurchases() interfejsu Digital Goods API, aby pobrać listę zakupów użytkownika.
  2. W przypadku każdego zakupu przekaż do backendu parametry purchaseToken i itemId.
  3. W razie potrzeby przyznaj uprawnienia w bazie danych backendu.
  4. Następnie zadzwoń i sprawdź acknowledgementState.
  5. Jeśli wartość wynosi 0 (jeszcze niepotwierdzona), wywołaj:

Dowiedz się więcej o tym, jak weryfikować zakupy na serwerze backendu przed przyznaniem uprawnień.

Historia zakupów

Funkcja listPurchases zwraca informacje o dotychczasowych zakupach użytkownika, a metoda listPurchaseHistory() (w wersji 2.1 interfejsu API) zwraca ostatni zakup dokonany przez użytkownika w przypadku każdego produktu, niezależnie od tego, czy zakup wygasł, został anulowany czy wykorzystany. Metoda listPurchaseHistory() zwraca listę PurchaseDetails zawierającą itemId i purchaseToken dla każdego zakupu. Musisz użyć tych informacji w interfejsie Google Play Developer API na serwerze backendu, aby uzyskać więcej informacji.

Zakupy poza aplikacją

Zakupy poza aplikacją to zakupy, które nie są dokonywane w ramach standardowego procesu zakupu w aplikacji. Zwykle odbywają się one w Sklepie Play, a nie w aplikacji. Użytkownicy mogą dokonać zakupu poza aplikacją na 2 główne sposoby:

  • Wykorzystanie kodu promocyjnego: w menu użytkownika Sklepu Play w sekcji „Oferty i powiadomienia” –> „Wykorzystaj kod promocyjny” lub w sekcji „Płatności i subskrypcje” –> „Wykorzystaj kod podarunkowy”.
  • Ponowna subskrypcja: w menu użytkownika Sklepu Play w sekcji „Płatności i subskrypcje” –> „Subskrypcje”. W tym miejscu użytkownicy mogą zarządzać wszystkimi subskrypcjami w różnych aplikacjach. W przypadku wygasłych lub anulowanych subskrypcji użytkownicy mają możliwość ponownego wykupienia subskrypcji.

Gdy użytkownicy ponownie subskrybują w Sklepie Play, ich zakupy nie są potwierdzane automatycznie, co może skutkować zwrotem środków. Jest to zamierzone działanie, ponieważ użytkownicy powinni być obciążani opłatą za subskrypcję tylko wtedy, gdy otworzą aplikację, aby z niej skorzystać. Użytkownik może zobaczyć komunikat „Potwierdź subskrypcję”, który przypomni mu o konieczności otwarcia aplikacji.

Użytkownicy są proszeni o potwierdzenie subskrypcji przez otwarcie aplikacji i potwierdzenie zakupu.

To Ty jako deweloper musisz wdrożyć potwierdzenie tych zakupów, gdy użytkownik uruchomi aplikację. Dlatego zalecamy sprawdzanie istniejących zakupów (zwykle przy pierwszym uruchomieniu aplikacji) i potwierdzanie wszystkich zakupów, które nie zostały jeszcze potwierdzone.

Umożliwianie użytkownikom zarządzania subskrypcjami

Aby zapewnić użytkownikom dobre wrażenia, ważne jest, aby mogli zarządzać subskrypcjami i je anulować w aplikacji. Zalecamy utworzenie na stronie ustawień lub w menu precyzyjnego linku, który przekieruje użytkownika do strony zarządzania subskrypcjami w Sklepie Play. Zastąp poniższy adres URL odpowiednimi wartościami „sub-product-id” i „app-package-name”:

https://play.google.com/store/account/subscriptions?sku=sub-product-id&package=app-package-name

Dalsze kroki

Te ścieżki użytkownika i fragmenty kodu to podstawowa implementacja, która pokazuje, jak używać interfejsów Digital Goods API i Payment Request API w progresywnej aplikacji internetowej do implementacji płatności w Google Play. Korzystaj z interfejsów API w sposób odpowiedni do kontekstu i przypadków użycia aplikacji. Przykład pełnej implementacji znajdziesz w naszym przykładowym kodzie open source.

Następnie sprawdź, jak wdrożyć kluczowe komponenty Płatności w Google Play na serwerze backendu, aby zapewnić bezpieczeństwo aplikacji i utrzymywać ją w aktualnym stanie w zakresie uprawnień użytkownika.