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 prodotti digitali oppure offrire gli abbonamenti devono utilizzare la fatturazione Google Play. Il servizio Fatturazione Google Play offre strumenti per gestire il tuo catalogo, prezzi e abbonamenti, report utili e un flusso di pagamento tramite Google Play un negozio noto agli utenti.

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

In questa guida imparerai ad aggiungere il supporto per la Fatturazione Google Play alla tua PWA e a pacchettizzarlo per distribuzione sul Google Play Store sia per ChromeOS che per il Play Store.

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

Come monetizzare le applicazioni sul Play Store

La tua applicazione può monetizzare con Fatturazione Google Play sul Play Store in due modi:

  • Gli acquisti in-app consentono di vendere beni virtuali durevoli e di consumo, come ulteriori funzionalità o la rimozione di annunci.
  • Abbonamenti: offrono agli utenti l'accesso continuativo a contenuti o servizi dietro pagamento di una tariffa ricorrente. ad esempio abbonamenti alle notizie o abbonamenti.

Requisiti

Per configurare il servizio Fatturazione Google Play, ti serviranno:

Aggiornare il progetto Bubble wrap

Se Bubble wrap non è installato, dovrai installarlo. Consulta le Guida rapida per i dettagli su come iniziare. Se è già disponibile, assicurati assicurati di eseguire l'aggiornamento alla versione 1.8.2 o successiva.

Il pluriball ha anche la funzione dietro una bandiera. Nella per abilitarlo, dovrai modificare la configurazione del progetto in twa-manifest.json, che si trova nella directory principale del progetto e abilita sia alphaDependencies sia playBilling funzionalità:

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

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

Funzionalità che rileva la disponibilità dell'API Digital Goods e del servizio Fatturazione Google Play

L'API Digital Goods è attualmente supportata da Chrome solo quando la PWA viene eseguita all'interno di un Attività web attendibile ed è possibile determinare se è disponibile controllando la 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 negozi. Per per controllare se il backend di un determinato store è supportato, dovrai richiamare getDigitalGoodsService() trasmette l'ID negozio come parametro. Il Google Play Store è identificato in base alla 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 titolo, descrizione e, soprattutto, prezzo del prodotto provenienti dal backend dei pagamenti.

Puoi quindi utilizzare queste informazioni nell'interfaccia di utilizzo 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);
}

Crea il flusso di acquisto

Il costruttore di una PaymentRequest utilizza due parametri: un elenco di metodi di pagamento e un elenco dati di pagamento.

Quando ti trovi nell'Attività web attendibile, devi utilizzare il metodo di pagamento tramite fatturazione di Google Play, impostando https://play.google.com/billing come identificatore e aggiungendo lo SKU di prodotto come membro 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, il servizio Fatturazione Play ignorerà questi valori e utilizzerà i impostati durante la creazione dello SKU in Play Console, in modo che possano essere riempiti con valori fasulli:

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

const request = new PaymentRequest(paymentMethods, paymentDetails);

Chiama il show() sull'oggetto della richiesta di pagamento per avviare il flusso di pagamento. Se la promessa ha esito positivo 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 ha esito positivo, dovrai verificare e confermare l'acquisto. Per proteggerti da attività fraudolente, questo passaggio deve essere implementato utilizzando il tuo backend. Consulta le Documentazione relativa alla Fatturazione Play 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 consente di acquistarlo di nuovo.

Combinando tutti gli aspetti, un metodo di acquisto ha il seguente aspetto:

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 ha diritti esistenti (in-app acquisti non ancora consumati o abbonamenti in corso) derivanti da acquisti precedenti che ha effettuato già effettuati, su un altro dispositivo, da un'installazione precedente, utilizzati da un codice promozionale o solo l'ultima volta che hanno 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}`);
}

Questo è anche un buon momento per controllare gli acquisti effettuati in precedenza, ma che non sono stati confermati. Ti consigliamo di confermare gli acquisti il prima possibile per assicurarti che i diritti siano riportate 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 il segnala per nome:
    • #enable-debug-for-store-billing
  • Verifica che il sito sia ospitato utilizzando un protocollo https. Se utilizzi http, l'API sarà undefined

Su un dispositivo ChromeOS

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

  • Installa l'app dal Play Store sul dispositivo.
  • Verifica che il sito sia ospitato utilizzando un protocollo https. Se utilizzi http, l'API sarà undefined

Con utenti di test e team di QA

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

Qual è il passaggio successivo?

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