Versions d’évaluation et achats in-app

Achats in-app et versions d’essai avec l’espace de noms Windows.Services.Store

Cette section fournit une vue d’ensemble des tâches et concepts importants pour l’espace de noms Windows.Services.Store. Cet espace de noms est disponible uniquement pour les applications qui ciblent Windows 10 Édition anniversaire (10.0 ; Build 14393) ou une version ultérieure dans Visual Studio (qui correspond à Windows 10 version 1607). Nous recommandons l’utilisation de l’espace de noms Windows.Services.Store plutôt que l’espace de noms Windows.ApplicationModel.Store dans les applications si possible. Pour plus d’informations sur l’espace de noms Windows.ApplicationModel.Store, consultez cet article.

Dans cette section

• Vidéo
• Bien démarrer avec la classe StoreContext
• Implémenter des achats in-app
• Implémenter la fonctionnalité d’essai
• Tester l’implémentation de vos achats in-app ou versions d’essai
• Reçus pour les achats in-app
• Utilisation de la classe StoreContext avec le Pont du bureau
• Produits, références SKU et disponibilités
• ID Store

Bien démarrer avec la classe StoreContext

Le point d’entrée principal de l’espace de noms Windows.Services.Store est la classe StoreContext. Cette classe fournit des méthodes que vous pouvez utiliser pour obtenir des informations sur l’application active et ses extensions disponibles, obtenir les informations de licence de l’application actuelle ou de ses extensions, acheter une application ou une extension pour l’utilisateur actif et accomplir d’autres tâches. Pour obtenir un objet StoreContext, effectuez l’une des opérations suivantes :

• Dans une application mono-utilisateur (c’est-à-dire une application qui ne s’exécute que dans le contexte de l’utilisateur qui l’a lancée), utilisez la méthode statique GetDefault pour obtenir un objet StoreContext que vous pouvez utiliser pour accéder aux données du Microsoft Store concernant l’utilisateur. La plupart des applications de plateforme Windows universelle (UWP) sont des applications mono-utilisateur.

  Windows.Services.Store.StoreContext context = StoreContext.GetDefault();
  

• Dans une application multi-utilisateur, utilisez la méthode statique GetForUser pour obtenir un objet StoreContext que vous pouvez utiliser pour accéder aux données du Microsoft Store concernant un utilisateur connecté avec son compte Microsoft pendant qu’il utilise l’application. L’exemple suivant obtient un objet StoreContext pour le premier utilisateur disponible.

  var users = await Windows.System.User.FindAllAsync();
  Windows.Services.Store.StoreContext context = StoreContext.GetForUser(users[0]);
  

Une fois que vous avez un objet StoreContext, vous pouvez commencer à appeler les méthodes de cet objet pour obtenir les informations produit du Store concernant l’application actuelle et ses extensions, récupérer les informations de licence de l’application actuelle et ses extensions, acheter une application ou une extension pour l’utilisateur actif et accomplir d’autres tâches. Pour plus d’informations sur les tâches courantes que vous pouvez effectuer à l’aide de cet objet, consultez les articles suivants :

• Obtenir les informations produit d’applications et d’extensions
• Obtenir les informations de licence d’applications et d’extensions
• Activer les achats in-app d’applications et d’extensions
• Activer les achats d’extensions consommables
• Activer les extensions par abonnement pour votre application
• Implémenter une version d’essai de votre application

Pour obtenir un exemple d’application qui montre comment utiliser StoreContext et d’autres types dans l’espace de noms Windows.Services.Store, consultez l’exemple Store.

Implémenter des achats in-app

Pour proposer un achat in-app aux clients de votre application à l’aide de l’espace de noms Windows.Services.Store :

1. Si votre application propose des extensions que peuvent acheter les clients, créez des soumissions d’extension pour votre application dans l’Espace partenaires.

2. Écrivez du code dans votre application pour récupérer les informations produit de votre application ou d’une extension proposée par votre application, puis déterminez si la licence est active (autrement dit, si l’utilisateur dispose d’une licence pour utiliser l’application ou l’extension). Si la licence n’est pas active, affichez une interface utilisateur qui propose l’application ou l’extension à la vente à l’utilisateur en tant qu’achat in-app.

3. Si l’utilisateur choisit d’acheter votre application ou extension, utilisez la méthode appropriée pour acheter le produit :

   • Si l’utilisateur achète votre application ou une extension durable, suivez les instructions dans Activer les achats in-app des applications et extensions.
   • Si l’utilisateur achète une extension consommable, suivez les instructions dans Activer les achats d’extensions consommables.
   • Si l’utilisateur achète une extension par abonnement, suivez les instructions dans Activer les extensions par abonnement pour votre application.

4. Testez votre implémentation en suivant les instructions sur les tests.

Implémenter la fonctionnalité d’essai

Pour exclure ou limiter des fonctionnalités dans une version d’essai de votre application avec l’espace de noms Windows.Services.Store :

1. Configurez votre application en tant qu’essai gratuit dans l’Espace partenaires.

2. Écrivez du code dans votre application pour récupérer les informations produit de votre application ou d’une extension proposée par votre application, puis déterminez si la licence associée à l’application est une licence d’essai.

3. Excluez ou limitez certaines fonctionnalités dans votre application s’il s’agit d’une version d’essai, puis activez les fonctionnalités lorsque l’utilisateur achète une licence complète. Pour plus d’informations et un exemple de code, consultez Implémenter une version d’essai de votre application.

4. Testez votre implémentation en suivant les instructions sur les tests.

Tester l’implémentation de vos achats in-app ou versions d’essai

Si votre application utilise des API dans l’espace de noms Windows.Services.Store pour implémenter un achat in-app ou une fonctionnalité d’essai, vous devez publier votre application dans le Store et la télécharger sur votre appareil de développement pour utiliser sa licence à des fins de test. Suivez ce processus pour tester votre code :

1. Si votre application n’est pas encore publiée et disponible dans le Store, assurez-vous qu’elle répond aux conditions minimales requises du Kit de certification des applications Windows, puis soumettez votre application dans l’Espace partenaires et assurez-vous qu’elle réussit le processus de certification. Vous pouvez configurer votre application afin qu’elle ne soit pas détectable dans le Store pendant que vous la testez. Veuillez noter la configuration appropriée des versions d’évaluation de package. Les versions d’évaluation de package mal configurées risquent de ne pas pouvoir être téléchargées.

2. Vérifiez ensuite que vous avez effectué les opération suivantes :

   • Écrire du code dans votre application qui utilise la classe StoreContext et d’autres types associés dans l’espace de noms Windows.Services.Store pour implémenter des achats in-app ou une fonctionnalité d’essai.
   • Si votre application propose une extension que peuvent acheter les clients, créez une soumission d’extension pour votre application dans l’Espace partenaires.
   • Si vous souhaitez exclure ou limiter certaines fonctionnalités dans une version d’essai de votre application, configurez votre application en tant qu’essai gratuit dans l’Espace partenaires.

3. Avec votre projet ouvert dans Visual Studio, cliquez sur le menu Projet, pointez sur Store, puis cliquez sur Associer l’application au Store. Suivez les instructions de l’Assistant pour associer le projet d’application à l’application dans votre compte Espace partenaires que vous voulez utiliser pour le test.

   Remarque

   Si vous n’associez pas votre projet à une application du Store, les méthodes StoreContext attribuent le code d’erreur 0x803F6107 à la propriété ExtendedError dans la valeur de retour. Cette valeur indique que le Store n’a aucune connaissance de l’application.

4. Si vous ne l’avez pas déjà fait, installez l’application que vous avez spécifiée à l’étape précédente à partir du Store, exécutez-la une seule fois, puis fermez-la. Cela permet de vous assurer qu’une licence valide pour l’application est installée sur votre appareil de développement.

5. Dans Visual Studio, commencez à exécuter ou déboguer votre projet. Votre code devrait récupérer les données d’application et d’extension à partir de l’application du Store que vous avez associée à votre projet local. Si vous êtes invité à réinstaller l’application, suivez les instructions, puis exécutez ou déboguez votre projet.

   Remarque

   Après avoir effectué ces étapes, vous pouvez continuer de mettre à jour le code de votre application, puis déboguer votre projet mis à jour sur votre ordinateur de développement sans soumettre de nouveaux packages d’application au Store. Vous devez uniquement télécharger la version Store de votre application sur votre ordinateur de développement une fois pour obtenir la licence locale qui sera utilisée pour les tests. Vous devez uniquement soumettre de nouveaux packages d’application au Store une fois que vous avez effectué vos tests et que vous souhaitez mettre à la disposition de vos clients l’achat in-app ou les fonctionnalités d’essai dans votre application.

Si votre application utilise l’espace de noms Windows.ApplicationModel.Store, vous pouvez utiliser la classe CurrentAppSimulator dans votre application pour simuler les informations de licence pendant les tests avant de soumettre votre application dans le Store. Pour plus d’informations, consultez Bien démarrer avec les classes CurrentApp et CurrentAppSimulator.

Reçus pour les achats in-app

L’espace de noms Windows.Services.Store ne fournit pas d’API que vous pouvez utiliser pour obtenir un reçu de transaction pour les achats réussis dans le code de votre application. C’est une expérience différente de celle des applications qui utilisent l’espace de noms Windows.ApplicationModel.Store, qui peut utiliser une API côté client pour récupérer un reçu de transaction.

Si vous implémentez des achats in-app à l’aide de l’espace de noms Windows.Services.Store et que vous souhaitez confirmer qu’un client donné a bien acheté une application ou une extension, vous pouvez utiliser la méthode de requête de produits dans l’API REST de collection du Microsoft Store. Les données de retour pour cette méthode confirment si le client spécifié dispose d’un droit pour un produit donné et fournissent les données de la transaction associée à l’acquisition du produit par l’utilisateur. L’API de collection du Microsoft Store utilise l’authentification Azure AD pour récupérer ces informations.

Utilisation de la classe StoreContext avec le Pont du bureau

Les applications de bureau qui utilisent le Pont du bureau peuvent utiliser la classe StoreContext pour implémenter des achats in-app et des versions d’essai. Toutefois, si vous avez une application de bureau Win32 ou une application de bureau avec un handle de fenêtre associé au framework de rendu (comme une application WPF ou de SDK d’application Windows), votre application doit configurer l’objet StoreContext pour spécifier quelle fenêtre applicative est la fenêtre propriétaire pour les boîtes de dialogue modales affichées par l’objet.

De nombreux membres StoreContext (et des membres d’autres types associés accessibles via l’objet StoreContext) affichent une boîte de dialogue modale à l’utilisateur pour les opérations liées au Store, telles que l’achat d’un produit. Si une application de bureau ne configure pas l’objet StoreContext pour spécifier la fenêtre propriétaire des boîtes de dialogue modales, cet objet retourne des données inexactes ou des erreurs.

Pour configurer un objet StoreContext dans une application de bureau qui utilise le Pont du bureau, suivez ces étapes.

Pour .NET 6 ou ultérieur

Si votre application est écrite en C# avec .NET 6 ou ultérieur, suivez ces étapes.

1. Assurez-vous que la propriété TargetFramework dans le fichier projet est définie sur une version spécifique du SDK Windows pour accéder aux API Windows Runtime, qui fournit un accès à l’espace de noms WinRT.Interop. Par exemple :

   <PropertyGroup>
     <!-- You can also target other versions of the Windows SDK and .NET, e.g. "net6.0-windows10.0.19041.0" -->
     <TargetFramework>net6.0-windows10.0.22000.0</TargetFramework>
   </PropertyGroup>
   

2. Obtenez un objet StoreContext à l’aide de la méthode GetDefault (ou GetForUser si votre application est une application multi-utilisateur), comme décrit précédemment dans cet article. Pour initialiser la boîte de dialogue avec le handle de fenêtre spécifié, utilisez les méthodes WinRT.Interop.WindowNative.GetWindowHandle et WinRT.Interop.InitializeWithWindow.Initialize (voir Récupérer un handle de fenêtre (HWND) et Afficher les objets d’interface utilisateur WinRT qui dépendent de CoreWindow).

   StoreContext context = StoreContext.GetDefault();
   // Obtain window handle by passing in pointer to the window object
   var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(windowObject);
   // Initialize the dialog using wrapper function for IInitializeWithWindow
   WinRT.Interop.InitializeWithWindow.Initialize(context, hwnd); 
   

Pour les versions antérieures de .NET ou C++

Si votre application est écrite avec une version antérieure de .NET ou en C++, suivez ces étapes.

1. Effectuez l’une des opérations suivantes pour permettre à votre application d’accéder à l’interface IInitializeWithWindow :

   • Si votre application est écrite dans un langage managé comme C# ou Visual Basic (antérieur à .NET 6), déclarez l’interface IInitializeWithWindow dans le code de votre application avec l’attribut ComImport, comme illustré dans l’exemple suivant en C#. Cet exemple suppose que votre fichier de code a une instruction using pour l’espace de noms System.Runtime.InteropServices.

     [ComImport]
     [Guid("3E68D4BD-7135-4D10-8018-9FB6D9F33FA1")]
     [InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
     public interface IInitializeWithWindow
     {
         void Initialize(IntPtr hwnd);
     }
     

   • Si votre application est écrite en C++, ajoutez une référence au fichier d’en-tête shobjidl.h dans votre code. Ce fichier d’en-tête contient la déclaration de l’interface IInitializeWithWindow.

2. Récupérez un objet StoreContext en utilisant la méthode GetDefault (ou la méthode GetForUser si votre application est une application multi-utilisateur) comme décrit plus haut dans cet article, puis castez cet objet en objet IInitializeWithWindow. Ensuite, appelez la méthode IInitializeWithWindow.Initialize et passez le handle de la fenêtre que vous voulez comme propriétaire pour toutes les boîtes de dialogue modales affichées par les méthodes StoreContext. L’exemple C# suivant montre comment passer le handle de la fenêtre principale de votre application à la méthode. Consultez également Récupérer un handle de fenêtre (HWND) et Afficher les objets d’interface utilisateur WinRT qui dépendent de CoreWindow.

   StoreContext context = StoreContext.GetDefault();
   IInitializeWithWindow initWindow = (IInitializeWithWindow)(object)context;
   initWindow.Initialize(System.Diagnostics.Process.GetCurrentProcess().MainWindowHandle);
   

Produits, références SKU et disponibilités

Chaque produit du Store a au moins une référence SKU et chaque référence SKU a au moins une disponibilité. La plupart des développeurs ignorent ces concepts dans l’Espace partenaires et ne définissent jamais les références SKU ou les disponibilités de leurs applications ou extensions. Toutefois, comme le modèle objet des produits du Store dans l’espace de noms Windows.Services.Store contient des références SKU et des disponibilités, comprendre ces concepts peut être utile pour certains scénarios.

ID Store

Chaque application, extension ou autre produit du Store a un ID Store associé (appelé parfois également ID Store produit). De nombreuses API nécessitent l’ID Store pour effectuer une opération sur une application ou une extension.

L’ID Store de tous les produits du Store est une chaîne alphanumérique de 12 caractères, telle que 9NBLGGH4R315. Il existe plusieurs façons d’obtenir l’ID Store d’un produit dans le Store :

• Pour une application, vous pouvez obtenir l’ID Store dans la page Identité de l’application dans l’Espace partenaires.
• Pour une extension, vous pouvez obtenir l’ID Store dans sa page de vue d’ensemble dans l’Espace partenaires.
• Pour n’importe quel produit, vous pouvez également obtenir l’ID Store programmatiquement en utilisant la propriété StoreId de l’objet StoreProduct qui représente le produit.

Pour les produits avec des références SKU et des disponibilités, celles-ci ont également leurs propres ID Store avec différents formats.

Comment utiliser des ID produit pour les extensions dans votre code

Si vous souhaitez mettre une extension à la disposition de vos clients dans le contexte de votre application, vous devez entrer un ID produit unique pour votre extension lorsque vous créez votre soumission d’extension dans l’Espace partenaires. Vous pouvez utiliser cet ID produit pour faire référence à l’extension dans votre code, bien que les scénarios spécifiques dans lesquels vous pouvez utiliser l’ID produit dépendent de l’espace de noms que vous utilisez pour les achats in-app dans votre application.

Applications qui utilisent l’espace de noms Windows.Services.Store

Si votre application utilise l’espace de noms Windows.Services.Store, vous pouvez utiliser l’ID produit pour identifier facilement le StoreProduct qui représente votre extension ou le StoreLicense qui représente la licence de votre extension. L’ID produit est exposé par les propriétés StoreProduct.InAppOfferToken et StoreLicense.InAppOfferToken.

Applications qui utilisent l’espace de noms Windows.ApplicationModel.Store

Si votre application utilise l’espace de noms Windows.ApplicationModel.Store, vous devez utiliser l’ID produit que vous affectez à une extension dans l’Espace partenaires pour la plupart des opérations. Par exemple :

• Utilisez l’ID produit pour identifier le ProductListing qui représente votre extension ou le ProductLicense qui représente la licence de votre extension. L’ID produit est exposé par les propriétés ProductListing.ProductId et ProductLicense.ProductId.

• Spécifiez l’ID produit lorsque vous achetez votre extension pour l’utilisateur en utilisant la méthode RequestProductPurchaseAsync. Pour plus d’informations, voir Activer l’achat de produits dans l’application.

• Spécifiez l’ID produit lorsque vous signalez votre extension consommable comme étant consommée en utilisant la méthode ReportConsumableFulfillmentAsync. Pour plus d’informations, consultez Activer les achats de produits in-app consommables.

Rubriques connexes

• Obtenir les informations produit d’applications et d’extensions
• Obtenir les informations de licence d’applications et d’extensions
• Activer les achats in-app d’applications et d’extensions
• Activer les achats d’extensions consommables
• Activer les extensions par abonnement pour votre application
• Implémenter une version d’essai de votre application
• Codes d’erreur pour les opérations du Store
• Achats in-app et versions d’essai avec l’espace de noms Windows.ApplicationModel.Store