Ricevi i pagamenti tramite Fatturazione Google Play con le API Digital Goods e Payment Request

André Cipriani Bandarra

Se la tua app è distribuita tramite Google Play e vuoi vendere beni digitali o offrire abbonati, devi utilizzare Fatturazione Google Play. La fatturazione di Google Play offre strumenti per gestire il tuo catalogo, i prezzi e gli abbonamenti, report utili e un flusso di pagamento basato sul Play Store già familiare ai tuoi utenti.

Per le app create utilizzando le Attività web attendibili e distribuite tramite il Google Play Store, ora puoi utilizzare l'API Payment Request e l'API Digital Goods per l'integrazione con la fatturazione di Google Play. È disponibile su Chrome 101 e versioni successive per Android e ChromeOS.

In questa guida scoprirai come aggiungere il supporto per la fatturazione di Google Play alla tua PWA e impacchettarla per la distribuzione sul Google Play Store sia per ChromeOS sia per il Play Store.

Utilizzerai due API della piattaforma web per aggiungere il supporto di Play Billing alla tua PWA. L'API Digital Goods viene utilizzata per raccogliere informazioni sugli SKU e verificare gli acquisti e i diritti dal Play Store. L'API Payment Request viene utilizzata per configurare il Google Play Store come metodo di pagamento e per completare il flusso di acquisto.

Come monetizzare le applicazioni sul Play Store

La tua applicazione può monetizzare con la fatturazione di Google Play sul Play Store in due modi:

  • Gli acquisti in-app consentono di vendere beni virtuali durevoli e di consumo, come funzionalità aggiuntive, o di rimuovere annunci.
  • Abbonamenti: offri ai tuoi utenti l'accesso continuo a contenuti o servizi a un prezzo ricorrente, come abbonamenti o iscrizioni a notizie.

Requisiti

Per configurare la fatturazione di Google Play, devi avere:

Aggiornare il progetto Bubblewrap

Se non hai installato Bubblewrap, dovrai farlo. Per informazioni dettagliate su come iniziare, consulta la guida rapida. Se hai già Bubblewrap, assicurati di eseguire l'aggiornamento alla versione 1.8.2 o successiva.

Anche Bubblewrap ha la funzionalità dietro un flag. Per attivarla, devi modificare la configurazione del progetto in twa-manifest.json, situata nella directory principale del progetto, e attivare sia alphaDependencies sia la funzionalità playBilling:

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

Dopo aver aggiornato il file di configurazione, esegui bubblewrap update per applicare la configurazione al progetto, seguito da bubblewrap build per generare un nuovo pacchetto Android e caricarlo sul Play Store.

Rilevamento della disponibilità dell'API Digital Goods e della fatturazione Google Play

Al momento, l'API Digital Goods è supportata da Chrome solo quando la PWA viene eseguita all'interno di un'attività web attendibile ed è possibile rilevare se è disponibile cercando getDigitalGoodsService nell'oggetto window:

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

L'API Digital Goods potrebbe essere disponibile in qualsiasi browser e supportare diversi store. Per verificare se un determinato backend dello Store è supportato, dovrai invocaregetDigitalGoodsService() passando l'ID dello Store come parametro. Il Google Play Store è identificato dalla stringa 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;
  }
}

Recuperare i dettagli di uno SKU

L'API Digital Goods fornisce getDetails(), che consente di recuperare informazioni come il titolo, la descrizione e, soprattutto, il prezzo del prodotto dal backend dei pagamenti.

Puoi quindi utilizzare queste informazioni nella tua interfaccia utente e fornire ulteriori dettagli all'utente:

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);
}

Creare il flusso di acquisto

Il costruttore di un oggetto PaymentRequest accetta due parametri: un elenco di metodi di pagamento e un elenco di dettagli di pagamento.

Quando ti trovi all'interno dell'attività web attendibile, devi utilizzare il metodo di pagamento per la fatturazione di Google Play impostando https://play.google.com/billing come identificatore e aggiungendo lo SKU del prodotto come membro di dati:

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

   ...
}

Anche se i dettagli di pagamento sono obbligatori, la fatturazione di Google Play li ignorerà e utilizzerà i valori impostati durante la creazione dello SKU in Play Console, pertanto possono essere inseriti valori non validi:

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

const request = new PaymentRequest(paymentMethods, paymentDetails);

Chiama show() nell'oggetto della richiesta di pagamento per avviare il flusso di pagamento. Se la promessa va a buon fine, il pagamento potrebbe essere andato a buon fine. Se il pagamento non va a buon fine, è probabile che l'utente abbia interrotto il pagamento.

Se la promessa va a buon fine, dovrai verificare e confermare l'acquisto. Per proteggerti da attività fraudolente, questo passaggio deve essere implementato utilizzando il tuo backend. Consulta la documentazione di Play Billing per scoprire come implementare la verifica nel tuo backend. Se non confermi l'acquisto, dopo tre giorni l'utente riceverà un rimborso e Google Play revocherà l'acquisto.

...
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
}
...

Facoltativamente, consume() può essere chiamato su un purchaseToken per contrassegnare l'acquisto come esaurito e consentirne l'acquisto di nuovo.

Riepilogando, un metodo di acquisto è il seguente:

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
    }
}

Controllare lo stato degli acquisti esistenti

L'API Digital Goods ti consente di verificare se l'utente dispone di diritti esistenti (acquisti in-app che non sono stati ancora utilizzati o abbonamenti in corso) da acquisti precedenti che ha già effettuato, su un altro dispositivo, da un'installazione precedente, riscattati da un codice promozionale o solo l'ultima volta che ha aperto l'app.


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}`);
}

È anche un buon momento per controllare gli acquisti effettuati in precedenza, ma non confermati. Ti consigliamo di confermare gli acquisti il prima possibile per assicurarti che i diritti degli utenti siano riportati correttamente nella tua app.

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}`);
}

Testare l'integrazione

Su un dispositivo Android di sviluppo

È possibile abilitare l'API Digital Goods su un dispositivo Android di sviluppo per eseguire test:

  • Assicurati di utilizzare Android 9 o versioni successive con la modalità sviluppatore attivata.
  • Installa Chrome 101 o versioni successive.
  • Per attivare i seguenti flag in Chrome, vai su chrome://flags e cerca la segnalazione per nome:
    • #enable-debug-for-store-billing
  • Assicurati che il sito sia ospitato utilizzando un protocollo https. L'utilizzo di http comporterà l'undefined dell'API

Su un dispositivo ChromeOS

L'API Digital Goods sarà disponibile su ChromeOS stabile a partire dalla versione 89. Nel frattempo, è possibile testare l'API Digital Goods:

  • Installa l'app dal Play Store sul dispositivo.
  • Assicurati che il sito sia ospitato utilizzando un protocollo https. L'utilizzo di http comporterà l'undefined dell'API

Con utenti di test e team di QA

Il Play Store offre funzionalità per i test, inclusi account di test degli utenti e SKU di test. Per ulteriori informazioni, consulta la documentazione relativa al test di fatturazione di Google Play.

Passaggi successivi

Come discusso in questo documento, l'API Play Billing ha componenti lato client, gestiti dall'API Digital Goods, e componenti lato server.