Activer les achats de modules complémentaires consommables

  • Article

Cet article explique comment utiliser les méthodes de la classe StoreContext dans l’espace de noms Windows.Services.Store pour gérer l’exécution par l’utilisateur des modules complémentaires consommables dans vos applications UWP. Utilisez les modules complémentaires consommables pour les éléments qu’il est possible d’acheter, d’utiliser et d’acheter à nouveau. 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.

Notes

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. Si votre application cible une version antérieure de Windows 10, vous devez utiliser l’espace de noms Windows.ApplicationModel.Store à la place de l’espace de noms Windows.Services.Store. Pour plus d’informations, consultez cet article.

Présentation des modules complémentaires consommables

Les applications peuvent proposer deux types de modules complémentaires consommables qui diffèrent dans la façon dont les exécutions sont gérées :

  • Consommable géré par les développeurs. Pour ce type de consommable, vous devez gérer le solde d’éléments de l’utilisateur, qui représente le module complémentaire, et signaler l’achat du module complémentaire comme épuisé dans le Windows Store une fois que l’utilisateur a consommé tous les éléments. L’utilisateur ne peut pas acheter à nouveau le module complémentaire, tant que votre application n’a pas signalé le module complémentaire précédent comme épuisé.

    Par exemple, si votre module complémentaire représente 100 pièces dans un jeu et que l’utilisateur en consomme 10, votre application ou votre service doit maintenir le nouveau solde restant de 90 pièces pour l’utilisateur. Une fois que l’utilisateur a consommé les 100 pièces, votre application doit signaler le module complémentaire comme épuisé. Ensuite, l’utilisateur peut racheter le module complémentaire de 100 pièces.

  • Consommable géré par le magasin. Pour ce type de consommable, le Windows Store gère le solde d’éléments de l’utilisateur, que le module complémentaire représente. Lorsque l’utilisateur utilise des éléments, vous devez les déclarer comme consommés dans le Store qui met à jour le solde de l’utilisateur. L’utilisateur peut acheter le module complémentaire autant de fois qu’il le souhaite (il n’a pas besoin de consommer les éléments en premier). Votre application peut interroger le Store pour obtenir le solde actuel de l’utilisateur à tout moment.

    Par exemple, si votre module complémentaire représente une quantité initiale de 100 pièces dans un jeu et que l’utilisateur consomme 50 pièces, votre application signale au Store que 50 unités de l’extension ont été remplies et que le Store met à jour le solde restant. Si l’utilisateur rachète ensuite votre module complémentaire pour acquérir 100 pièces supplémentaires, il aura maintenant un total de 150 pièces.

    Notes

    Les consommables gérés par le magasin ont été introduits dans Windows 10 version 1607.

Pour offrir un module complémentaire consommable à un utilisateur, suivez cette procédure générale :

  1. Autorisez les utilisateurs à acheter le module complémentaire à partir de votre application.
  2. Lorsque l’utilisateur consomme le module complémentaire (par exemple, en dépensant des pièces dans un jeu), signalez le module comme consommé.

À tout moment, vous pouvez également consulter le solde restant d’un consommable géré par le Windows Store.

Prérequis

Les conditions préalables de ces exemples sont les suivantes :

Le code de ces exemples respecte les présupposés suivants :

  • Le code s’exécute dans le contexte d’une Page qui contient un ProgressRing nommé workingProgressRing et un TextBlock nommé textBlock. Ces objets sont utilisés pour respectivement indiquer qu’une opération asynchrone est en cours et afficher les messages de sortie.
  • Le fichier de code contient une instruction using pour l’espace de noms Windows.Services.Store.
  • Cette application mono-utilisateur ne s’exécute que dans le contexte de l’utilisateur qui l’a lancée. Pour plus d’informations, consultez Versions d’évaluation et achats in-app.

Pour obtenir un exemple d’application complète, consultez Exemple Windows Store.

Notes

Si vous disposez d’une application de bureau qui utilise le Pont du bureau, vous devrez peut-être ajouter du code supplémentaire qui n’apparaît pas dans ces exemples pour configurer l’objet StoreContext. Pour plus d’informations, voir Utilisation de la classe StoreContext dans une application de bureau qui utilise Desktop Bridge.

Signaler un composant additionnel consommable comme épuisé

Lorsque l’utilisateur achète le module complémentaire à votre application et qu’il le consomme, votre application doit le signaler comme épuisé en appelant la méthode ReportConsumableFulfillmentAsync de la classe StoreContext. Vous devez transmettre les informations suivantes à cette méthode :

  • L’ID Windows Store du module complémentaire que vous souhaitez signaler comme consommé.
  • Les unités du module complémentaire que vous souhaitez signaler comme épuisées.
    • Pour un consommable géré par le développeur, attribuez la valeur 1 au paramètre de quantité. Ceci signale au Windows Store que le consommable est épuisé et que le client peut l’acheter à nouveau. L’utilisateur ne peut pas acheter le consommable à nouveau tant que votre application n’a pas notifié au Windows Store qu’il a été épuisé.
    • Pour un consommable géré par le Windows Store, indiquez le nombre réel d’unités consommées. Le Windows Store met à jour le solde restant du consommable.
  • L’ID de suivi de l’acquisition. Il s’agit d’un GUID fourni par le développeur, qui identifie la transaction spécifique à laquelle l’opération d’acquisition est associée, à des fins de suivi. Pour plus d’informations, consultez les remarques dans ReportConsumableFulfillmentAsync.

Cet exemple montre comment signaler un consommable géré par le Windows Store comme épuisé.

private StoreContext context = null;

public async void ConsumeAddOn(string addOnStoreId)
{
    if (context == null)
    {
        context = StoreContext.GetDefault();
        // If your app is a desktop app that uses the Desktop Bridge, you
        // may need additional code to configure the StoreContext object.
        // For more info, see https://aka.ms/storecontext-for-desktop.
    }

    // This is an example for a Store-managed consumable, where you specify the actual number
    // of units that you want to report as consumed so the Store can update the remaining
    // balance. For a developer-managed consumable where you maintain the balance, specify 1
    // to just report the add-on as fulfilled to the Store.
    uint quantity = 10;
    Guid trackingId = Guid.NewGuid();

    workingProgressRing.IsActive = true;
    StoreConsumableResult result = await context.ReportConsumableFulfillmentAsync(
        addOnStoreId, quantity, trackingId);
    workingProgressRing.IsActive = false;

    // Capture the error message for the operation, if any.
    string extendedError = string.Empty;
    if (result.ExtendedError != null)
    {
        extendedError = result.ExtendedError.Message;
    }

    switch (result.Status)
    {
        case StoreConsumableStatus.Succeeded:
            textBlock.Text = "The fulfillment was successful. " + 
                $"Remaining balance: {result.BalanceRemaining}";
            break;

        case StoreConsumableStatus.InsufficentQuantity:
            textBlock.Text = "The fulfillment was unsuccessful because the remaining " +
                $"balance is insufficient. Remaining balance: {result.BalanceRemaining}";
            break;

        case StoreConsumableStatus.NetworkError:
            textBlock.Text = "The fulfillment was unsuccessful due to a network error. " +
                "ExtendedError: " + extendedError;
            break;

        case StoreConsumableStatus.ServerError:
            textBlock.Text = "The fulfillment was unsuccessful due to a server error. " +
                "ExtendedError: " + extendedError;
            break;

        default:
            textBlock.Text = "The fulfillment was unsuccessful due to an unknown error. " +
                "ExtendedError: " + extendedError;
            break;
    }
}

Obtenir le solde restant d’un consommable géré par le Windows Store

Cet exemple montre comment utiliser la méthode GetConsumableBalanceRemainingAsync de la classe StoreContext pour obtenir le solde restant d’un consommable géré par le Windows Store.

private StoreContext context = null;

public async void GetRemainingBalance(string addOnStoreId)
{
    if (context == null)
    {
        context = StoreContext.GetDefault();
        // If your app is a desktop app that uses the Desktop Bridge, you
        // may need additional code to configure the StoreContext object.
        // For more info, see https://aka.ms/storecontext-for-desktop.
    }

    workingProgressRing.IsActive = true;
    StoreConsumableResult result = await context.GetConsumableBalanceRemainingAsync(addOnStoreId);
    workingProgressRing.IsActive = false;

    // Capture the error message for the operation, if any.
    string extendedError = string.Empty;
    if (result.ExtendedError != null)
    {
        extendedError = result.ExtendedError.Message;
    }

    switch (result.Status)
    {
        case StoreConsumableStatus.Succeeded:
            textBlock.Text = "Remaining balance: " + result.BalanceRemaining;
            break;

        case StoreConsumableStatus.NetworkError:
            textBlock.Text = "Could not retrieve balance due to a network error. " +
                "ExtendedError: " + extendedError;
            break;

        case StoreConsumableStatus.ServerError:
            textBlock.Text = "Could not retrieve balance due to a server error. " +
                "ExtendedError: " + extendedError;
            break;

        default:
            textBlock.Text = "Could not retrieve balance due to an unknown error. " +
                "ExtendedError: " + extendedError;
            break;
    }
}