Gestion des produits d'abonnement depuis votre service

Pour les produits d’abonnement, utilisez un service back-end pour valider l’état et gérer les opérations de cycle de vie. Les API Recurrence offrent à vos équipes de support et de live-ops un moyen fiable d’inspecter, de prolonger ou d’annuler des abonnements. Cet article explique comment utiliser les points de terminaison Recurrence pour ces scénarios.

​

Utilisation de la bibliothèque .NET Microsoft.StoreServices et de l’exemple

Pour illustrer les principes et les flux décrits dans cet article, consultez l’exemple Microsoft.StoreServices. L’exemple utilise la bibliothèque Microsoft.StoreServices pour gérer l’authentification et effectuer les appels aux services du Microsoft Store. Le service d’exemple lui-même contient une logique d’exemple pour gérer les produits d’abonnement et fournit un guide de configuration pour sa mise en place.

• Microsoft.StoreServices (GitHub)
• Exemple Microsoft.StoreServices (GitHub)

​

Types de produits d’abonnement

Les types de produits d’abonnement géré par le Store et d’abonnement de type extension fonctionnent tous deux avec le service Recurrence pour afficher et gérer l’abonnement de l’utilisateur. Pour plus d’informations sur chacun de ces types de produits, consultez Choix du type de produit approprié

​

Interrogation de l’abonnement d’un utilisateur

Utilisez purchase.mp.microsoft.com/v8.0/b2b/recurrences/query comme point de terminaison principal pour l’état de l’abonnement. Il retourne les périodes d’abonnement actives et historiques, ainsi que le subscriptionId nécessaire aux opérations de modification. Il inclut également les champs requis pour distinguer les périodes de grâce (Grace) et de relance (Dunning). Les API Collections (b2bLicensePreview (v8) et publisherQuery (v9)) peuvent indiquer un droit d’abonnement actif, mais pas le même niveau de détail sur la récurrence.

​

Délai entre la satisfaction des vérifications de droits sur le client et en serveur à serveur

Lorsque vous publiez une mise à jour ajoutant de nouveaux éléments (droits satisfaisants) à un bundle, il existe un délai de visibilité des nouveaux éléments entre les requêtes d’API côté client et les requêtes d’API de serveur à serveur. Ce délai est dû au fait que les différents systèmes du Store mettent à jour leurs caches de catalogue à des intervalles différents. Lorsque la modification est publiée dans le catalogue, les services de licence locaux obtiennent généralement les informations mises à jour en premier, et les caches utilisés par publisherQuery deux à trois heures plus tard. Par conséquent, prévoyez quelques heures pendant lesquelles les API côté client accordent l’accès alors que vos appels de serveur à serveur ne reflètent pas encore la propriété des nouveaux éléments. Le service Recurrence lui-même n’est pas affecté, seuls les points de terminaison publisherQuery ou b2bLicensePreview qui interrogent les droits satisfaisants sur les éléments nouvellement ajoutés le sont.

​

Comprendre les dates de début, de renouvellement et d’expiration d’un abonnement

La date StartTime d’un abonnement est la date à laquelle l’abonnement actif a commencé. Si l’abonnement est configuré pour le renouvellement automatique, la date de début reste la même, mais les dates d’expiration changent à mesure que l’abonnement est renouvelé au cours des mois suivants. Si un abonnement est annulé, expiré ou révoqué, un nouvel objet d’abonnement est créé lorsque l’utilisateur achète à nouveau l’abonnement. La nouvelle période d’abonnement active a pour StartTime le jour où l’utilisateur a activé ou acheté le nouvel abonnement. Les périodes d’abonnement dans le Microsoft Store sont normalement configurées sous forme de nombre de mois. Par exemple, 1 mois, 3 mois ou 12 mois. Lorsqu’un utilisateur achète un abonnement d’un mois, le StartTime est minuit UTC (00:00:00) du jour où il a commencé l’abonnement. ExpirationTime correspond au nombre de mois (et non de jours) ajouté au StartTime, moins une seconde (23:59:59 UTC).
Cette valeur permet à l’abonnement d’expirer juste avant minuit UTC. Cependant, certains mois comportent un nombre de jours différent, ce qui crée un conflit pour les abonnements commençant le 29, le 30 ou le 31 d’un mois.
Si le StartTime de l’utilisateur tombe l’un de ces jours, l’ExpirationTime est modifié pour être 23:59:59 UTC le dernier jour du mois d’expiration. Ainsi, la date de renouvellement est toujours minuit UTC (00:00:00) le premier jour du mois par la suite, et l’ExpirationTime est toujours 23:59:59 UTC le dernier jour du mois.

​

Exemple de comportement des dates de début, de renouvellement et d’expiration d’un abonnement d’un mois

​

Comprendre les états Grace et Dunning

Si un paiement de renouvellement automatique échoue à l’ExpirationTime, l’abonnement passe en période de grâce (Grace), puis en période de relance (Dunning) si le problème n’est toujours pas résolu. Les deux périodes signalent l’état InDunning ; déterminez donc la période en cours en comparant l’heure UTC actuelle à ExpirationTimeWithGrace. Lorsque l’abonnement d’un utilisateur est en période Grace ou Dunning, vous devez inviter les utilisateurs à vérifier l’état de leur facturation sur Services et abonnements du compte Microsoft. Pour placer correctement un compte dans chacun de ces états à des fins de test, consultez Test des produits d’abonnement.

​

Période de grâce (Grace)

Pendant la période Grace, maintenez les avantages de l’abonnement activés pendant que le Store retente le paiement du renouvellement. Si le renouvellement réussit, les jours de grâce utilisés sont déduits de la période suivante. Si le paiement n’est pas résolu avant ExpirationTimeWithGrace, l’abonnement passe en période Dunning.

​

Période de relance (Dunning)

La période Dunning commence à la fin de la période Grace. Désactivez les avantages de l’abonnement pendant cette période. Les utilisateurs ne peuvent pas racheter ni utiliser un code pour le même abonnement pendant la période Dunning. Si le paiement reste non résolu pendant toute la période Dunning, l’abonnement devient inactif.

​

Durées des périodes Grace et Dunning

​

Modification de l’abonnement d’un utilisateur

Vos services peuvent également modifier les abonnements avec purchase.mp.microsoft.com/v8.0/b2b/recurrences//change. Les opérations prises en charge incluent l’ajout de jours, la désactivation du renouvellement automatique et l’annulation de l’abonnement. Votre service a besoin du recurrenceId (même valeur que id de l’API RecurrenceQuery et que les valeurs recurrenceData de l’API de requête Collections) pour agir sur l’abonnement de l’utilisateur. Voici quelques exemples d’utilisation du point de terminaison Recurrence Change avec vos services :

• Ajout de temps aux abonnements des utilisateurs ayant subi une interruption de service.
• Intégration avec vos équipes de support client pour aider les utilisateurs avec des informations sur l’état de leur abonnement, les annulations, etc.
• Interface utilisateur dans le jeu permettant aux utilisateurs de modifier des paramètres tels que le renouvellement automatique ou de mettre fin à leur abonnement.

​

Test des produits d’abonnement

L’API Recurrence Change peut également être utilisée pour les tests. Extend accepte des valeurs de jours négatives, ce qui vous permet de faire avancer un abonnement de test vers les états ciblés.

​

Test des états Active, Inactive et Canceled

Lorsque vous testez les états Active, Inactive et Canceled d’un abonnement, vous pouvez utiliser un prix de base de $0.00 pour l’abonnement. Ajoutez l’abonnement au compte de test pour vérifier l’état Active et utilisez le point de terminaison Recurrence Change pour désactiver le renouvellement automatique. Utilisez ensuite le point de terminaison Recurrence Change pour annuler l’abonnement ou soustraire suffisamment de jours pour que l’ExpirationTime soit antérieur à la date et l’heure UTC actuelles.

​

Test des états Grace et Dunning

Pour tester les états Grace et Dunning, l’abonnement doit avoir un prix non nul.
De plus, le compte de test doit être configuré de manière à ce que les paiements ultérieurs échouent une fois l’ExpirationTime passé. Actuellement, le Microsoft Store ne dispose pas d’instruments de paiement de test ; le moyen le plus simple de configurer un compte consiste donc à utiliser des codes de devise prépayés comme suit :

1. Configurez l’abonnement avec un prix bas, par exemple $0.99, dans votre environnement de test.
2. Achetez une carte cadeau prépayée XBOX de $1.00 ou$2.00 pour couvrir le premier achat de l’abonnement (taxes comprises), mais pas le renouvellement.
3. Utilisez la carte cadeau sur votre compte de test.
4. Achetez l’abonnement sur le compte de test.
5. Assurez-vous que le renouvellement automatique est activé pour l’abonnement, mais que les fonds sont insuffisants pour le renouveler.
6. Utilisez Recurrence Change pour placer l’ExpirationTime de l’abonnement dans les prochaines 24 heures (consultez la remarque suivante).
7. Attendez que l’ExpirationTime soit naturellement dépassé et que l’état affiche InDunning (cela peut prendre jusqu’à 24 heures après l’ExpirationTime).

Pour obtenir un comportement Grace -> Dunning -> Inactive exact, laissez le compte progresser naturellement après avoir configuré le test.

​

Voir aussi

Vue d’ensemble du commerce API de service du Microsoft Store purchase.mp.microsoft.com/v8.0/b2b/recurrences/query purchase.mp.microsoft.com/v8.0/b2b/recurrences//change Bibliothèque Microsoft.StoreServices (GitHub) Exemple Microsoft.StoreServices (GitHub)