Reminder: By Aug 31, 2024, all new apps and updates to existing apps must use Billing Library version 6 or newer. If you need more time to update your app, you will be able to request an extension until Nov 1, 2024. Learn more.

Questa pagina è stata tradotta dall'API Cloud Translation.

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

L'API Google Play Developer ora include ulteriori per segnalare le transazioni provenienti da una fatturazione alternativa di offerte esterne. Questa guida descrive come segnalare alternative di fatturazione o per offerte esterne.

Potrebbero essere necessari alcuni componenti per gestire acquisti dal tuo backend. Per crearle, devi configurare il tuo backend come indicato nella sezione Configurare l'API Google Play Developer. Per Tutte le funzionalità backend degli sviluppatori che non sono specifiche per la fatturazione alternativa o le API per offerte esterne, le istruzioni Si applica la documentazione del sistema di fatturazione di Google Play.

Segnalare nuove transazioni esterne a Google Play

Eseguire l'integrazione con Externaltransactions APIs per segnalare le transazioni che avvengono al di fuori del sistema di fatturazione di Google Play in paesi supportati, incluse le transazioni senza costi derivanti dalla prova senza costi acquisti. Transazioni su sistemi di fatturazione alternativa o su sistemi di offerte esterne deve essere avviato e incluso nei report solo per i paesi degli utenti idonei, come consentito ai sensi della fatturazione alternativa programmi di offerte esterne, altrimenti la chiamata API verrà rifiutato. Questo vale per tutte le transazioni, inclusi nuovi acquisti, rinnovi ricariche, upgrade, downgrade e altro ancora.

Report sulle transazioni esterne

Devi chiamare il Externaltransactions API per segnalare una transazione esterna dopo che il pagamento è stato autorizzato tramite la fatturazione alternativa o di offerte esterne. Questo vale per tutte le transazioni, incluse le transazioni iniziali addebiti, rinnovi, rimborsi e altro. Tutte le transazioni devono essere entro 24 ore dalla transazione.

Ogni transazione esterna viene registrata con un ID transazione esterno. Per acquisti ricorrenti (come gli abbonamenti con rinnovo automatico), devi inviare l'ID esterno della transazione associato alla prima transazione nell'account di servizio ricorrente purchase come parametro per tutte le transazioni successive, inclusi i rimborsi. Questo registra la serie di transazioni relative all'acquisto in questione. Invii un nuovo server esterno ID transazione per gli acquisti quando il prodotto cambia (ad esempio un upgrade o una downgrade) oppure se la transazione ricorrente viene annullata o scaduta e in un secondo momento. Non devi includere informazioni che consentono l'identificazione personale informazioni, informazioni proprietarie o riservate nell'ambito del presente dell'ID transazione.

Segnalare un nuovo acquisto

Ogni volta che un nuovo acquisto va a buon fine con la fatturazione alternativa o un sistema di offerte esterne, una chiamata all'API Externaltransactions viene obbligatorio. Per questi nuovi acquisti, devi fornire un modello univoco externalTransactionId associato all'acquisto nel tuo backend come query . Questo externalTransactionId non può essere riutilizzato all'interno di l'ID pacchetto.

externalTransactionToken ricevuto dall'app tramite UserChoiceBillingListener, AlternativeBillingOnlyReportingDetailsListener o ExternalOfferReportingDetailsListener è necessario anche nell'ambito il corpo della richiesta per gli acquisti una tantum e le prime transazioni in un un acquisto ricorrente (ad esempio un abbonamento). In entrambi i casi, viene chiamato una transazione iniziale. Dopo la transazione iniziale, externalTransactionToken non è più necessario e segnali in seguito (come i rinnovi dell'abbonamento) fornendo un nuovo ID univoco externalTransactionId. Consulta Segnalare le transazioni successive per un acquisto. per maggiori dettagli su come segnalare le transazioni successive.

Esempio:

Uno sviluppatore configura e attiva la fatturazione alternativa nella propria app.
L'utente 1 si trova nella Corea del Sud, un paese supportato, e sta tentando di acquistare product1, a 12634,10 KRW al mese, con un'offerta di prova senza costi di un mese.
L'app avvia il flusso di acquisto con ProductDetails per product1 e l'offerta selezionata dall'utente.
L'utente 1 seleziona il sistema di fatturazione alternativo dello sviluppatore.
UserChoiceBillingListener riceve il valore my_token come externalTransactionToken.
Lo sviluppatore invia quindi le informazioni pertinenti al suo backend. (valore di 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 segnalarlo a Google Play: 123-456-789. L'ID transazione è obbligatorio, anche se l'utente sta usufruendo di una prova senza costi.
Dopo che la transazione di acquisto avviene nella fatturazione alternativa di sistema, lo sviluppatore segnala la transazione a Google Play con richiesta in seguito. Inizialmente viene segnalata come transazione da zero dollari perché l'utente ha 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 si effettuano transazioni con un utente residente in India, dove le imposte variano a seconda della area amministrativa (come stato o provincia), accertati di includere in userTaxAddress. Fai riferimento all'elenco predefinito di stringhe nel Guida di riferimento delle API per le aree amministrative pertinenti.

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

Segnala le transazioni successive per un acquisto

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

Seguendo l'esempio precedente:

Il primo rinnovo dell'Utente 1 avviene nel sistema di fatturazione alternativo. L'iniziale l'ID transazione era 123-456-789.
Lo sviluppatore segnala la ricorrenza delle transazioni nel parametro di query dell'URL come ID transazione esterna per questa nuova transazione, facendo riferimento l'ID della 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 di fatturazione alternativa, utilizzi lo stesso endpoint e la stessa funzione API Externaltransactions, durante l'invio del externalTransactionToken che è stato fornita all'app per la transazione di upgrade o downgrade. Funziona in modo simile alla segnalazione di un nuovo acquisto.

Eseguire la migrazione dai report manuali delle transazioni di fatturazione alternativa

Per eseguire la migrazione degli abbonamenti attivi iniziati mentre offrivi un'alternativa fatturazione senza generazione di report automatici, crea una nuova transazione a costo zero utilizzando il campo migratedTransactionProgram invece di specificare initialExternalTransactionId o externalTransactionToken. Imposta il parametro transactionTime al momento in cui l'utente ha eseguito la registrazione iniziale di ogni abbonamento attivo abbonamento. In seguito, registra ogni transazione successiva per questi gli abbonamenti normalmente attraverso le API, fornendo initialExternalTransactionId utilizzato in precedenza per creare le transazioni di rinnovo. Una volta eseguita la migrazione dell'abbonamento, non dovrai più segnalarlo manualmente le transazioni successive per l'abbonamento, a condizione che siano riportati tramite i metodi automatici descritti in questa pagina.

Durante la migrazione degli abbonamenti, tieni presente i limiti di quota applicati per per assicurarti che la migrazione non causi un'interruzione della quota. Se sono necessari molti abbonamenti eseguire la migrazione, distribuirli su più giorni o richiedere un aumento della quota di Google.

Il campo migratedTransactionProgram può essere utilizzato solo durante la migrazione da creazione di report manuali. Verrà ritirata 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 programmi partner di Google Play

Gli sviluppatori che partecipano a programmi per i partner quali Il programma Esperienza multimediale Play deve fornire i seguenti elementi: transaction_program_code quando segnali transazioni esterne. Se uno sviluppatore idoneo, contatta il tuo Business Development Manager per ulteriori informazioni informazioni su come impostare questo campo.

Segnalare i rimborsi degli acquisti su Google Play

Integrare l'API Externaltransactions per segnalare le transazioni rimborsate utenti esterni al sistema di fatturazione di Google Play. Per consentire a Google Play di identificare correttamente transazione è stata rimborsata, includi i dati corrispondenti externalTransactionId per la transazione precedentemente segnalata nell'ambito di Parametri URL.

Quando segnali i rimborsi degli acquisti di abbonamenti, fai riferimento ai externalTransactionId della ricorrenza specifica dell'abbonamento in fase di rimborso.

Esempio: supponiamo che un abbonamento includa le seguenti transazioni:

Una transazione iniziale con un 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 per l'abbonamento, devi effettuare tre richieste di rimborso distinte: una per la transazione iniziale e due per la transazioni successive.

Questo metodo accetta entrambi i rimborsi completi (dove l'importo è lo stesso pagato dall'utente nell'account esterno originale transazione) e rimborsi parziali (dove l'importo è inferiore a quello pagato dall'utente nell'offerta esterna originale transazione). 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, come per qualsiasi altro endpoint nell'API Google Play Developer.

Inoltre, l'API Externaltransactions ha 1200 query al minuto Limite di (QPM) per le chiamate a Externaltransactions.createexternaltransaction o Externaltransactions.refundexternaltransaction. Chiamate a Externaltransactions.getexternaltransaction non vengono conteggiati ai fini di queste 1200 QPM limite.