Indicazioni per l'integrazione del backend per la monetizzazione al di fuori della Fatturazione Google Play

L'API Google Play Developer ora include funzionalità aggiuntive per segnalare le transazioni da un sistema di fatturazione alternativa o offerte esterne. Questa guida descrive come segnalare le transazioni effettuate con fatturazione alternativa o per offerte esterne.

Esistono alcuni componenti che potrebbero essere necessari per gestire gli acquisti in-app dal backend. Per crearle, devi configurare l'integrazione del backend come indicato in Configurare l'API Google Play Developer. Per tutte le funzionalità di backend per sviluppatori non specifiche per le API di fatturazione alternativa o di offerte esterne, si applicano le istruzioni riportate nella documentazione del sistema di fatturazione di Google Play.

Segnalare nuove transazioni esterne a Google Play

Esegui l'integrazione con Externaltransactions APIs per segnalare le transazioni effettuate al di fuori del sistema di fatturazione di Google Play nei paesi supportati, incluse le transazioni senza costi derivanti da acquisti di prove senza costi. Le transazioni su sistemi di fatturazione alternativa o di offerte esterne devono essere avviate e registrate solo per i paesi degli utenti idonei come consentito dai programmi di fatturazione alternativa o offerte esterne, altrimenti la chiamata API verrà rifiutata. Questo vale per tutte le transazioni, inclusi nuovi acquisti, rinnovi, ricariche, upgrade, downgrade e altro ancora.

Report sulle transazioni esterne

Devi chiamare Externaltransactions API per segnalare una transazione esterna dopo che il pagamento è stato autorizzato tramite il sistema di fatturazione alternativo o di offerte esterne. Questo vale per tutte le transazioni, inclusi addebiti iniziali, rinnovi, rimborsi e altro. Tutte le transazioni devono essere segnalate entro 24 ore dal momento in cui si verificano.

Ogni transazione esterna viene registrata con un ID transazione esterno. Per gli acquisti ricorrenti (ad esempio gli abbonamenti con rinnovo automatico), devi inviare l'ID transazione esterno associato alla prima transazione nell'acquisto ricorrente come parametro per tutte le transazioni successive, inclusi i rimborsi. Questa registra la serie di transazioni per l'acquisto in questione. Devi inviare un nuovo ID transazione esterno per gli acquisti quando il prodotto cambia (ad esempio un upgrade o un downgrade) oppure se la transazione ricorrente viene annullata o scaduta e lo stesso prodotto viene acquistato di nuovo in un secondo momento. Non devi includere informazioni che consentono l'identificazione personale, informazioni proprietarie o riservate in questo ID transazione esterna.

Segnalare un nuovo acquisto

Ogni volta che un nuovo acquisto va a buon fine nel sistema di fatturazione alternativa o di offerte esterne, è necessaria una chiamata all'API Externaltransactions. Per questi nuovi acquisti, devi fornire un externalTransactionId univoco associato all'acquisto nel tuo backend come parametro di query. Questa risorsa externalTransactionId non può essere riutilizzata all'interno dell'ID pacchetto della stessa app.

Il externalTransactionToken ricevuto dall'app tramite i callback UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener o ExternalOfferReportingDetailsListener è obbligatorio anche come parte del corpo della richiesta per gli acquisti una tantum e le prime transazioni in un acquisto ricorrente (ad esempio un abbonamento). In entrambi i casi, si tratta di una transazione iniziale. Dopo la transazione iniziale, l'externalTransactionToken non è più necessario e segnali le transazioni successive (come il rinnovo dell'abbonamento) fornendo un nuovo externalTransactionId univoco. Per ulteriori dettagli su come segnalare le transazioni successive, consulta l'articolo Segnalare le transazioni successive per un acquisto.

Esempio:

  1. Uno sviluppatore configura e attiva la fatturazione alternativa nella propria app.
  2. L'utente 1 si trova in Corea del Sud, un paese supportato, e sta cercando di acquistare product1 a 12.634, 10 KRW al mese, con un'offerta di prova senza costi di un mese.
  3. L'app avvia il flusso di acquisto con ProductDetails per product1 e l'offerta selezionata dall'utente.
  4. L'utente 1 seleziona il sistema di fatturazione alternativo dello sviluppatore.
  5. UserChoiceBillingListener riceve il valore my_token come externalTransactionToken.
  6. Lo sviluppatore invia quindi le informazioni pertinenti al suo backend (valore externalTransactionToken e prodotti acquistati). Quindi, avvia il flusso di acquisto per product1 nel sistema di fatturazione alternativo. A questa transazione viene assegnato un ID transazione univoco sul lato sviluppatore, utilizzato per segnalarla a Google Play: 123-456-789. L'ID transazione è obbligatorio, anche se l'utente sta ricevendo una prova senza costi.
  7. Dopo che la transazione per l'acquisto avviene nel sistema di fatturazione alternativo, lo sviluppatore segnala la transazione a Google Play con la seguente richiesta. Inizialmente viene indicata come transazione a zero dollari perché l'utente riceve un mese senza costi.
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Se le transazioni con un utente residente in India, dove le tasse variano in base all'area amministrativa (ad esempio, stato o provincia), assicurati di includere quell'area in userTaxAddress. Consulta l'elenco predefinito di stringhe nella Guida di riferimento dell'API per le aree amministrative applicabili.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
"transactionTime" : "2023-11-01T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   # Tax varies in India based on state, so include that information in
   # administrativeArea
   "regionCode": "IN"
   "administrativeArea": "KERALA"
 }
}

Segnalare le transazioni successive per un acquisto

In alcuni casi, è presente più di un pagamento utente associato allo stesso acquisto esterno (ad esempio, rinnovi di abbonamenti o ricariche di piani prepagati). Puoi segnalare queste transazioni successive utilizzando la stessa API in Externaltransactions. Come descritto in Segnalare un nuovo acquisto, externalTransactionToken non è necessario per le transazioni successive. Viene invece inviato un nuovo externalTransactionId univoco come parametro di query per ogni transazione di rinnovo o ricarica, con l'ID della transazione iniziale incluso nel campo initialExternalTransactionId.

In base all'esempio precedente:

  1. Il primo rinnovo dell'utente 1 avviene nel sistema di fatturazione alternativo. L'ID transazione iniziale era 123-456-789.
  2. Lo sviluppatore segnala la ricorrenza della transazione nel parametro di query dell'URL come ID transazione esterno per questa nuova transazione, facendo riferimento all'ID transazione esterna della transazione iniziale nel campo initialExternalTransactionId.

Esempio di richiesta:

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "12634000000",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "1263000000",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "initialExternalTransactionId": "123-456-789",

   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Segnalare un upgrade o un downgrade

Per segnalare un upgrade o un downgrade quando l'utente possiede un abbonamento nel sistema di fatturazione alternativo, utilizzi lo stesso endpoint e la stessa funzione nell'API Externaltransactions e invii il valore externalTransactionToken fornito all'app per la transazione di upgrade o downgrade. Questa procedura è simile a quella per segnalare un nuovo acquisto.

Eseguire la migrazione dai report manuali delle transazioni di fatturazione alternativa

Per eseguire la migrazione degli abbonamenti attivi iniziati mentre offrivi la fatturazione alternativa senza generazione di report automatici, crea una nuova transazione senza costi utilizzando il campo migratedTransactionProgram anziché specificare un initialExternalTransactionId o un externalTransactionToken. Imposta transactionTime sull'ora in cui l'utente ha inizialmente registrato ogni abbonamento attivo. In seguito, segnala come di consueto ogni successiva transazione per questi abbonamenti tramite le API, fornendo i initialExternalTransactionId utilizzati in precedenza per creare le transazioni di rinnovo. Una volta eseguita la migrazione dell'abbonamento, non dovrai più segnalare manualmente le successive transazioni relative all'abbonamento, a condizione che vengano segnalate tramite i metodi automatici descritti in questa pagina.

Durante la migrazione degli abbonamenti, tieni presente i limiti di quota in vigore per assicurarti che la migrazione non causi un'interruzione della quota. Se è necessario eseguire la migrazione di molti abbonamenti, distribuiscili su più giorni o richiedi un aumento della quota.

Il campo migratedTransactionProgram può essere utilizzato solo durante la migrazione dai report manuali. Verrà deprecata quando i report manuali non saranno più supportati.

Esempio di richiesta:

# Note that the externalTransactionId specified here will used to report subsequent
# transactions.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
 # Be sure to set the price to 0 for this transaction since it does not reflect
 # an actual subscription renewal.
 "originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },

 # The transaction time should be set to when the user signed up for this
 # subscription.
 "transactionTime" : "2022-02-22T12:45:00Z",
  "recurringTransaction" : {
    "migratedTransactionProgram": "USER_CHOICE_BILLING",

    "externalSubscription" {
      "subscriptionType": "RECURRING"
    }
  },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

Segnalare i rimborsi degli acquisti a Google Play

Esegui l'integrazione con l'API Externaltransactions per segnalare le transazioni rimborsate a utenti esterni al sistema di fatturazione di Google Play. Affinché Google possa identificare correttamente la transazione rimborsata, devi includere il valore externalTransactionId corrispondente per la transazione segnalata in precedenza nei parametri URL.

Quando segnali i rimborsi di acquisti di abbonamenti, fai riferimento al valore externalTransactionId relativo alla ricorrenza specifica dell'abbonamento che viene rimborsato.

Esempio: supponiamo che un abbonamento presenti le seguenti transazioni:

  • Una transazione iniziale con ID transazione esterno ABC.1234-5678-9012-34567
  • La prima transazione ricorrente con ID transazione esterno ABC.1234-5678-9012-34567..0
  • La seconda transazione ricorrente con ID transazione esterno ABC.1234-5678-9012-34567..1

Per segnalare un rimborso di tutte le transazioni relative all'abbonamento, devi presentare tre richieste di rimborso separate: una per la transazione iniziale e due per le transazioni successive.

Questo metodo accetta sia rimborsi completi (in cui l'importo è lo stesso importo pagato dall'utente nella transazione esterna originale) e rimborsi parziali (in cui l'importo è inferiore a quello pagato dall'utente nella transazione esterna originale). Per i rimborsi parziali, devi specificare l'importo al lordo delle imposte che è stato rimborsato.

Quote API

L'API Externaltransactions è soggetta a quote API giornaliere per tutte le chiamate, così come qualsiasi altro endpoint nell'API Google Play Developer.

Inoltre, l'API Externaltransactions ha un limite di 1200 query al minuto (QPM) per le chiamate a Externaltransactions.createexternaltransaction o Externaltransactions.refundexternaltransaction. Le chiamate a Externaltransactions.getexternaltransaction non vengono conteggiate ai fini di questo limite di 1200 QPM.