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

L'API Google Play Developer include funzionalità aggiuntive per segnalare le transazioni dai programmi di fatturazione e di collegamento. Questa guida descrive come segnalare le transazioni da questi programmi di fatturazione.

Esistono alcuni componenti che potrebbero essere necessari per gestire le transazioni esterne dal backend. Per crearli, devi configurare l'integrazione del backend come indicato in Configurare l'API Google Play Developer. Per creare funzionalità del backend dello sviluppatore che non sono specifiche per i programmi di fatturazione e di collegamento, consulta Sistema di fatturazione di Google Play.

Glossario dei termini

Convenzioni dei termini seguite in questa guida:

  • Programmi di fatturazione e di collegamento: programmi che facilitano gli acquisti di contenuti digitali o i download di app al di fuori di Google Play. Sono inclusi i programmi di fatturazione alternativa e di contenuti esterni.
  • API per transazioni esterne: API utilizzate per segnalare le transazioni per i programmi di fatturazione e di collegamento idonei.
  • Transazione esterna: una transazione idonea che si verifica al di fuori dell' app, come definita dai programmi di fatturazione alternativa e contenuti esterni.
  • Token di transazione esterno: un token fornito tramite la Libreria Fatturazione Play da utilizzare quando l'utente avvia una transazione esterna. Questo token viene utilizzato per notificare a Google Play una transazione esterna autorizzata.
  • ID transazione esterno: un identificatore univoco generato da te per identificare una transazione esterna.

Segnalare nuove transazioni esterne a Google Play

Integra l'API externaltransactions per segnalare le transazioni che avvengono al di fuori del sistema di fatturazione di Google Play nei paesi supportati, incluse le transazioni da 0 $ derivanti da acquisti di prove senza costi e installazioni di app. Devi avviare e segnalare le transazioni sui programmi di fatturazione e di collegamento solo per i paesi degli utenti idonei, come consentito dai programmi di fatturazione alternativa e di contenuti esterni; in caso contrario, la chiamata API viene rifiutata. Ciò vale per tutte le transazioni, inclusi nuovi acquisti, rinnovi, ricariche, upgrade, downgrade e download di app.

Report sulle transazioni esterne

Devi chiamare l'API externaltransactions per segnalare una transazione esterna dopo che un pagamento è stato autorizzato tramite un programma di fatturazione e di collegamento. Ciò vale per tutte le transazioni, inclusi addebiti iniziali, rinnovi, rimborsi e altro. Consulta le linee guida per il rispettivo programma di fatturazione e di collegamento per i requisiti di report.

Ogni transazione esterna viene segnalata 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 le transazioni successive, inclusi i rimborsi. In questo modo viene registrata la serie di transazioni per l'acquisto. Devi inviare un nuovo ID transazione esterno per gli acquisti quando il prodotto cambia (ad esempio un upgrade o un downgrade) o se la transazione ricorrente viene annullata o scade e lo stesso prodotto viene acquistato di nuovo in un secondo momento. Non devi includere informazioni che consentono l'identificazione personale, proprietarie o riservate come parte di questo ID transazione esterno.

Segnalare una transazione iniziale

Ogni volta che un nuovo acquisto o download di app viene autorizzato nei programmi di fatturazione e di collegamento, devi chiamare l'API externaltransactions.

L'externalTransactionToken ricevuto dall'app tramite la Libreria Fatturazione Google Play è necessario come parte del corpo della richiesta per i download di app, gli acquisti una tantum e le transazioni iniziali in un acquisto ricorrente (ad esempio un abbonamento). Questa è chiamata transazione iniziale. Dopo la transazione iniziale, segnala le transazioni successive (ad esempio i rinnovi degli abbonamenti) fornendo un nuovo externalTransactionId univoco. Per maggiori informazioni, consulta Segnalare le transazioni successive per un acquisto.

Esempio:

  1. Uno sviluppatore configura e attiva la fatturazione alternativa nella sua app.
  2. L'utente 1 si trova in Corea del Sud, un paese supportato, e sta tentando di acquistare product1 per 12634, 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 proprio backend (valore externalTransactionToken e prodotti acquistati). Poi, avvia il flusso di acquisto per product1 nel sistema di fatturazione alternativo. A questa transazione viene assegnato un ID transazione univoco sul lato dello sviluppatore, utilizzato per segnalarla a Google Play: 123-456-789. L'ID transazione è obbligatorio, anche se l'utente riceve una prova senza costi.
  7. Dopo che la transazione per l'acquisto è avvenuta nel sistema di fatturazione alternativo, lo sviluppatore la segnala a Google Play con la seguente richiesta. Inizialmente viene segnalata come transazione da 0 $ 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"
 }
}

Quando segnali una transazione iniziale, tieni presente quanto segue:

  • subscriptionType può essere RECURRING (per gli abbonamenti con rinnovo automatico) o PREPAID (per gli abbonamenti prepagati).
  • Devi utilizzare OtherRecurringProduct per rappresentare gli acquisti una tantum che richiedono più pagamenti o un pagamento ritardato. Ad esempio, un pre-ordine potrebbe avere una transazione iniziale da 0 $seguita da una seconda transazione in una data successiva per il prezzo dello SKU quando il pre-ordine viene evaso. Per maggiori dettagli sulla segnalazione delle transazioni successive, consulta Segnalare le transazioni successive per un acquisto.
  • Devi fornire ExternalOfferDetails quando segnali le transazioni iniziali delle offerte esterne. Questo non è obbligatorio per le transazioni successive.

Se stai effettuando transazioni con un utente in India in cui l'imposta dipende dalla sua area amministrativa (ad esempio uno stato o una provincia), includi l'area in userTaxAddress. Fai riferimento all'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"
 }
}

Offerte esterne

Se la transazione segnalata rientra nel programma per offerte esterne, devi impostare il campo externalOfferDetails se la transazione è una tantum o la prima di una serie ricorrente:

  • Quando segnali le transazioni di download di app, imposta linkType su LINK_TO_APP_DOWNLOAD e fornisci i valori appropriati per installedAppPackage e installedAppCategory. Per i dettagli, consulta Segnalare il download di un'app.
  • Quando segnali le transazioni di offerte di contenuti digitali, imposta linkType su LINK_TO_DIGITAL_CONTENT_OFFER.
  • Dopo aver installato un'app esterna tramite il programma per offerte esterne, devi segnalare le transazioni effettuate nell'app esterna. Quando segnali queste transazioni, collegale all'evento di download dell'app originale:
    • Fornisci l'externalTransactionToken dell'evento di download dell'app.
    • Nel campo externalOfferDetails, imposta appDownloadEventExternalTransactionId sull'externalTransactionId dell'evento di download dell'app. Gli altri campi in externalOfferDetails non sono obbligatori.

Esempio di richiesta per una transazione in un'app esterna scaricata tramite offerte esterne:

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=ABC-DEF-GHI

Body
 {
"originalPreTaxAmount" : {
   "priceMicros" : "990000", # 0.99 EUR
   "currency" : "EUR"
 },
 "originalTaxAmount" : {
   "priceMicros" : "90000", # 0.09 EUR
   "currency" : "EUR"
 },
"transactionTime" : "2025-11-22T12:45:00Z",
 "oneTimeTransaction" : {
   "externalTransactionToken" : "my_external_transaction_token_for_link_to_download_event"
 },
 "userTaxAddress" : {
   "regionCode" : "DE"
 },
 "externalOfferDetails" : {
   "appDownloadEventExternalTransactionId" : "my_external_transaction_id_for_link_to_download_event"
 }
}

I dettagli aggiornati della commissione di servizio di Play per i diversi tipi di transazione possono essere trovati in Modifiche al programma per offerte esterne per gli utenti nello Spazio economico europeo (SEE).

Segnalare le transazioni successive per un acquisto

In alcuni casi, a uno stesso acquisto esterno sono associati più pagamenti dell'utente, ad esempio i rinnovi degli abbonamenti o le ricariche dei piani prepagati. Puoi segnalare queste transazioni successive utilizzando la stessa API in Externaltransactions. Come descritto in Segnalare un nuovo acquisto, il 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.

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.

Esempio di richiesta:

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

Body
 {
"originalPreTaxAmount" : {
   "priceMicros" : "12634000000", # 12634 KRW
   "currency" : "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros" : "1263000000", # 1263 KRW
   "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 l'externalTransactionToken fornito all'app per la transazione di upgrade o downgrade. Il funzionamento è simile alla segnalazione di un nuovo acquisto.

Segnalare il download di un'app

Per segnalare l'installazione di un'app nel sistema di fatturazione per offerte esterne, devi chiamare Externaltransactions.createexternaltransaction, inviando l' externalTransactionToken fornito all'app. Segnala questa transazione come una tantum senza costi; questa procedura è simile alla segnalazione di una transazione iniziale. Assicurati di includere ExternalOfferDetails in nel corpo della richiesta.

Esempio di richiesta:

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

Body
 {
"originalPreTaxAmount" : {
   "priceMicros" : "0",
   "currency" : "USD"
 },
 "originalTaxAmount" : {
   "priceMicros" : "0",
   "currency" : "USD"
 },
"transactionTime" : "2025-12-22T12:45:00Z",
 "oneTimeTransaction" : {
   "externalTransactionToken" : "my_token",
 },
 "userTaxAddress" : {
   "regionCode" : "US"
 },
 "externalOfferDetails" : {
   "linkType" : "LINK_TO_APP_DOWNLOAD",
   "installedAppPackage" : "my.external.app",
   "installedAppCategory" : "APP"
 }
}

Eseguire la migrazione dalla segnalazione manuale delle transazioni di fatturazione alternativa

Per eseguire la migrazione degli abbonamenti attivi iniziati mentre offrivi la fatturazione alternativa senza segnalazione automatica, 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 eseguito la registrazione iniziale per ogni abbonamento attivo. Dopodiché, segnala normalmente ogni transazione successiva per questi abbonamenti tramite le API, fornendo l'initialExternalTransactionId utilizzato in precedenza 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 verificare che la migrazione non causi un'interruzione della quota. Se devi 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 dalla segnalazione manuale. Verrà ritirato quando la segnalazione manuale non sarà più supportata.

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

Requisiti per i programmi partner di Play

Gli sviluppatori che partecipano a programmi partner come il Programma Esperienza multimediale di Play devono fornire il transaction_program_code quando segnalano le transazioni esterne. Se sei uno sviluppatore idoneo, contatta il tuo responsabile dello Sviluppo aziendale per maggiori informazioni su come impostare questo campo.

Segnalare i rimborsi degli acquisti a Google Play

Integra l'API externaltransactions per segnalare le transazioni rimborsate agli utenti al di fuori del sistema di fatturazione di Google Play. Affinché Play identifichi correttamente la transazione rimborsata, devi includere l'externalTransactionId corrispondente della transazione segnalata in precedenza come parte dei parametri dell'URL.

Quando segnali i rimborsi degli acquisti di abbonamenti, fai riferimento all'externalTransactionId della ricorrenza specifica dell'abbonamento che viene rimborsato.

Esempio: supponi 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 segnalare un rimborso di tutte le transazioni per l'abbonamento, devi effettuare tre richieste di rimborso separate: una per la transazione iniziale e due per le transazioni successive.

Questo metodo accetta sia i rimborsi completi (in cui l'importo è lo stesso importo pagato dall'utente nella transazione esterna originale) sia i 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 netto delle imposte rimborsato.

Quote API

L'API Externaltransactions è soggetta a quote API per tutte le chiamate, proprio 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.