Guide de référence des notifications en temps réel pour les développeurs

Ce document liste et décrit les types de notifications en temps réel pour les développeurs que vous pouvez recevoir de Google Play.

Remarque : Vous devez appeler l'API Google Play Developer après avoir reçu des notifications en temps réel pour les développeurs afin d'obtenir l'état complet et mettre à jour votre propre état de backend. Ces notifications vous indiquent uniquement que l'état de l'achat a changé. Elles ne vous fournissent pas toutes les informations sur l'achat.

Encodage

Chaque publication effectuée sur un sujet Cloud Pub/Sub ne contient qu'un seul champ de données encodé en base64.

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

Remarque : Le champ messageId est un identifiant unique pour la notification. Toutefois, nous vous recommandons de vérifier l'unicité de ces ID pour éviter de traiter des notifications en double et d'effectuer des appels d'API backend redondants, ce qui vous aidera à optimiser l'utilisation de votre quota d'API.

Après avoir décodé le champ de données encodé en base64, DeveloperNotification contient les champs suivants :

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

Ces champs sont décrits dans le tableau suivant.

Nom de propriété	Valeur	Description
version	string	Version de cette notification. Dans un premier temps, la version correspond à "1.0". Cette version est différente des autres champs de version.
packageName	string	Nom de package de l'application auquel cette notification se rapporte (par exemple, "com.exemple.XXX").
eventTimeMillis	long	Horodatage de l'événement (en millisecondes à partir de la date initiale de référence du système d'exploitation).
subscriptionNotification	SubscriptionNotification	Si ce champ est présent, cette notification est liée à un abonnement. Ce champ contient des informations supplémentaires sur l'abonnement. Notez que les champs pendingRefundReviewNotification, oneTimeProductNotification, voidedPurchaseNotification et testNotification s'excluent mutuellement.
oneTimeProductNotification	OneTimeProductNotification	Si ce champ est présent, cette notification est associée à un achat ponctuel, et ce champ contient des informations supplémentaires concernant l'achat. Notez que les champs pendingRefundReviewNotification, subscriptionNotification, voidedPurchaseNotification et testNotification s'excluent mutuellement.
voidedPurchaseNotification	VoidedPurchaseNotification	Si ce champ est présent, cette notification est liée à un achat annulé, et ce champ contient des informations supplémentaires la concernant. Notez que les champs pendingRefundReviewNotification, oneTimeProductNotification, subscriptionNotification, et testNotification s'excluent mutuellement.
pendingRefundReviewNotification	PendingRefundReviewNotification	Si ce champ est présent, cette notification est liée à une demande de rétrofacturation pour laquelle vous pouvez suggérer une résolution. Répondez à cette notification en appelant l'API `ReviewRefund`. Notez que les champs subscriptionNotification, oneTimeProductNotification, voidedPurchaseNotification, et testNotification s'excluent mutuellement.
testNotification	TestNotification	Si ce champ est présent, cette notification est liée à une publication test. Elle n'est envoyée que via la Google Play Developer Console. Notez que les champs pendingRefundReviewNotification, oneTimeProductNotification, subscriptionNotification et voidedPurchaseNotification s'excluent mutuellement.

SubscriptionNotification

SubscriptionNotification contient les champs suivants :

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

Nom de propriété	Valeur	Description
version	string	Version de cette notification. Dans un premier temps, la version correspond à "1.0". Cette version est différente des autres champs de version.
notificationType	int	Le type de notification d'un abonnemment peut avoir les valeurs suivantes : (1) SUBSCRIPTION_RECOVERED : l'abonnement a été récupéré suite à un blocage de compte ou a été réactivé après une suspension. (2) SUBSCRIPTION_RENEWED : un abonnement actif a été renouvelé. (3) SUBSCRIPTION_CANCELED : un abonnement a été résilié volontairement ou involontairement. Pour une résiliation volontaire, cette notification est envoyée au moment de la résiliation. (4) SUBSCRIPTION_PURCHASED : un nouvel abonnement a été souscrit. (5) SUBSCRIPTION_ON_HOLD : un abonnement vient de passer à l'état "blocage de compte" (le cas échéant). (6) SUBSCRIPTION_IN_GRACE_PERIOD : l'abonnement est passé en période de grâce (le cas échéant). (7) SUBSCRIPTION_RESTARTED : l'utilisateur a restauré son abonnement depuis Play > Compte > Abonnements. L'abonnement a été résilié, mais n'a pas encore expiré lorsque l'utilisateur effectue une restauration. Pour en savoir plus, consultez la section Restaurations. (8) SUBSCRIPTION_PRICE_CHANGE_CONFIRMED (OBSOLÈTE) : l'utilisateur a confirmé le changement de prix de son abonnement. (9) SUBSCRIPTION_DEFERRED : La durée de récurrence d'un abonnement a été prolongée. (10) SUBSCRIPTION_PAUSED : un abonnement a été suspendu. (11) SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED : la planification de la suspension de l'abonnement a été modifiée. (12) SUBSCRIPTION_REVOKED : l'utilisateur a révoqué un abonnement avant la date d'expiration. (13) SUBSCRIPTION_EXPIRED : un abonnement a expiré. (17) SUBSCRIPTION_ITEMS_CHANGED : un article d'un pack d'abonnement a été modifié. (18) SUBSCRIPTION_CANCELLATION_SCHEDULED : une résiliation d'abonnement à paiement échelonné a été programmée pour prendre effet à la fin de la période d'engagement. (19) SUBSCRIPTION_PRICE_CHANGE_UPDATED : les détails du changement de prix d'un article d'abonnement ont été mis à jour. (20) SUBSCRIPTION_PENDING_PURCHASE_CANCELED : une transaction en attente d'un abonnement a été annulée. (22) SUBSCRIPTION_PRICE_STEP_UP_CONSENT_UPDATED : la période de consentement d'un abonnement pour une augmentation de prix a commencé ou l'utilisateur a donné son consentement pour l'augmentation de prix. Cette notification en temps réel pour les développeurs n'est envoyée que pour les abonnements dans une région où l'augmentation de prix est obligatoire.
purchaseToken	string	Jeton fourni à l'appareil de l'utilisateur lors de la souscription de l'abonnement.

Exemple

Voici un exemple de notification concernant un nouvel abonnement :

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

OneTimeProductNotification

Remarque : Une OneTimeProductNotification n'est envoyée que si vous avez choisi de recevoir des événements d'achat de produits ponctuels. Pour en savoir plus, consultez Activer les notifications en temps réel pour les développeurs pour votre application.

OneTimeProductNotification contient les champs suivants :

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

Nom de la propriété	Valeur	Description
version	string	Version de cette notification. Dans un premier temps, la version correspond à "1.0". Cette version est différente des autres champs de version.
notificationType	int	Type de notification. Les valeurs suivantes sont possibles : (1) ONE_TIME_PRODUCT_PURCHASED : un produit ponctuel a bien été acheté par un utilisateur. (2) ONE_TIME_PRODUCT_CANCELED : un achat ponctuel en attente a été annulé par l'utilisateur.
purchaseToken	string	Jeton fourni à l'appareil de l'utilisateur lors de l'achat.
sku	string	ID du produit ponctuel acheté (par exemple, "épée_001")

Exemple

Voici un exemple de notification concernant un nouvel achat ponctuel :

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

VoidedPurchaseNotification

VoidedPurchaseNotification contient les champs suivants :

Nom de la propriété	Valeur	Description
purchaseToken	string	Jeton associé à l'achat annulé. Ces informations sont fournies au développeur lorsqu'un nouvel achat est effectué.
orderId	string	ID de commande unique associé à la transaction annulée. Pour les achats uniques, il s'agit du seul ID de commande généré pour l'achat. Pour les abonnements à renouvellement automatique, un nouvel ID de commande est généré pour chaque transaction de renouvellement.
productType	int	Le productType d'un achat annulé peut avoir les valeurs suivantes : (1) PRODUCT_TYPE_SUBSCRIPTION : un achat d'abonnement a été annulé. (2) PRODUCT_TYPE_ONE_TIME : un achat unique a été annulé.
refundType	int	Le refundType d'un achat annulé peut avoir les valeurs suivantes : (1) REFUND_TYPE_FULL_REFUND : l'achat a été entièrement annulé. (2) REFUND_TYPE_QUANTITY_BASED_PARTIAL_REFUND : l'achat a été partiellement annulé par un remboursement partiel basé sur la quantité, applicable uniquement aux achats de quantités multiples. Un achat peut être partiellement annulé plusieurs fois. Notez que lorsque la quantité totale restante d'un achat de quantités multiples est remboursée, le refundType est REFUND_TYPE_FULL_REFUND.

Exemple

Voici un exemple de notification concernant un nouvel achat annulé :

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

Utiliser VoidedPurchaseNotification

Lorsque votre client RTDN reçoit une notification VoidedPurchaseNotification, tenez compte des informations suivantes :

• packageName: identifie l'application.
• eventTimeMillis: vous informe de l'heure à laquelle le changement d'état s'est produit.
• purchaseToken: jeton fourni à l'appareil de l'utilisateur lors de l'achat du produit.
• orderId: identifie la commande associée à la transaction annulée.
• productType: indique si l'achat annulé était un achat via une application ou un abonnement.
• refundType: spécifie le type de remboursement qui a annulé l'achat.

Conseil : Si vous n'avez besoin que de localiser le bon achat et la bonne commande pour les ajustements des droits d'accès, les informations fournies dans le VoidedPurchaseNotification suffisent. Pour obtenir des données supplémentaires sur les achats annulés, utilisez l'API Voided Purchases de Google Play. Cette API fournit un modèle pull pour récupérer les données d'achat annulées dans une plage d'horodatages spécifiée.

Remarque : Pour les achats de quantités multiples partiellement annulés, le champ refundableQuantity fourni par purchases.productsv2 contient le nombre restant de produits achetés qui n'ont pas été annulés.

PendingRefundReviewNotification

Une notification PendingRefundReviewNotification est envoyée lorsqu'un utilisateur demande une rétrofacturation pour un achat et que la demande nécessite un examen par le développeur. Lorsque vous recevez cette notification, vous devez évaluer la demande et fournir une suggestion de remboursement et une preuve d'utilisation de l'achat dans les 24 heures en appelant l' ReviewRefund API.

Remarque : Les examens en attente n'acceptent que CHARGEBACK comme motif de remboursement.

PendingRefundReviewNotification contient les champs suivants :

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

Nom de propriété	Valeur	Description
version	string	Version de cette notification. Dans un premier temps, la version correspond à "1.0". Cette version est différente des autres champs de version.
pendingRefundToken	string	Jeton unique qui identifie la demande de remboursement en attente en cours d'examen. Transmettez ce jeton lorsque vous appelez l'API ReviewRefund.
orderId	string	ID de commande de l'achat soumis à l'examen du remboursement en attente.
refundReason	int	Motif de la demande de remboursement. Les examens en attente n'acceptent que CHARGEBACK (7) comme motif de remboursement. Votre code doit gérer les nouveaux motifs à mesure qu'ils deviennent disponibles.
obfuscatedAccountId	string	(Le cas échéant) ID de compte utilisateur obscurci spécifié par le développeur qui a été fourni lors de l'achat.
obfuscatedProfileId	string	(Le cas échéant) ID de profil obscurci spécifié par le développeur qui a été fourni lors de l'achat.

Exemple

Voici un exemple de notification d'examen de remboursement en attente :

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

TestNotification contient les champs suivants :

{
  "version": string
}

Nom de propriété	Valeur	Description
version	string	Version de cette notification. Dans un premier temps, la version correspond à "1.0". Cette version est différente des autres champs de version.

Exemple

Voici un exemple de notification test :

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