Questa pagina è stata tradotta dall'API Cloud Translation.

Implementare la fatturazione Play nella tua PWA

Se la tua PWA è elencata in Google Play e vuoi monetizzarla vendendo prodotti in-app o abbonamenti, le norme di Google Play ti richiederanno di implementare la fatturazione Google Play. Nella tua PWA devi implementare due API: l'API Digital Goods e l'API Payment Request.

API Digital Goods

L'API Digital Goods è un'interfaccia tra la tua app e Google Play. Consente di recuperare i prodotti digitali e i dettagli che hai inserito per i tuoi prodotti in-app e abbonamenti in Play Console, nonché gli acquisti esistenti effettuati da un utente. Se non hai ancora aggiunto prodotti in-app o abbonamenti in Play Console, assicurati di seguire la configurazione di Play Console per Play Billing.

Il 30 novembre 2021 è stato rilasciato ChromeOS 96 con l'implementazione dell'API Digital Goods 2.0.

La prova dell'origine per la prima versione dell'API Digital Goods è terminata il 30 gennaio 2022. Pertanto, è ora deprecata ed è disponibile solo la versione 2 dell'API.

Il 23 giugno 2022 è stato rilasciato ChromeOS 103 con l'implementazione dell'API Digital Goods 2.1. Questa release non include modifiche che causano interruzioni e include solo nuovi metodi e campi aggiuntivi: listPurchaseHistory() e itemType.

Registrati alla prova dell'origine

Nota:l'API Digital Goods è attualmente disponibile tramite una prova dell'origine, un meccanismo che consente agli sviluppatori di accedere in anteprima alle nuove API web. Dovrai registrarti alla prova dell'origine dell'API Digital Goods v2 e richiedere un token, che dovrai fornire in tutte le pagine della tua origine.

Al momento della registrazione alla prova dell'origine, vedrai una data "Valido fino al", ovvero la data fino alla quale è garantito il funzionamento del token. Ricordati di rinnovare i token quando la data si avvicina per continuare a partecipare alla prova. Le API offerte come prova di origine sono soggette a modifiche, quindi assicurati di rimanere aggiornato sulle ultime modifiche apportate a qualsiasi prova di origine a cui partecipi. In caso di problemi, consulta la documentazione dell'API Digital Goods.

API di richiesta del pagamento

L'API Payment Request gestisce la transazione di pagamento effettiva quando viene effettuato un acquisto. Utilizza i dettagli dell'articolo forniti dall'API Digital Goods per effettuare l'acquisto in-app utilizzando il metodo di pagamento appropriato, che nel nostro caso è la Fatturazione Google Play.

Rilevare le funzionalità dell'API Digital Goods

Puoi rilevare se hai abilitato correttamente l'API sul tuo sito web tramite la prova dell'origine controllando il metodo getDigitalGoodsService nell'oggetto window.

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

Connettiti al servizio di fatturazione Google Play

L'API Digital Goods è stata progettata per essere compatibile con vari browser e negozi digitali, in modo simile a come l'API Payment Request è indipendente dal browser e può essere utilizzata con diversi fornitori di servizi di pagamento. Per ottenere un'istanza del servizio associato a Fatturazione Google Play, passa la stringa "https://play.google.com/billing" come metodo di pagamento a getDigitalGoodsService().

Se il metodo genera un errore, il metodo di pagamento Fatturazione Google Play non è disponibile (ad es. l'utente accede alla tua PWA tramite il browser). Devi invece offrire un altro metodo di pagamento per le transazioni.

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

Recupera i dettagli dell'articolo

Una volta collegato il servizio Digital Goods a Google Play, puoi utilizzare l'API per recuperare informazioni su prodotti e acquisti.

Il metodo getDetails() ti consente di ottenere informazioni sugli elementi che hai configurato in Play Console. Informazioni come titolo, descrizione e prezzo del prodotto devono essere visualizzate nell'interfaccia utente della tua app in modo che l'utente sappia cosa è disponibile per l'acquisto e a quale prezzo.

Il metodo getDetails() richiede un elenco di ID articolo che corrispondono agli ID prodotto dei prodotti in-app e degli abbonamenti che hai creato in Play Console.

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

Per ottenere il prezzo appropriato per le impostazioni internazionali dell'utente, dovrai eseguire una formattazione aggiuntiva:

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

Nota:l'API Digital Goods non fornisce un metodo per ottenere un elenco di ID articolo. Dovrai invece codificarli nel client o recuperarli dal server di backend. L'API Google Play Developer ti consente di eseguire query sull'elenco degli ID articolo da un backend. Scopri di più sull'implementazione dei componenti chiave di Fatturazione Google Play nel server di backend. Qualunque soluzione tu scelga, assicurati che gli ID articolo siano coerenti con quelli presenti in Play Console.

Nella versione 2.1 dell'API, uno dei campi restituiti da getDetails() è itemType. Si tratta di un'enumerazione in cui il valore è ”product” o ”subscription” per indicare se l'elemento corrispondente è un prodotto in-app o un abbonamento, rispettivamente. La possibilità di distinguere tra i due tipi di prodotti può essere utile se devi applicare trattamenti diversi a ciascun tipo di prodotto. Ad esempio, potresti avere una pagina specifica per gli utenti che vogliono abbonarsi e un'altra pagina per gli altri prodotti non in abbonamento. È utile anche per conoscere la risorsa REST dell'API Google Play Developer appropriata da utilizzare nel backend (purchases.products o purchases.subscriptions).

Acquistare un articolo

Una volta visualizzati i prodotti e i dettagli per l'utente, puoi creare il flusso di acquisto con l'API Payment Request. Se utilizzata insieme all'API Digital Goods, è necessario un solo parametro di input: methodData.

Play Billing consente solo l'acquisto di un singolo articolo alla volta; il prezzo e i dettagli dell'articolo sono già noti al server Play, quindi il parametro details non è necessario. Per una spiegazione più dettagliata, consulta la spiegazione.

Utilizza il membro supportedMethods del parametro methodData in PaymentRequest per identificare la fatturazione Google Play come metodo di pagamento con la stringa "https://play.google.com/billing". Poi, nel membro data, passa l'ID articolo come sku.

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

Quindi, crea la richiesta di pagamento e chiama show() per avviare il flusso di pagamento:

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

Verrà visualizzata l'interfaccia utente di acquisto su Google Play, in cui l'utente vedrà i dettagli del prodotto che sta cercando di acquistare. Possono abbandonare la transazione o procedere con il pagamento. Se l'utente annulla il pagamento, la promessa restituita da show() verrà rifiutata con un errore. Se il pagamento e l'acquisto vengono completati correttamente, la promessa verrà risolta con un PaymentResponse. Nella proprietà details della risposta al pagamento viene restituito un token di acquisto.

Per prevenire le frodi, è fondamentale verificare l'acquisto e il token di acquisto sul server di backend. È anche una buona idea tenere traccia degli utenti e dei token di acquisto associati. Scopri come implementare la verifica sul server di backend.

Dopo aver convalidato l'acquisto, chiama complete() nella risposta al pagamento per completare il flusso di pagamento e chiudere l'interfaccia utente di fatturazione. Puoi anche trasmettere una stringa result facoltativa per indicare lo stato della procedura di pagamento. Spetta al browser fornire o meno un'indicazione di questo risultato all'utente. Chrome non crea indicatori visibili all'utente, pertanto ti consigliamo di visualizzare i tuoi messaggi di errore o di successo nella tua 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
}

Upgrade e downgrade degli abbonamenti

Questo flusso di acquisto è lo stesso sia per i prodotti in-app sia per gli acquisti di abbonamenti. Tuttavia, per gli abbonamenti, Google Play offre opzioni di acquisto aggiuntive che puoi implementare: upgrade e downgrade. Quando crei l'intent data per il metodo di pagamento, devi trasmettere quanto segue per avviare un flusso di upgrade o downgrade:

sku: l'ID articolo del nuovo abbonamento a cui eseguire l'upgrade o il downgrade.
oldSku: l'ID articolo dell'abbonamento attuale dell'utente.
purchaseToken: questo è il token di acquisto per l'abbonamento attuale dell'utente. Come accennato in precedenza, è consigliabile tenere traccia dei token di acquisto nel backend. Per questo scenario e altri, devi associare un utente ai suoi acquisti e token di acquisto attuali.
prorationMode: Questo è il modo in cui verrà addebitato il nuovo abbonamento quando sostituirà quello attuale dell'utente.

Modalità di ripartizione proporzionale	Descrizione
immediateAndChargeProratedPrice	L'abbonamento viene eseguito immediatamente e il ciclo di fatturazione rimane invariato. All'utente viene quindi addebitata la differenza di prezzo per il periodo rimanente.
immediateAndChargeFullPrice	L'abbonamento viene eseguito l'upgrade o il downgrade e all'utente viene addebitato immediatamente il prezzo intero del nuovo diritto. Il valore rimanente dell'abbonamento precedente viene ripartito proporzionalmente in base al tempo trascorso fino al nuovo abbonamento. Questa modalità di ripartizione è stata aggiunta di recente nella release 4.0 della Libreria Fatturazione Google Play. È ora disponibile tramite Bubblewrap a partire dalla versione 1.13.5.
immediateWithoutProration	TEMPORANEAMENTE DISATTIVATO Esiste un potenziale percorso di frode con questa modalità di ripartizione proporzionale in cui gli utenti potrebbero ottenere un abbonamento con upgrade senza pagamento aggiuntivo per un ciclo di fatturazione. Tieni presente che abbiamo disattivato temporaneamente questa modalità mentre lavoriamo alla correzione.
immediateWithTimeProration	L'upgrade o il downgrade dell'abbonamento viene eseguito immediatamente. Il tempo rimanente viene adeguato in base alla differenza di prezzo e accreditato al nuovo abbonamento posticipando la data di fatturazione successiva. Questo è il comportamento predefinito.
deferred	L'upgrade o il downgrade dell'abbonamento viene eseguito solo al momento del rinnovo. Questa funzionalità è particolarmente utile per i downgrade.
unknownSubscriptionUpgradeDowngradePolicy	Nessun criterio impostato. Questa operazione è sconsigliata.

Scopri di più sulle diverse modalità di ripartizione proporzionale nella documentazione di riferimento della Libreria Fatturazione Google Play. Consulta la documentazione per gli sviluppatori Android per saperne di più su upgrade e downgrade degli abbonamenti e sui consigli sulla modalità di ripartizione proporzionale.

L'utilizzo di questi campi aggiuntivi sarà simile al seguente:

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

In questo caso, item è il ItemDetails del nuovo abbonamento a cui l'utente sta tentando di eseguire l'upgrade o il downgrade, mentre oldPurchase è il PurchaseDetails dell'abbonamento attuale dell'utente.

Confermare un acquisto

Dopo che un utente ha acquistato un articolo, devi concedergli i diritti appropriati (accesso all'articolo o ai contenuti che ha appena acquistato). Poi, conferma l'acquisto. Il riconoscimento di un acquisto consente a Google Play di sapere che hai ricevuto ed elaborato l'acquisto in modo appropriato.

Nota:se un acquisto non viene confermato entro 72 ore dall'orario di acquisto, il pagamento viene rimborsato all'utente e l'acquisto viene revocato. Il token di acquisto non sarà più valido, quindi quando interroghi gli acquisti esistenti, l'acquisto revocato non verrà restituito. In questo modo, l'utente non viene addebitato in modo improprio in caso di errore di rete che impedisce la concessione del diritto al suo articolo.

Devi confermare gli acquisti dal tuo server di backend utilizzando l'API Google Play Developer. Ti consigliamo di concedere i diritti e poi riconoscere l'acquisto insieme nel server di backend.

Dopo che un utente ha effettuato un acquisto lato client, invia il token di acquisto e l'ID articolo in una richiesta al server di backend.
Nel backend, per ottenere i dettagli dell'acquisto da verificare, chiama:
- purchases.products.get per gli articoli in-app.
- purchases.subscriptions.get per gli abbonamenti.
Concedi il diritto appropriato nel database di backend.
Poi conferma l'acquisto chiamando:
- purchases.products.acknowledge per gli articoli in-app.
- purchases.subscriptions.acknowledge per gli abbonamenti.

Consumare un acquisto

Quando confermi un acquisto, Google Play sa che l'utente ora possiede l'articolo e non deve essere autorizzato ad acquistarlo di nuovo. Se si tratta di un articolo che l'utente dovrà acquistare una sola volta e possederà per sempre (ad es. una skin di un personaggio di un gioco), l'articolo non è consumabile.

In alternativa, l'elemento potrebbe essere qualcosa che limiti a un solo utente alla volta. Dopodiché, l'utente dovrà utilizzare l'articolo prima di poterne acquistare un altro. Quando l'utente "utilizza" l'articolo, per comunicare a Google Play che l'utente ha consumato l'articolo, devi chiamare il metodo consume(). Google Play renderà di nuovo disponibile l'articolo per l'acquisto da parte dell'utente.

Per gli articoli di cui consenti a un utente di possedere più unità, è necessario che possano essere acquistati ripetutamente senza dover essere utilizzati prima (li chiamiamo articoli ripetibili). Allo stesso modo, questi articoli devono essere "consumati" prima che Google Play consenta all'utente di acquistarli di nuovo. Pertanto, anche se l'utente non ha ancora utilizzato l'articolo, devi chiamare il metodo consume() per contrassegnarlo come utilizzato.

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

Controllare gli acquisti esistenti

L'ultimo flusso utente chiave consiste nel verificare la presenza di acquisti esistenti (prodotti in-app non ancora consumati e abbonamenti in corso) per comunicare agli utenti quali abbonamenti o articoli possiedono attualmente. Questi acquisti esistenti provengono da precedenti acquisti su Google Play effettuati in-app o sul Play Store su qualsiasi dispositivo. Gli acquisti effettuati al di fuori dell'app nel Play Store sono chiamati acquisti esterni all'app.

Quando recuperi gli acquisti esistenti, devi anche controllare lo stato di conferma e confermare gli acquisti effettuati in precedenza ma non confermati correttamente. È consigliabile confermare gli acquisti il prima possibile in modo che i diritti dell'utente siano aggiornati e riflettano correttamente l'app.

Il metodo listPurchases() dell'API Digital Goods restituirà un elenco di PurchaseDetails che contiene itemId e purchaseToken per ciascun acquisto. Dovrai utilizzare l'API Google Play Developer sul tuo server di backend per controllare lo stato degli acquisti e confermarli in modo appropriato. Al termine del corso dovreste essere in grado di:

Chiama il metodo listPurchases() dell'API Digital Goods lato client per recuperare l'elenco degli acquisti dell'utente.
Per ogni acquisto, trasmetti purchaseToken e itemId al tuo backend.
Se necessario, concedi i diritti nel database di backend.
Poi chiama:e controlla acknowledgementState.
- purchases.products.get per gli articoli in-app.
- purchases.subscriptions.get per gli abbonamenti.
Se il valore è 0 (ancora da confermare), chiama:
- purchases.products.acknowledge per gli articoli in-app.
- purchases.subscriptions.acknowledge per gli abbonamenti.

Scopri di più su come verificare gli acquisti sul server di backend prima di concedere i diritti.

Cronologia acquisti

Mentre listPurchases restituirà informazioni sugli acquisti esistenti dell'utente, il metodo listPurchaseHistory() (nella versione 2.1 dell'API) restituirà l'acquisto più recente effettuato dall'utente per ogni articolo, indipendentemente dal fatto che l'acquisto sia scaduto, annullato o consumato. Il metodo listPurchaseHistory() restituisce un elenco di PurchaseDetails contenenti itemId e purchaseToken per ogni acquisto, che dovrai utilizzare con l'API Google Play Developer sul server di backend per recuperare ulteriori informazioni.

Acquisti esterni all'app

Gli acquisti esterni all'app sono acquisti non effettuati nel normale flusso di acquisto in-app. Questi acquisti in genere vengono effettuati nel Play Store anziché nella tua app. Gli utenti possono effettuare un acquisto al di fuori dell'app in due modi principali:

Utilizzo di un codice promozionale: nel menu utente del Play Store, in "Offerte e notifiche" -> "Utilizza codice promozionale" o in "Pagamenti e abbonamenti" -> "Utilizza codice acquisto".
Rinnovo dell'abbonamento: nel menu utente del Play Store, in "Pagamenti e abbonamenti" -> "Abbonamenti". Qui gli utenti possono gestire tutti i loro abbonamenti in diverse app. Per gli abbonamenti scaduti o annullati, gli utenti hanno la possibilità di "Riabbonarsi".

Quando gli utenti si riabbonano dal Play Store, i loro acquisti non vengono confermati automaticamente, il che potrebbe comportare il rimborso. Questo comportamento è intenzionale perché agli utenti deve essere addebitato l'abbonamento solo se aprono l'app per utilizzarla. L'utente potrebbe visualizzare un messaggio come "Conferma abbonamento", che gli ricorda di aprire l'app.

Agli utenti viene chiesto di confermare l'abbonamento aprendo l'app per confermare l'acquisto.

In qualità di sviluppatore, spetta a te implementare la conferma di questi acquisti una volta che l'utente avvia l'app. Per questo motivo, ti consigliamo di verificare la presenza di acquisti esistenti (di solito al primo avvio dell'app) e di confermare gli acquisti non ancora confermati.

Consentire agli utenti di gestire gli abbonamenti

Per una buona esperienza utente, è importante fornire agli utenti un modo per gestire e annullare gli abbonamenti in-app. Ti consigliamo di creare un deep link, in una pagina o in un menu delle impostazioni, che reindirizzi l'utente alla pagina di gestione degli abbonamenti del Play Store per la tua app. Sostituisci il seguente URL con "sub-product-id" e "app-package-name" appropriati:

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

Passaggi successivi

Questi flussi utente e snippet di codice sono un'implementazione di base per dimostrare come utilizzare l'API Digital Goods e l'API Payment Request nella tua PWA per implementare Google Play Billing. Devi utilizzare le API nel modo più opportuno nel contesto e nei casi d'uso della tua app. Per un esempio di implementazione end-to-end, consulta il nostro esempio open source.

Poi, scopri come implementare i componenti cruciali di Google Play Billing nel server di backend per mantenere la tua app sicura e sempre aggiornata con i diritti degli utenti.

Implementare la fatturazione Play nella tua PWA Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.