Abilitare gli acquisti di componenti aggiuntivi di consumo

  • Articolo

Questo articolo illustra come usare i metodi della classe StoreContext nello spazio dei nomi Windows.Services.Store per gestire l'evasione da parte dell'utente dei componenti aggiuntivi di consumo nelle app UWP. Usare i componenti aggiuntivi di consumo per elementi che possono essere acquistati, usati e acquistati di nuovo. Questo è particolarmente utile per elementi quali il denaro usato nel gioco (oro, monete e così via) che possono essere acquistati e poi usati per acquistare potenziamenti specifici.

Nota

Lo spazio dei nomi Windows.Services.Store è stato introdotto in Windows 10, versione 1607, e può essere usato solo nei progetti destinati a Windows 10 Anniversary Edition (10.0; Build 14393) o versione successiva in Visual Studio. Se l'app è destinata a una versione precedente di Windows 10, è necessario usare lo spazio dei nomi Windows.ApplicationModel.Store anziché Windows.Services.Store. Per altre informazioni, vedi questo articolo.

Panoramica dei componenti aggiuntivi di consumo

Le app possono offrire due tipi di componenti aggiuntivi di consumo che differiscono nel modo in cui vengono gestite le evasioni:

  • Di consumo gestito dallo sviluppatore. Per questo tipo di componente di consumo, occorre tenere traccia del saldo dell'utente degli elementi rappresentati dal componente aggiuntivo e di segnalare l'acquisto del componente aggiuntivo come evaso allo Store dopo che l'utente ha consumato tutti gli articoli. L'utente non può acquistare di nuovo il componente aggiuntivo finché l'app non segna l'acquisto del componente aggiuntivo precedente come evaso.

    Ad esempio, se il componente aggiuntivo rappresenta 100 monete in un gioco e l'utente consuma 10 monete, l'app o il servizio deve mantenere il nuovo saldo rimanente di 90 monete per l'utente. Dopo che l'utente ha consumato tutte le 100 monete, l'app deve segnalare il componente aggiuntivo come evaso, quindi l'utente può acquistare nuovamente il componente aggiuntivo di 100 monete.

  • Di consumo gestito dallo Store. Per questo tipo di componente di consumo, lo Store tiene traccia del saldo degli elementi dell'utente rappresentato dal componente aggiuntivo. Quando l'utente utilizza qualsiasi elemento, occorre segnalare tali elementi come evasi allo Store affinché lo Store aggiorni il saldo dell'utente. L'utente può acquistare il componente aggiuntivo tutte le volte che desidera (non è necessario che consumi prima gli elementi). L'app può eseguire una query nello Store per conoscere il saldo corrente dell'utente in qualsiasi momento.

    Ad esempio, se il componente aggiuntivo rappresenta una quantità iniziale di 100 monete in un gioco e l'utente consuma 50 monete, l'app segnala allo Store che sono state evase 50 unità del componente aggiuntivo e lo Store aggiorna il saldo rimanente. Se successivamente l'utente acquista di nuovo il componente aggiuntivo per acquisire altre 100 monete, raggiungerà un saldo totale di 150 monete.

    Nota

    I componenti di consumo gestiti dallo Store sono stati introdotti in Windows 10, versione 1607.

Per offrire un componente aggiuntivo di consumo a un utente, seguire questa procedura generale:

  1. Consentire agli utenti di acquistare il componente aggiuntivo dall'app.
  2. Quando l'utente consuma il componente aggiuntivo (ad esempio, spende monete in un gioco), segnalare il componente aggiuntivo come evaso.

In qualsiasi momento è possibile ottenere il saldo rimanente per un componente aggiuntivo di consumo gestito dallo Store.

Prerequisiti

Questi esempi hanno i seguenti prerequisiti:

  • Un progetto Visual Studio per un'app UWP (Universal Windows Platform) destinata a Windows 10 Anniversary Edition (10.0; Build 14393) o versione successiva.
  • Aver creato un invio dell'app nel Centro per i partner e pubblicato l'app nello Store. Facoltativamente, è possibile configurare l'app in modo che non sia rilevabile nello Store durante il test. Per ulteriori informazioni, vedere le linee guida per i test.
  • Aver creato un componente aggiuntivo di consumo per l'app nel Centro per i partner.

Il codice in questi esempi presuppone quanto segue:

  • Il codice è eseguito nel contesto di un oggetto Page che contiene un oggetto ProgressRing denominato workingProgressRing e un oggetto TextBlock denominato textBlock. Questi oggetti vengono usati per indicare che si sta verificando un'operazione asincrona e per visualizzare rispettivamente i messaggi di output.
  • Il file di codice contiene un'istruzione using per lo spazio dei nomi Windows.Services.Store.
  • L'app è un'app per un singolo utente che viene eseguita solo nel contesto dell'utente che ha avviato l'app. Per ulteriori informazioni, vedere Acquisti in-app e versioni di valutazione.

Per un'applicazione di esempio completa, vedere l'esempio di Store.

Nota

Se si ha un'applicazione desktop che usa Desktop Bridge, può essere necessario aggiungere ulteriore codice non illustrato in questi esempi per configurare l'oggetto StoreContext. Per ulteriori informazioni, vedere Uso della classe StoreContext in un'applicazione desktop che usa Desktop Bridge.

Segnalare un componente aggiuntivo di consumo come evaso

Dopo che l'utente acquista il componente aggiuntivo dall'app e lo consuma, l'app deve segnalare il componente aggiuntivo come evaso chiamando il metodo ReportConsumableFulfillmentAsync della classe StoreContext. È necessario passare le informazioni seguenti a questo metodo:

  • L'ID dello Store del componente aggiuntivo che si desidera segnalare come evaso.
  • Le unità del componente aggiuntivo che si desidera segnalare come evase.
    • Per un componente aggiuntivo di consumo gestito dallo sviluppatore, specificare 1 per il parametro quantity. In questo modo lo Store segnala che il componente di consumo è stato evaso e il cliente può quindi acquistarlo di nuovo. L'utente non può acquistare di nuovo il componente di consumo finché l'app non ha comunicato allo Store che è stato evaso.
    • Per un componente di consumo gestito dallo Store, specificare il numero effettivo di unità consumate. Lo Store aggiornerà il saldo rimanente per il componente di consumo.
  • ID di traccia per l'evasione. Questo è un GUID fornito dallo sviluppatore che identifica la transazione specifica a cui è associata l'operazione di evasione a scopo di traccia. Per ulteriori informazioni, vedere le note in ReportConsumableFulfillmentAsync.

Questo esempio illustra come segnalare un componente aggiuntivo di consumo gestito dallo Store come evaso.

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;
    }
}

Ottenere il saldo rimanente per un componente aggiuntivo di consumo gestito dallo Store

Questo esempio illustra come usare il metodo GetConsumableBalanceRemainingAsync della classe StoreContext per ottenere il saldo rimanente per un componente aggiuntivo di consumo gestito dallo 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;
    }
}