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

Jeśli aplikacja jest rozpowszechniana w Google Play i chcesz sprzedawać produkty cyfrowe lub oferować subskrypcje, musisz korzystać z systemu Płatności w Google Play. Płatności w Google Play to narzędzia do zarządzania katalogiem, cenami i subskrypcjami, przydatne raporty oraz proces płatności obsługiwany przez Sklep Play, który jest już znany użytkownikom.

W przypadku aplikacji utworzonych za pomocą zaufanych działań w internecie i rozpowszechnianych w Sklepie Google Play możesz teraz używać interfejsu API żądania płatności i interfejsu API dotyczących towarów cyfrowych do integracji z systemem płatności Google Play. Jest dostępna w Chrome 101 lub nowszej na Androida i ChromeOS.

Z tego przewodnika dowiesz się, jak dodać do PWA obsługę płatności Google Play i przekazać ją do dystrybucji w Sklepie Google Play na ChromeOS i w Sklepie Play.

Aby dodać do PWA obsługę płatności w Google Play, użyjesz 2 interfejsów API platformy internetowej. Interfejs Digital Goods API służy do zbierania informacji o kodzie SKU oraz sprawdzania zakupów i uprawnień w Sklepie Play. Interfejs Payment Request API służy do konfigurowania sklepu Google Play jako formy płatności i do przeprowadzania procesu zakupu.

Jak zarabiać na aplikacjach w Sklepie Play

Aplikacja może zarabiać w Sklepie Play za pomocą systemu Google Play Billing na 2 sposoby:

  • Zakupy w aplikacji umożliwiają sprzedaż zarówno trwałych, jak i zużywalnych produktów wirtualnych, np. dodatkowych funkcji lub usuwania reklam.
  • Subskrypcje – oferują użytkownikom stały dostęp do treści lub usług za stałą opłatą, na przykład w ramach subskrypcji wiadomości lub członkostwa.

Wymagania

Aby skonfigurować Płatności Google Play, musisz mieć:

Aktualizacja projektu Bubblewrap

Jeśli nie masz zainstalowanej aplikacji Bubblewrap, 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.

Bubblewrap również ma tę funkcję za pomocą flagi. Aby to zrobić, musisz zmodyfikować konfigurację projektu w pliku twa-manifest.json, który znajduje się w katalogu głównym projektu. Włącz w nim zarówno funkcję alphaDependencies, jak i funkcję 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 Androida i przesłać go do Sklepu Play.

Funkcja wykrywania dostępności interfejsu Digital Goods API i rozliczeń w Google Play

Interfejs API cyfrowych towarów jest obecnie obsługiwany przez Chrome tylko wtedy, gdy PWA jest wykonywana w ramach zaufanej aktywności w internecie. Można wykryć, czy jest ona dostępna, sprawdzając, czy obiekt getDigitalGoodsService zawiera wartość getDigitalGoodsService:window

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

Interfejs API cyfrowych towarów może być dostępny w dowolnej przeglądarce i obsługiwać różne sklepy. Aby sprawdzić, czy obsługiwany jest backend konkretnego sklepu, musisz wywołać funkcję getDigitalGoodsService(), podając identyfikator sklepu jako parametr. Sklep Google Play jest identyfikowany przez ciąg znaków 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 API cyfrowych towarów udostępnia funkcję getDetails(), która umożliwia pobieranie z backendu płatności takich informacji jak tytuł produktu, opis i, co najważniejsze, cena.

Możesz następnie użyć tych informacji w interfejsie i przekazać użytkownikowi więcej szczegółów:

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 żądania płatności przyjmuje 2 parametry: listę form płatności i listę szczegółów płatności.

W ramach zaufanej aktywności w internecie musisz używać formy płatności w Google Play. Aby to zrobić, ustaw https://play.google.com/billing jako identyfikator i dodaj identyfikator SKU produktu jako element 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 szczegóły płatności są wymagane, system płatności Google Play zignoruje te wartości i użyje wartości ustawionych podczas tworzenia kodu SKU w Konsoli Play. Dlatego te pola można wypełnić 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 funkcję show() w obiekcie żądania płatności. Jeśli obietnica się powiedzie, może to oznaczać, że płatność została zrealizowana. Jeśli się nie powiedzie, prawdopodobnie użytkownik przerwał płatność.

Jeśli obietnica się powiedzie, musisz potwierdzić zakup. Aby chronić się przed oszustwami, musisz wdrożyć ten krok na swoim backendzie. Aby dowiedzieć się, jak zaimplementować weryfikację na zapleczu, zapoznaj się z dokumentacją dotyczącą płatności w Google Play. Jeśli nie potwierdzisz zakupu, po 3 dniach użytkownik otrzyma zwrot środków, a Google Play unieważni 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ć metodę consume() z parametrem purchaseToken, aby oznaczyć zakup jako wykorzystany i zezwolić na jego ponowne zakupienie.

Połączenie wszystkich elementów tworzy metodę zakupu:

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 dotychczasowych zakupów

Interfejs API cyfrowych towarów pozwala sprawdzić, czy użytkownik ma jakieś uprawnienia (zakupy w aplikacji, które nie zostały jeszcze wykorzystane, lub bieżące subskrypcje) z wcześniejszych zakupów, niezależnie od tego, czy zostały one dokonane na innym urządzeniu, w ramach poprzedniej instalacji, przy użyciu kodu promocyjnego czy podczas ostatniego otwierania 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 też dobry moment na sprawdzenie, czy nie ma zakupów, które zostały wcześniej dokonane, ale nie zostały potwierdzone. Zalecamy jak najszybsze potwierdzanie zakupów, aby uprawnienia użytkowników były prawidłowo odzwierciedlane w aplikacji.

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 przeznaczonym do testowania

Aby przetestować interfejs API cyfrowych towarów, możesz go włączyć na urządzeniu deweloperskim z Androidem:

  • Upewnij się, że masz zainstalowany Android 9 lub nowszy z włączonym trybem programisty.
  • Zainstaluj Chrome w wersji 101 lub nowszej.
  • Włącz te flagi w Chrome, przechodząc na stronę chrome://flags i wyszukując flagę według nazwy:
    • #enable-debug-for-store-billing
  • Upewnij się, że witryna jest hostowana przy użyciu protokołu https. Korzystanie z http spowoduje, że interfejs API będzie undefined

Na urządzeniu z ChromeOS

Interfejs API cyfrowych towarów będzie dostępny w ChromeOS w stabilnej wersji od wersji 89. W międzyczasie możesz przetestować interfejs API cyfrowych towarów:

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

z użytkownikami testowymi i zespołami ds. kontroli jakości;

Sklep Play udostępnia funkcje testowania, w tym konta testowe użytkowników i testowe kody SKU. Więcej informacji znajdziesz w dokumentacji dotyczącej testów płatności w Google Play.

Co dalej?

Jak opisano w tym dokumencie, interfejs Play Billing API ma komponenty po stronie klienta, którymi zarządza interfejs API cyfrowych towarów, oraz komponenty po stronie serwera.