Activer les achats de produits consommables in-app

  • Article

Proposez des produits consommables dans l’application qui peuvent être achetés, utilisés et rachetés via la plateforme commerciale du Windows Store, afin d’offrir à vos clients une expérience d’achat à la fois solide et fiable au sein de l’application. Cette fonction est particulièrement utile pour différents aspects du jeu, comme les devises (or, pièces, etc.) susceptibles d’être achetées, puis utilisées pour acheter certaines améliorations.

Important

Cet article explique comment utiliser les membres de l’espace de noms Windows.ApplicationModel.Store pour activer les achats de produits consommables dans l’application. Cet espace de noms n’est plus mis à jour avec de nouvelles fonctionnalités et nous vous recommandons d’utiliser l’espace de noms Windows.Services.Store à la place. L’espace de noms Windows.Services.Store prend en charge les derniers types de modules complémentaires, tels que les modules complémentaires et les abonnements consommables gérés par le Store, et est conçu pour être compatible avec les futurs types de produits et fonctionnalités pris en charge par l’Espace partenaires et le Store. L’espace de noms Windows.Services.Store a été introduit dans Windows 10, version 1607, et il ne peut être utilisé que dans les projets qui ciblent Windows 10 Édition anniversaire (10.0 ; Build 14393) ou une version ultérieure dans Visual Studio. Pour plus d’informations sur l’activation des achats de produits consommables dans l’application à l’aide de l’espace de noms Windows.Services.Store , consultez cet article.

Prérequis

  • Cette rubrique porte sur les rapports relatifs aux achats et acquisitions de produits in-app consommables. Si vous ne connaissez pas les produits in-app, consultez Activer les achats de produits in-app pour en savoir plus sur les licences et obtenir la liste des produits in-app dans le Windows Store.
  • Lorsque vous codez et testez de nouveaux produits in-app pour la première fois, vous devez utiliser l’objet CurrentAppSimulator au lieu de l’objet CurrentApp. Cela vous permet de vérifier votre logique de licence à l’aide d’appels simulés au serveur de licences au lieu d’appels au serveur Windows Live. Pour ce faire, vous devez personnaliser le fichier nommé WindowsStoreProxy.xml dans %userprofile%\AppData\local\packages\<package name>\LocalState\Microsoft\Windows Store\ApiData. Le simulateur Microsoft Visual Studio crée ce fichier quand vous exécutez votre application pour la première fois. Vous pouvez également charger un fichier personnalisé au moment de l’exécution. Pour plus d’informations, consultez Utilisation du fichier WindowsStoreProxy.xml avec CurrentAppSimulator.
  • Cette rubrique fait également référence à des exemples de code fournis dans Exemple Windows Store. Cet exemple représente un excellent moyen d’obtenir une expérience pratique avec les différentes options de monétisation fournies pour les applications UWP.

Étape 1 : Établissement de la demande d’achat

La demande d’achat initiale est effectuée avec le paramètre RequestProductPurchaseAsync, comme tout autre achat effectué dans le Windows Store. En ce qui concerne les produits in-app, la différence réside dans le fait qu’après avoir effectué un achat, un client ne peut pas acheter le même produit tant que l’application n’a pas averti le Windows Store que l’achat précédent a été correctement effectué. Il revient à votre application d’acquérir les consommables achetés et d’avertir le Windows Store de l’opération.

L’exemple suivant représente une demande d’achat de produits consommables dans l’application. Vous noterez la présence de commentaires de code indiquant le moment où votre application doit effectuer l’acquisition locale du produit in-app consommable, selon deux scénarios différents : lorsque la demande aboutit ou lorsqu’elle échoue suite à un achat non finalisé du même produit.

PurchaseResults purchaseResults = await CurrentAppSimulator.RequestProductPurchaseAsync("product1");
switch (purchaseResults.Status)
{
    case ProductPurchaseStatus.Succeeded:
        product1TempTransactionId = purchaseResults.TransactionId;

        // Grant the user their purchase here, and then pass the product ID and transaction ID to
        // CurrentAppSimulator.ReportConsumableFulfillment to indicate local fulfillment to the
        // Windows Store.
        break;

    case ProductPurchaseStatus.NotFulfilled:
        product1TempTransactionId = purchaseResults.TransactionId;

        // First check for unfulfilled purchases and grant any unfulfilled purchases from an
        // earlier transaction. Once products are fulfilled pass the product ID and transaction ID
        // to CurrentAppSimulator.ReportConsumableFulfillment to indicate local fulfillment to the
        // Windows Store.
        break;
}

Étape 2 : Suivi de l’acquisition locale du consommable

Quand vous accordez à votre client un accès au produit in-app consommable, il est important de garder une trace du produit acquis (productId) et de chaque transaction associée à cette acquisition (transactionId).

Important

Votre application est responsable du signalement précis de l’exécution au Store. Cette étape est essentielle pour assurer une expérience d’achat fiable et juste à vos clients.

L’exemple suivant illustre l’utilisation des propriétés PurchaseResults de l’appel RequestProductPurchaseAsync à l’étape précédente, pour identifier le produit acheté à acquérir. Un tableau est utilisé pour stocker les informations du produit à un emplacement référençable ultérieurement et permettant de confirmer que l’acquisition locale a abouti.

private void GrantFeatureLocally(string productId, Guid transactionId)
{
    if (!grantedConsumableTransactionIds.ContainsKey(productId))
    {
        grantedConsumableTransactionIds.Add(productId, new List<Guid>());
    }
    grantedConsumableTransactionIds[productId].Add(transactionId);

    // Grant the user their content. You will likely increase some kind of gold/coins/some other asset count.
}

L’exemple qui suit montre comment utiliser le tableau de l’exemple précédent pour accéder à l’ID du produit et à l’ID de transaction, deux informations qui sont utilisées plus tard pour signaler la finalisation de l’opération au Windows Store.

Important

Quelle que soit la méthodologie utilisée par votre application pour suivre et confirmer l’exécution, votre application doit faire preuve de diligence raisonnable pour s’assurer que vos clients ne sont pas facturés pour les articles qu’ils n’ont pas reçus.

private Boolean IsLocallyFulfilled(string productId, Guid transactionId)
{
    return grantedConsumableTransactionIds.ContainsKey(productId) &&
        grantedConsumableTransactionIds[productId].Contains(transactionId);
}

Étape 3 : Signalement de l’acquisition de produits au Windows Store

Une fois l’acquisition locale effectuée, votre application doit passer un appel ReportConsumableFulfillmentAsync incluant l’élément productId et la transaction comprenant l’achat du produit.

Important

Si vous ne signalez pas au Store des produits consommables dans l’application, l’utilisateur ne pourra pas acheter à nouveau ce produit tant que l’exécution de l’achat précédent n’est pas signalée.

FulfillmentResult result = await CurrentAppSimulator.ReportConsumableFulfillmentAsync(
    "product2", product2TempTransactionId);

Étape 4 : Identification des achats non acquis

Votre application peut utiliser la méthode GetUnfulfilledConsumablesAsync pour rechercher les produits in-app consommables non acquis dans l’application et ce, à tout moment. Cette méthode doit être appelée régulièrement pour rechercher les consommables non acquis suite à des événements imprévus de l’application (interruption de la connectivité réseau, arrêt de l’application, etc.).

L’exemple suivant montre comment la méthode GetUnfulfilledConsumablesAsync permet d’énumérer les consommables non acquis et comment votre application peut parcourir cette liste pour effectuer l’acquisition locale.

private async void GetUnfulfilledConsumables()
{
    products = await CurrentApp.GetUnfulfilledConsumablesAsync();

    foreach (UnfulfilledConsumable product in products)
    {
        logMessage += "\nProduct Id: " + product.ProductId + " Transaction Id: " + product.TransactionId;
        // This is where you would pass the product ID and transaction ID to
        // currentAppSimulator.reportConsumableFulfillment to indicate local fulfillment to the Windows Store.
    }
}