Guida di riferimento alle notifiche in tempo reale per lo sviluppatore

Questo documento elenca e descrive i tipi di notifiche in tempo reale per lo sviluppatore che puoi ricevere da Google Play.

Nota: dopo aver ricevuto le notifiche in tempo reale per lo sviluppatore, devi chiamare l' API Google Play Developer per ottenere lo stato completo e aggiornare il tuo stato di backend. Queste notifiche ti informano solo che lo stato dell'acquisto è cambiato. Non forniscono informazioni complete sull'acquisto.

Codifica

Ogni pubblicazione in un argomento di Cloud Pub/Sub contiene un singolo campo di dati con codifica in base64.

{
  "message": {
    "attributes": {
      "key": "value"
    },
    "data": "eyAidmVyc2lvbiI6IHN0cmluZywgInBhY2thZ2VOYW1lIjogc3RyaW5nLCAiZXZlbnRUaW1lTWlsbGlzIjogbG9uZywgIm9uZVRpbWVQcm9kdWN0Tm90aWZpY2F0aW9uIjogT25lVGltZVByb2R1Y3ROb3RpZmljYXRpb24sICJzdWJzY3JpcHRpb25Ob3RpZmljYXRpb24iOiBTdWJzY3JpcHRpb25Ob3RpZmljYXRpb24sICJ0ZXN0Tm90aWZpY2F0aW9uIjogVGVzdE5vdGlmaWNhdGlvbiB9",
    "messageId": "136969346945"
  },
  "subscription": "projects/myproject/subscriptions/mysubscription"
}

Nota: Il campo messageId è un identificatore univoco per la notifica. Tuttavia, ti consigliamo di verificare l'unicità di questi ID per evitare di elaborare notifiche duplicate ed effettuare chiamate API di backend ridondanti, il che contribuisce a ottimizzare l'utilizzo della quota API.

Dopo aver decodificato il campo di dati con codifica in base64, DeveloperNotification contiene i seguenti campi:

{
  "version": string,
  "packageName": string,
  "eventTimeMillis": long,
  "oneTimeProductNotification": OneTimeProductNotification,
  "subscriptionNotification": SubscriptionNotification,
  "voidedPurchaseNotification": VoidedPurchaseNotification,
  "pendingRefundReviewNotification": PendingRefundReviewNotification,
  "testNotification": TestNotification
}

Questi campi sono descritti nella tabella seguente.

Nome proprietà	Valore	Descrizione
versione	stringa	La versione di questa notifica. Inizialmente, è "1.0". Questa versione è diversa dagli altri campi Version.
packageName	stringa	Il nome del pacchetto dell'applicazione a cui si riferisce questa notifica a (ad esempio, `com.some.thing`).
eventTimeMillis	lungo	Il timestamp in cui si è verificato l'evento, in millisecondi da l'epoca.
subscriptionNotification	SubscriptionNotification	Se questo campo è presente, la notifica è relativa a un abbonamento e contiene informazioni aggiuntive sull' abbonamento. Tieni presente che questo campo è mutuamente esclusivo con pendingRefundReviewNotification, oneTimeProductNotification, voidedPurchaseNotification, e testNotification.
oneTimeProductNotification	OneTimeProductNotification	Se questo campo è presente, la notifica è relativa a un acquisto una tantum e contiene informazioni aggiuntive sull'acquisto. Tieni presente che questo campo è mutuamente esclusivo con pendingRefundReviewNotification, subscriptionNotification, voidedPurchaseNotification e testNotification.
voidedPurchaseNotification	VoidedPurchaseNotification	Se questo campo è presente, la notifica è relativa a un acquisto annullato e contiene informazioni aggiuntive relative all'acquisto annullato. Tieni presente che questo campo è mutuamente esclusivo con pendingRefundReviewNotification, oneTimeProductNotification, subscriptionNotification e testNotification.
pendingRefundReviewNotification	PendingRefundReviewNotification	Se questo campo è presente, la notifica è relativa a una richiesta di storno di addebito per la quale puoi suggerire una risoluzione. Rispondi a questa notifica chiamando l'API `ReviewRefund`. Tieni presente che questo campo è mutuamente esclusivo con subscriptionNotification, oneTimeProductNotification, voidedPurchaseNotification, e testNotification.
testNotification	TestNotification	Se questo campo è presente, la notifica è relativa a una pubblicazione di test. Queste notifiche vengono inviate solo tramite la Console per gli sviluppatori di Google Play. Tieni presente che questo campo è mutuamente esclusivo con pendingRefundReviewNotification, oneTimeProductNotification, subscriptionNotification e voidedPurchaseNotification.

SubscriptionNotification

Un SubscriptionNotification contiene i seguenti campi:

{
  "version": string,
  "notificationType": int,
  "purchaseToken": string
}

Nome proprietà	Valore	Descrizione
versione	stringa	La versione di questa notifica. Inizialmente, è "1.0". Questa versione è diversa dagli altri campi Version.
notificationType	int	Il notificationType per un abbonamento può avere i seguenti valori: (1) SUBSCRIPTION_RECOVERED: un abbonamento è stato recuperato dalla sospensione dell'account o riattivato dalla pausa. (2) SUBSCRIPTION_RENEWED: un abbonamento attivo è stato rinnovato. (3) SUBSCRIPTION_CANCELED: un abbonamento è stato annullato volontariamente o involontariamente. Per l'annullamento volontario, viene inviato quando l'utente annulla l'abbonamento. (4) SUBSCRIPTION_PURCHASED: è stato acquistato un nuovo abbonamento. (5) SUBSCRIPTION_ON_HOLD: un abbonamento è stato messo in sospensione dell'account hold (se abilitata). (6) SUBSCRIPTION_IN_GRACE_PERIOD: un abbonamento è entrato nel periodo di tolleranza (se abilitato). (7) SUBSCRIPTION_RESTARTED: l'utente ha ripristinato il suo abbonamento da Play > Account > Abbonamenti. L'abbonamento è stato annullato, ma non era ancora scaduto quando l'utente lo ha ripristinato. Per ulteriori informazioni, vedi Ripristinare prima della scadenza. (8) SUBSCRIPTION_PRICE_CHANGE_CONFIRMED (DEPRECATO): l'utente ha confermato correttamente una modifica del prezzo dell'abbonamento. (9) SUBSCRIPTION_DEFERRED: il tempo di ricorrenza di un abbonamento è stato esteso. (10) SUBSCRIPTION_PAUSED: un abbonamento è stato messo in pausa. (11) SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED: la pianificazione della pausa di un abbonamento è stata modificata. (12) SUBSCRIPTION_REVOKED: un abbonamento è stato revocato all'utente prima della scadenza. (13) SUBSCRIPTION_EXPIRED: un abbonamento è scaduto. (17) SUBSCRIPTION_ITEMS_CHANGED: un articolo in un pacchetto di abbonamento è stato modificato. (18) SUBSCRIPTION_CANCELLATION_SCHEDULED: è stato pianificato l'annullamento di un abbonamento a rate che diventerà effettivo al termine del periodo di impegno. (19) SUBSCRIPTION_PRICE_CHANGE_UPDATED: i dettagli della modifica del prezzo di un articolo di abbonamento sono stati aggiornati. (20) SUBSCRIPTION_PENDING_PURCHASE_CANCELED: una transazione in attesa di un abbonamento è stata annullata. (22) SUBSCRIPTION_PRICE_STEP_UP_CONSENT_UPDATED: è iniziato il periodo di consenso per l'aumento del prezzo di un abbonamento oppure l'utente ha fornito il consenso per l'aumento del prezzo. Questa notifica in tempo reale per lo sviluppatore viene inviata solo per gli abbonamenti in una regione in cui è richiesto l'aumento del prezzo.
purchaseToken	stringa	Il token fornito al dispositivo dell'utente al momento dell'acquisto dell'abbonamento.

Esempio

Ecco un esempio di notifica per un nuovo acquisto di un abbonamento:

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503349566168",
  "subscriptionNotification":
  {
    "version":"1.0",
    "notificationType":4,
    "purchaseToken":"PURCHASE_TOKEN"
  }
}

OneTimeProductNotification

Nota: Un OneTimeProductNotification viene inviato solo se hai scelto di ricevere eventi di acquisto di prodotti a pagamento singolo. Per ulteriori informazioni, vedi Attivare le notifiche in tempo reale per lo sviluppatore per la tua app.

Un OneTimeProductNotification contiene i seguenti campi:

{
  "version": string,
  "notificationType": int,
  "purchaseToken": string,
  "sku": string
}

Nome proprietà	Valore	Descrizione
versione	stringa	La versione di questa notifica. Inizialmente, sarà "1.0". Questa versione è diversa dagli altri campi Version.
notificationType	int	Il tipo di notifica. Può avere i seguenti valori: (1) ONE_TIME_PRODUCT_PURCHASED: un prodotto a pagamento singolo è stato acquistato da un utente. (2) ONE_TIME_PRODUCT_CANCELED: l'acquisto di un prodotto a pagamento singolo è stato annullato o revocato.
purchaseToken	stringa	Il token fornito al dispositivo dell'utente al momento dell'acquisto.
sku	stringa	L'ID del prodotto una tantum acquistato (ad esempio, "sword_001").

Esempio

Ecco un esempio di notifica per un nuovo acquisto una tantum:

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503349566168",
  "oneTimeProductNotification":
  {
    "version":"1.0",
    "notificationType":1,
    "purchaseToken":"PURCHASE_TOKEN",
    "sku":"my.sku"
  }
}

VoidedPurchaseNotification

Un VoidedPurchaseNotification contiene i seguenti campi:

Nome proprietà	Valore	Descrizione
purchaseToken	string	Il token associato all'acquisto annullato. Queste informazioni vengono fornite allo sviluppatore quando viene effettuato un nuovo acquisto
orderId	string	L'ID ordine univoco associato alla transazione che è stato annullato. Per gli acquisti una tantum, questo rappresenta l'unico ID ordine generato per l'acquisto. Per gli abbonamenti con rinnovo automatico, viene generato un nuovo ID ordine per ogni transazione di rinnovo.
productType	int	Il productType per un acquisto annullato può avere i seguenti valori: (1) PRODUCT_TYPE_SUBSCRIPTION - L'acquisto di un abbonamento è stato annullato. (2) PRODUCT_TYPE_ONE_TIME - L'acquisto una tantum è stato annullato.
refundType	int	Il refundType per un acquisto annullato può avere i seguenti valori: (1) REFUND_TYPE_FULL_REFUND - L'acquisto è stato annullato completamente. (2) REFUND_TYPE_QUANTITY_BASED_PARTIAL_REFUND - L'acquisto è stato annullato parzialmente da un rimborso parziale basato sulla quantità, applicabile solo agli acquisti di più quantità. Un acquisto può essere annullato parzialmente più volte. Tieni presente che quando viene rimborsata la quantità totale rimanente di un acquisto di più quantità, il refundType sarà REFUND_TYPE_FULL_REFUND.

Esempio

Ecco un esempio di notifica per un nuovo acquisto annullato:

{
  "version":"1.0",
  "packageName":"com.some.app",
  "eventTimeMillis":"1503349566168",
  "voidedPurchaseNotification":
  {
    "purchaseToken":"PURCHASE_TOKEN",
    "orderId":"GS.0000-0000-0000",
    "productType":1
    "refundType":1
  }
}

Utilizzare VoidedPurchaseNotification

Quando il client RTDN riceve un VoidedPurchaseNotification, prendi nota delle seguenti informazioni:

• packageName: identifica l'app.
• eventTimeMillis: ti informa dell'ora in cui si è verificata la modifica dello stato.
• purchaseToken: il token fornito al dispositivo dell'utente al momento dell'acquisto del prodotto.
• orderId: identifica l'ordine associato alla transazione annullata.
• productType: indica se l'acquisto annullato era un acquisto in-app o un abbonamento.
• refundType: specifica il tipo di rimborso che ha annullato l'acquisto.

Suggerimento: se devi solo individuare l'acquisto e l'ordine giusti per le modifiche dei diritti, le informazioni fornite in VoidedPurchaseNotification sono sufficienti. Per ulteriori dati sugli acquisti annullati, utilizza l'API Google Play Voided Purchases. Questa API fornisce un modello pull per recuperare i dati degli acquisti annullati in un intervallo di timestamp specificato.

Nota: per gli acquisti di più quantità annullati parzialmente, il refundableQuantity campo fornito da purchases.productsv2 contiene il numero rimanente di prodotti acquistati che non sono stati annullati.

PendingRefundReviewNotification

Un PendingRefundReviewNotification viene inviato quando un utente richiede uno storno di addebito per un acquisto e la richiesta richiede la revisione dello sviluppatore. Quando ricevi questa notifica, devi valutare la richiesta e fornire un suggerimento di rimborso e una prova dell'utilizzo dell'acquisto entro 24 ore chiamando l'API ReviewRefund.

Nota: le revisioni in sospeso supportano solo CHARGEBACK come motivo del rimborso.

Un PendingRefundReviewNotification contiene i seguenti campi:

{
  "version": string,
  "pendingRefundToken": string,
  "orderId": string,
  "refundReason": int,
  "obfuscatedAccountId": string,
  "obfuscatedProfileId": string
}

Nome proprietà	Valore	Descrizione
versione	stringa	La versione di questa notifica. Inizialmente, è "1.0". Questa versione è diversa dagli altri campi Version.
pendingRefundToken	stringa	Un token univoco che identifica la richiesta di rimborso in sospeso in fase di revisione. Passa questo token quando chiami l'API ReviewRefund.
orderId	stringa	L'ID ordine dell'acquisto soggetto alla revisione del rimborso in sospeso.
refundReason	int	Il motivo della richiesta di rimborso. Le revisioni in sospeso supportano solo CHARGEBACK (7) come motivo del rimborso. Il codice deve gestire i nuovi motivi man mano che diventano disponibili.
obfuscatedAccountId	stringa	(Se applicabile) L'ID account utente offuscato specificato dallo sviluppatore fornito al momento dell'acquisto.
obfuscatedProfileId	stringa	(Se applicabile) L'ID profilo offuscato specificato dallo sviluppatore fornito al momento dell'acquisto.

Esempio

Ecco un esempio di notifica di revisione del rimborso in sospeso:

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503350156918",
  "pendingRefundReviewNotification":
  {
    "version":"1.0",
    "pendingRefundToken":"example-token",
    "orderId":"GPA.1234-5678-9012-34567",
    "refundReason":7,
    "obfuscatedAccountId":"user-account-id",
    "obfuscatedProfileId":"user-profile-id"
  }
}

TestNotification

Un TestNotification contiene i seguenti campi:

{
  "version": string
}

Nome proprietà	Valore	Descrizione
versione	stringa	La versione di questa notifica. Inizialmente, è "1.0". Questa versione è diversa dagli altri campi Version.

Esempio

Ecco un esempio di notifica di test:

{
  "version":"1.0",
  "packageName":"com.some.thing",
  "eventTimeMillis":"1503350156918",
  "testNotification":
  {
    "version":"1.0"
  }
}