Partager via

Activer les achats de composants additionnels consommables

  • Article

Cet article montre comment utiliser des méthodes de la classe StoreContext dans l’espace de noms Windows.Services.Store pour gérer l’exécution des modules complémentaires consommables par l’utilisateur dans vos applications UWP. Utilisez des modules complémentaires consommables pour les articles qui peuvent être achetés, utilisés et achetés à nouveau. Cela est particulièrement utile pour les choses telles que la devise en jeu (or, pièces, etc.) qui peuvent être achetées, puis utilisées pour acheter des power-ups spécifiques.

Remarque

L’espace de noms Windows.Services.Store a été introduit dans la version 1607 de Windows 10 et ne peut être utilisé que dans les projets ciblant 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 plutôt que Windows.Services.Store. Pour plus d’informations, consultez cet article.

Vue d’ensemble des modules complémentaires consommables

Les applications peuvent offrir deux types de modules complémentaires consommables qui diffèrent de la façon dont les traitements sont gérés :

  • Consommable géré par le développeur. Pour ce type de consommable, vous êtes responsable du suivi du solde des éléments de l’utilisateur que le module complémentaire représente et de signaler l’achat du module complémentaire tel qu’il est rempli au Store une fois que l’utilisateur a consommé tous les éléments. L’utilisateur ne peut pas racheter l’extension tant que votre application n’a pas signalé l’achat d’extension précédent comme consommé.

    Par exemple, si votre extension représente 100 pièces dans un jeu et que l’utilisateur consomme 10 pièces, votre application ou service doit gérer 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 l’extension comme étant consommée, puis l’utilisateur peut racheter l’extension de 100 pièces.

  • Consommable géré par le magasin. Pour ce type de consommable, le Windows Store effectue le suivi de l’équilibre des éléments de l’utilisateur que le module complémentaire représente. Lorsque l’utilisateur consomme des éléments, vous êtes responsable de la création de rapports sur ces éléments comme remplis dans le Windows Store, et le Store met à jour le solde de l’utilisateur. L’utilisateur peut acheter l’extension autant de fois qu’il le souhaite (il n’a pas besoin de consommer les articles d’abord). Votre application peut interroger le Windows Store pour le solde actuel de l’utilisateur à tout moment.

    Par exemple, si votre extension 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é consommées, et le Store met à jour le solde restant. Si l’utilisateur achète une nouvelle fois votre extension pour acquérir 100 autres pièces, il aura un total de 150 pièces.

    Remarque

    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 ce processus général :

  1. Permettre aux utilisateurs d’acheter le module complémentaire à partir de votre application.
  2. Lorsque l’utilisateur consomme le module complémentaire (par exemple, il dépense des pièces dans un jeu), signalez le module complémentaire tel qu’il est rempli.

À tout moment, vous pouvez également obtenir le solde restant pour un consommable géré par le Store.

Prérequis

Ces exemples présentent les conditions préalables suivantes :

  • Un projet Visual Studio pour une application de la Plateforme Windows universelle (UWP) qui cible Windows 10 édition anniversaire (10.0 Build 14393) ou une version ultérieure.
  • Vous avez créé une soumission d’application dans l’Espace partenaires et cette application est publiée dans le Store. Vous pouvez configurer de manière alternative l’application afin qu’elle ne soit pas détectable dans le Store pendant que vous la testez. Pour plus d’informations, consultez nos conseils de test.
  • Vous avez créé un module complémentaire consommable pour l’application dans l’Espace partenaires.

Le code de ces exemples suppose :

  • Le code s’exécute dans le contexte d’une page contenant un progressRing nommé workingProgressRing et un TextBlock nommé textBlock. Ces objets sont utilisés respectivement pour indiquer qu’une opération asynchrone se produit 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 Achats in-app et versions d’évaluation.

Pour obtenir un exemple complet d’application, consultez l’exemple Store.

Remarque

Si vous disposez d’une application de bureau qui utilise le Pont du bureau, vous devrez peut-être ajouter du code supplémentaire non affiché dans ces exemples pour configurer l’objet StoreContext. Pour plus d’informations, consultez Utilisation de la classe StoreContext dans une application bureautique qui utilise le Pont du bureau.

Signaler un module complémentaire consommable tel qu’il est rempli

Une fois que l’utilisateur a acheté le module complémentaire à partir de votre application et qu’il consomme votre module complémentaire, votre application doit signaler le module complémentaire comme rempli en appelant la méthode ReportConsumableFulfillmentAsync de la classe StoreContext . Vous devez transmettre les informations suivantes à cette méthode :

  • ID store du module complémentaire que vous souhaitez signaler comme rempli.
  • Unités du module complémentaire que vous souhaitez signaler comme rempli.
    • Pour un consommable géré par le développeur, spécifiez 1 pour le paramètre de quantité . Cela avertit le Store que le consommable a été rempli et que le client peut ensuite acheter à nouveau le consommable. L’utilisateur ne peut pas acheter à nouveau le consommable tant que votre application n’a pas informé le Store qu’elle a été remplie.
    • Pour un consommable géré par le Store, spécifiez le nombre réel d’unités consommées. Le Windows Store met à jour le solde restant pour le consommable.
  • ID de suivi de l’exécution. Il s’agit d’un GUID fourni par le développeur qui identifie la transaction spécifique à laquelle l’opération de traitement 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 rempli.

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 Store

Cet exemple montre comment utiliser la méthode GetConsumableBalanceRemainingAsync de la classe StoreContext pour obtenir le solde restant pour un module complémentaire consommable géré par Le 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;
    }
}