Otrzymuj płatności za pomocą Płatności w Google Play oraz korzystaj z interfejsów Digital Goods API i Payment Request API

André Cipriani Bandarra
André Cipriani Bandarra
Twitter GitHub Glitch Mastodon strona główna

Jeśli Twoja aplikacja jest rozpowszechniana przez Google Play i chcesz sprzedawać produkty cyfrowe lub oferować subskrypcje, musisz korzystać z Płatności w Google Play. Płatności w Google Play zapewniają narzędzia do zarządzania katalogiem, cenami i subskrypcjami, przydatne raporty i proces płatności znane ze Sklepu Play.

W przypadku aplikacji utworzonych przy użyciu zaufanych aktywności w internecie i dostarczanych za pomocą Sklepu Google Play możesz teraz używać interfejsów Payment Request API i Digital Goods API do integracji z Płatnościami w Google Play. Jest dostępna w Chrome 101 i nowszych wersjach na Androida i ChromeOS.

Z tego przewodnika dowiesz się, jak dodać obsługę Płatności w Google Play do swojej aplikacji PWA i spakować ją do dystrybucji w Sklepie Google Play dla systemu ChromeOS i Sklepu Play.

Aby dodać do swojej aplikacji PWA obsługę Płatności w Play, użyjesz 2 interfejsów API platform internetowych. Interfejs Digital Goods API służy do zbierania informacji o kodach SKU i sprawdzania zakupów i uprawnień w Sklepie Play. Payment Request API służy do konfigurowania Sklepu Google Play jako formy płatności i do sfinalizowania procesu zakupu.

Jak zarabiać na aplikacjach w Sklepie Play

Korzystając z Płatności w Sklepie Play, możesz zarabiać na swojej aplikacji na 2 sposoby:

  • Zakupy w aplikacji umożliwiają sprzedaż trwałych i użytkowych towarów wirtualnych, takich jak dodatkowe funkcje czy usuwanie reklam.
  • Subskrypcje: oferują użytkownikom stały dostęp do treści lub usług, takich jak subskrypcje wiadomości czy subskrypcje, za cykliczną opłatę.

Wymagania

Aby skonfigurować Płatności w Google Play, potrzebujesz:

Aktualizowanie projektu Bubblewrap

Jeśli nie masz zainstalowanej folii bąbelkowej, musisz ją zainstalować. Szczegółowe informacje o tym, jak zacząć, znajdziesz w krótkim przewodniku. Jeśli masz już Bubblewrap, zaktualizuj go do wersji 1.8.2 lub nowszej.

Ta funkcja jest również dostępna za pomocą flagi. Aby go włączyć, zmodyfikuj konfigurację projektu w pliku twa-manifest.json w katalogu głównym projektu i włącz funkcje alphaDependencies oraz playBilling:

  ...,
  "enableNotifications": true,
  "features": {
    "playBilling": {
      "enabled": true
    }
  },
  "alphaDependencies": {
    "enabled": true
  },
  ...

Po zaktualizowaniu pliku konfiguracji uruchom polecenie bubblewrap update, aby zastosować konfigurację w projekcie, a następnie polecenie bubblewrap build, aby wygenerować nowy pakiet na Androida i przesłać go do Sklepu Play.

Funkcja wykrywania dostępności interfejsu Digital Goods API i Płatności w Google Play

Chrome obsługuje obecnie interfejs Digital Goods API tylko wtedy, gdy aplikacja PWA jest wykonywana w ramach zaufanej aktywności w internecie. Można to sprawdzić, sprawdzając, czy w obiekcie window występuje getDigitalGoodsService.

if ('getDigitalGoodsService' in window) {
 // Digital Goods API is supported!
}

Interfejs Digital Goods API może być dostępny w dowolnej przeglądarce i obsługuje różne sklepy. Aby sprawdzić, czy dany backend sklepu jest obsługiwany, musisz wywołać getDigitalGoodsService(), przekazując jako parametr identyfikator sklepu. Sklep Google Play jest identyfikowany przez ciąg https://play.google.com/billing:

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
  try {
    const service =
        await window.getDigitalGoodsService('https://play.google.com/billing');
    // Google Play Billing is supported!

  } catch (error) {
    // Google Play Billing is not available. Use another payment flow.
    return;
  }
}

Pobieranie szczegółów kodu SKU

Interfejs Digital Goods API udostępnia interfejs getDetails(), który umożliwia pobieranie z backendu płatności takich informacji jak nazwa produktu, opis i – co najważniejsze – cena.

Następnie możesz wykorzystać te informacje w swoim interfejsie, by przekazać użytkownikowi więcej informacji:

const skuDetails = await service.getDetails(['shiny_sword', 'gem']);
for (item of skuDetails) {
  // Format the price according to the user locale.
  const localizedPrice = new Intl.NumberFormat(
      navigator.language,
      {style: 'currency', currency: item.price.currency}
    ).format(item.price.value);

  // Render the price to the UI.
  renderProductDetails(
        item.itemId, item.title, localizedPrice, item.description);
}

Tworzenie procesu zakupu

Konstruktor PaymentRequest przyjmuje 2 parametry: listę form płatności i listę szczegółów płatności.

W zaufanej aktywności w internecie musisz użyć formy płatności w Google Play, ustawiając https://play.google.com/billing jako identyfikator i dodając kod SKU produktu jako członka danych:

async function makePurchase(service, sku) {
   // Define the preferred payment method and item ID
   const paymentMethods = [{
       supportedMethods: "https://play.google.com/billing",
       data: {
           sku: sku,
       }
   }];

   ...
}

Mimo że dane do płatności są wymagane, Płatności w Play zignorują je i użyją wartości ustawionych podczas tworzenia kodu SKU w Konsoli Play, więc mogą zostać wypełnione fałszywymi wartościami:

const paymentDetails = {
    total: {
        label: `Total`,
        amount: {currency: `USD`, value: `0`}
    }
};

const request = new PaymentRequest(paymentMethods, paymentDetails);

Aby rozpocząć proces płatności, wywołaj show() w obiekcie żądania płatności. Jeśli obietnica się powiedzie, możemy zrealizować płatność. Jeśli płatność nie powiodła się, użytkownik prawdopodobnie przerwał płatność.

Jeśli obietnica się powiedzie, musisz potwierdzić i potwierdzić zakup. Aby chronić Cię przed oszustwami, musisz wdrożyć ten krok za pomocą backendu. Informacje o tym, jak wdrożyć weryfikację w backendzie, znajdziesz w dokumentacji dotyczącej Płatności w Play. Jeśli nie potwierdzisz zakupu, po 3 dniach użytkownik otrzyma zwrot środków, a Google Play anuluje zakup.

...
const request = new PaymentRequest(paymentMethods, paymentDetails);
try {
    const paymentResponse = await request.show();
    const {purchaseToken} = paymentResponse.details;

    // Call backend to validate and acknowledge the purchase.
    if (await acknowledgePurchaseOnBackend(purchaseToken, sku)) {
        // Optional: tell the PaymentRequest API the validation was
        // successful. The user-agent may show a "payment successful"
        // message to the user.
        const paymentComplete = await paymentResponse.complete('success');
    } else {
        // Optional: tell the PaymentRequest API the validation failed. The
        // user agent may show a message to the user.
        const paymentComplete = await paymentResponse.complete('fail');
    }
} catch(e) {
    // The purchase failed, and we can handle the failure here. AbortError
    // usually means a user cancellation
}
...

Opcjonalnie można wywołać consume() przy użyciu tokena purchase, aby oznaczyć zakup jako wykorzystany i umożliwić jego ponowne zakup.

Po połączeniu wszystkich elementów metoda zakupu wygląda tak:

async function makePurchase(service, sku) {
    // Define the preferred payment method and item ID
    const paymentMethods = [{
        supportedMethods: "https://play.google.com/billing",
        data: {
            sku: sku,
        }
    }];

    // The "total" member of the paymentDetails is required by the Payment
    // Request API, but is not used when using Google Play Billing. We can
    // set it up with bogus details.
    const paymentDetails = {
        total: {
            label: `Total`,
            amount: {currency: `USD`, value: `0`}
        }
    };

    const request = new PaymentRequest(paymentMethods, paymentDetails);
    try {
        const paymentResponse = await request.show();
        const {purchaseToken} = paymentResponse.details;

        // Call backend to validate and acknowledge the purchase.
        if (await acknowledgePurchaseOnBackend(purchaseToken, sku)) {
            // Optional: consume the purchase, allowing the user to purchase
            // the same item again.
            service.consume(purchaseToken);

            // Optional: tell the PaymentRequest API the validation was
            // successful. The user-agent may show a "payment successful"
            // message to the user.
            const paymentComplete =
                    await paymentResponse.complete('success');
        } else {
            // Optional: tell the PaymentRequest API the validation failed.
            // The user agent may show a message to the user.
            const paymentComplete = await paymentResponse.complete('fail');
        }
    } catch(e) {
        // The purchase failed, and we can handle the failure here.
        // AbortError usually means a user cancellation
    }
}

Sprawdzanie stanu obecnych zakupów

Interfejs Digital Goods API pozwala sprawdzić, czy użytkownik ma jakiekolwiek uprawnienia (dokonania jeszcze niezrealizowanego zakupu w aplikacji lub trwającej subskrypcji) z wcześniejszych zakupów, których dokonał na innym urządzeniu, z poprzedniej instalacji, z wykorzystaniem kodu promocyjnego czy podczas ostatniego uruchomienia aplikacji.


const service =
     await window.getDigitalGoodsService('https://play.google.com/billing');
...
const existingPurchases = await service.listPurchases();
for (const p of existingPurchases) {
    // Update the UI with items the user is already entitled to.
    console.log(`Users has entitlement for ${p.itemId}`);
}

To także dobry moment, aby sprawdzić, czy zakup został już dokonany, ale nie został potwierdzony. Jeśli chcesz, aby uprawnienia użytkowników były prawidłowo odzwierciedlane w aplikacji, zalecamy jak najszybsze potwierdzanie zakupów.

const service =
     await window.getDigitalGoodsService("https://play.google.com/billing");
...
const existingPurchases = await service.listPurchases();
for (const p of existingPurchases) {
    await verifyOrAcknowledgePurchaseOnBackend(p.purchaseToken, p.itemId);

    // Update the UI with items the user is already entitled to.
    console.log(`Users has entitlement for ${p.itemId}`);
}

Testowanie integracji

Na urządzeniu z Androidem deweloperskim

Na używanym urządzeniu z Androidem możesz włączyć interfejs Digital Goods API do testowania:

  • Upewnij się, że używasz Androida 9 lub nowszego i włączony tryb programisty.
  • Zainstaluj Chrome 101 lub nowszą wersję.
  • Aby włączyć te flagi w Chrome, otwórz chrome://flags i wyszukaj flagę według nazwy:
    • #enable-debug-for-store-billing
  • Upewnij się, że witryna jest hostowana przy użyciu protokołu https. Użycie protokołu http spowoduje, że interfejs API będzie miał wartość undefined

Na urządzeniu z ChromeOS

Interfejs Digital Goods API będzie dostępny w systemie stabilnym ChromeOS od wersji 89. Tymczasem interfejs Digital Goods API jest dostępny do testowania:

  • Zainstaluj aplikację ze Sklepu Play na urządzeniu.
  • Upewnij się, że witryna jest hostowana przy użyciu protokołu https. Użycie protokołu http spowoduje, że interfejs API będzie miał wartość undefined

Użytkownicy testowi i zespoły kontroli jakości

Sklep Play udostępnia opcje testowania, m.in. konta testowe użytkowników i testowe kody SKU. Więcej informacji znajdziesz w dokumentacji dotyczącej testowania Płatności w Google Play.

Co dalej?

Jak wspomnieliśmy w tym dokumencie, interfejs Play Billing API wykorzystuje komponenty po stronie klienta, którymi zarządza się za pomocą interfejsu Digital Goods API oraz komponentów po stronie serwera.