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

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

Per gestire gli acquisti in-app dal tuo backend potrebbero essere necessari alcuni componenti. Per crearli, 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 per le 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 che avvengono al di fuori del sistema di fatturazione di Google Play nei paesi supportati, incluse le transazioni senza costi risultanti dagli acquisti di prova senza costi. Le transazioni sui sistemi di fatturazione alternativa o di offerte esterne devono essere avviate e registrate solo per i paesi idonei degli utenti, come consentito dai programmi di fatturazione alternativa o di offerte esterne, altrimenti la chiamata all'API verrà rifiutata. Ciò vale per tutte le transazioni, inclusi nuovi acquisti, rinnovi, ricariche, upgrade, downgrade e altro ancora.

Report sulle transazioni esterne

Devi chiamare il numero 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 gli addebiti iniziali, i rinnovi, i rimborsi e altro ancora. Tutte le transazioni devono essere comunicate entro 24 ore dalla loro effettuazione.

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. In questo modo vengono registrate le serie di transazioni relative all'acquisto. Invii un nuovo ID transazione esterno per gli acquisti quando il prodotto cambia (ad esempio in caso di upgrade o downgrade) o 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 nell'ambito di questo ID transazione esterno.

Segnalare un nuovo acquisto

Ogni volta che un nuovo acquisto viene completato nel sistema di fatturazione alternativa o di offerte esterne, è obbligatoria una chiamata all'API Externaltransactions. Per questi nuovi acquisti, devi fornire un valore univoco externalTransactionId associato all'acquisto nel tuo backend come parametro di query. Questo externalTransactionId non può essere riutilizzato all'interno dell'ID package della stessa app.

Il valore externalTransactionToken ricevuto dall'app tramite i callback UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener o ExternalOfferReportingDetailsListener è obbligatorio anche nel corpo della richiesta per gli acquisti una tantum e le transazioni iniziali in un acquisto ricorrente (ad esempio un abbonamento). In entrambi i casi, si tratta di una transazione iniziale. Dopo la transazione iniziale, il valore externalTransactionToken non è più necessario e puoi segnalare le transazioni successive (ad esempio i rinnovi dell'abbonamento) fornendo un nuovo valore externalTransactionToken univoco.externalTransactionId Per maggiori dettagli su come segnalare le transazioni successive, consulta la sezione 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 tentando di acquistare product1, al prezzo di 12634,10 KRW al mese, con un'offerta di prova senza costi di un mese.
3. L'app avvia il flusso di acquisto con il 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 proprio backend (valore externalTransactionToken e prodotti acquistati). Quindi, avviano il flusso di acquisto per product1 nel sistema di fatturazione alternativo. A questa transazione viene assegnato un ID transazione univoco lato sviluppatore che viene utilizzato per segnalarla a Google Play: 123-456-789. L'ID transazione è obbligatorio, anche se l'utente sta usufruendo di una prova senza costi.
7. Dopo che la transazione di acquisto avviene nel sistema di fatturazione alternativa, lo sviluppatore segnala la transazione a Google Play con la seguente richiesta. Inizialmente viene registrata come transazione senza costi 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"
 }
}

Nota: subscriptionType può essere RECURRING (per gli abbonamenti con rinnovo automatico) o PREPAID (per gli abbonamenti prepagati).

Nota: OtherRecurringProduct può essere utilizzato per rappresentare acquisti una tantum che richiedono più pagamenti o un pagamento differito. Ad esempio, una prenotazione potrebbe avere una transazione iniziale di 0 $seguita da una seconda transazione in data successiva per il prezzo dello SKU al momento dell'evasione della prenotazione. Per ulteriori dettagli sulla registrazione delle transazioni successive per un acquisto, consulta la sezione Registrare le transazioni successive per un acquisto.

Nota: la registrazione di una transazione per un acquisto utilizzando solo la fatturazione alternativa o le offerte esterne è la stessa descritta sopra, tranne per il fatto che il valore externalTransactionToken viene ottenuto seguendo i passaggi descritti nella guida relativa alla fatturazione alternativa o alle offerte esterne.

Se effettui transazioni con un utente residente in India, dove l'imposta varia in base alla sua area amministrativa (ad esempio stato o provincia), assicurati di includere questa area in userTaxAddress. Fai riferimento all'elenco di stringhe predefinite 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, allo stesso acquisto esterno è associato più di un pagamento utente (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, il valore externalTransactionToken non è necessario per le transazioni successive. Al suo posto, viene 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 externalTransactionId.initialExternalTransactionId

Seguendo l'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 esterno della transazione iniziale nel campo initialExternalTransactionId.

Richiesta di esempio:

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, utilizza lo stesso endpoint e la stessa funzione nell'API Externaltransactions, inviando il externalTransactionToken fornito all'app per la transazione di upgrade o downgrade. Il funzionamento è simile alla segnalazione di un nuovo acquisto.

Eseguire la migrazione dai report manuali delle transazioni di fatturazione alternativa

Nota: la generazione manuale di report per la fatturazione alternativa e la fatturazione scelta dall'utente è in fase di ritiro. Per maggiori dettagli sulle scadenze della migrazione, consulta Informazioni sulla fatturazione scelta dall'utente su Google Play. Assicurati di eseguire la migrazione di tutti gli abbonamenti attivi iniziati mentre offrivi la fatturazione alternativa senza segnalazione automatica tramite l'API ExternalTransactions prima che la generazione di report manuali venga disattivata.

Per eseguire la migrazione degli abbonamenti attivi iniziati mentre offrivi la fatturazione alternativa senza generazione automatica di report, crea una nuova transazione senza costi utilizzando il campo migratedTransactionProgram anziché specificare initialExternalTransactionId o externalTransactionToken. Imposta transactionTime sul momento in cui l'utente ha effettuato la registrazione iniziale per ogni abbonamento attivo. Successivamente, segnala ogni transazione successiva per questi abbonati come di consueto tramite le API, fornendo il valore initialExternalTransactionId utilizzato sopra per creare le transazioni di rinnovo. Una volta eseguita la migrazione dell'abbonamento, non dovrai più segnalare manualmente le transazioni successive per l'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, suddividili su più giorni o richiedi un aumento della quota.

Nota: solo gli sviluppatori che hanno offerto la fatturazione alternativa senza report automatici potranno impostare il campo migratedTransactionProgram. Se in precedenza offrivi la fatturazione alternativa senza automazione e ricevi un errore quando provi a effettuare una richiesta di migrazione dell'abbonamento, puoi contattare il nostro team di assistenza per ricevere aiuto.

Il campo migratedTransactionProgram può essere utilizzato solo durante la migrazione dai report manuali. Verrà ritirato quando la generazione di report manuali non sarà più supportata.

Richiesta di esempio:

# 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 programmi partner di Google Play

Gli sviluppatori che partecipano a programmi partner come il programma Esperienza multimediale Play devono fornire il transaction_program_code quando segnalano transazioni esterne. Se sei un sviluppatore idoneo, contatta il tuo Business Development Manager per ulteriori informazioni su come impostare questo campo.

Segnalare i rimborsi degli acquisti a Google Play

Esegui l'integrazione con l'API Externaltransactions per segnalare le transazioni rimborsate agli utenti al di fuori del sistema di fatturazione di Google Play. Affinché Google Play possa identificare correttamente la transazione per la quale è stato effettuato il rimborso, devi includere il valore corrispondente externalTransactionId per la transazione segnalata in precedenza nei parametri URL.

Quando registri i rimborsi degli acquisti di abbonamenti, fai riferimento al valore externalTransactionId della riattivazione specifica dell'abbonamento per cui viene effettuato il rimborso.

Esempio: supponiamo che un abbonamento abbia 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 richiedere il rimborso di tutte le transazioni relative all'abbonamento, devi effettuare tre richieste di rimborso distinte: una per la transazione iniziale e due per le transazioni successive.

Questo metodo accetta sia i rimborsi totali (se l'importo corrisponde a quello pagato dall'utente nella transazione esterna originale) sia i rimborsi parziali (se l'importo è inferiore a quello pagato dall'utente nella transazione esterna originale). Per i rimborsi parziali, devi specificare l'importo al netto delle imposte che è stato rimborsato.

Quote API

L'API Externaltransactions è soggetta a quote giornaliere dell'API per tutte le chiamate, come qualsiasi altro endpoint dell'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.