Condividi tramite

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 dei componenti aggiuntivi di consumo nelle app UWP. Usare i componenti aggiuntivi di consumo per gli articoli che possono essere acquistati, usati e acquistati di nuovo. Questo è particolarmente utile per cose come la valuta di gioco (oro, monete, eccetera) che può essere acquistata e poi utilizzata per acquistare specifici power-up.

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 una release successiva in Visual Studio. Se l'app è destinata a una versione precedente di Windows 10, devi usare lo spazio dei nomi Windows.ApplicationModel.Store anziché lo spazio dei nomi Windows.Services.Store. Per altre informazioni, vedere 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 gestiti gli adempimenti:

  • Consumo gestito dallo sviluppatore. Per questo tipo di componente di consumo, si è responsabili di 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 utilizzato tutti gli articoli. L'utente non può acquistare di nuovo il componente aggiuntivo finché l'app non ha segnalato l'acquisto del componente aggiuntivo precedente come evaso.

    Ad esempio, se il componente aggiuntivo rappresenta 100 monete in un gioco e l'utente utilizza 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 e quindi l'utente può acquistare nuovamente il componente aggiuntivo di 100 monete.

  • di consumo gestito dallo Store. Per questo tipo di consumabile, lo Store tiene traccia del saldo degli oggetti dell'utente che l'add-on rappresenta. Quando l'utente utilizza qualsiasi elemento, l'utente è responsabile della segnalazione di tali elementi come evasi allo Store e lo Store aggiorna il saldo dell'utente. L'utente può acquistare il componente aggiuntivo tutte le volte desiderato (non è necessario utilizzare prima gli elementi). L'app può eseguire una query nello Store per 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 utilizza 50 monete, l'app segnala allo Store che sono state soddisfatte 50 unità del componente aggiuntivo e lo Store aggiorna il saldo rimanente. Se l'utente riacquista quindi il componente aggiuntivo per acquisire 100 monete, ora avranno 150 monete totali.

    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 dalla tua app.
  2. Quando l'utente utilizza il componente aggiuntivo (ad esempio, spende monete in un gioco), segnala il componente aggiuntivo come evaso.

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

Prerequisiti

Questi esempi presentano i prerequisiti seguenti:

  • Un progetto di Visual Studio per un'app UWP (Universal Windows Platform) che punta a Windows 10 Anniversary Edition (10.0; Build 14393) o una versione successiva.
  • Hai creato un invio di app nel Centro per i partner e questa app viene pubblicata nello Store. Facoltativamente, puoi configurare l'app in modo che non sia individuabile nello Store durante il test. Per altre informazioni, vedere le linee guida per i test .
  • Hai creato un componente aggiuntivo consumabile per l'app nel Centro per i partner.

Il codice in questi esempi presuppone:

  • Il codice viene eseguito nel contesto di un Page di contenente un ProgressRing denominato workingProgressRing e un 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 include un usando'istruzione per lo spazio dei nomi Windows.Services.Store.
  • L'app è un'app a utente singolo che viene eseguita solo nel contesto dell'utente che ha avviato l'app. Per ulteriori informazioni, vedere acquisti in-app e prove.

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

Nota

Se si dispone di un'applicazione desktop che usa Desktop Bridge, potrebbe essere necessario aggiungere codice aggiuntivo non illustrato in questi esempi per configurare l'oggetto StoreContext. Per altre 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 dalla tua app e lo ha consumato, la tua 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 da segnalare come completato.
  • Le unità del componente aggiuntivo che desideri segnalare come soddisfatte.
    • Per una risorsa consumabile gestita dallo sviluppatore, specificare 1 per il parametro quantità . In questo modo lo Store segnala che il componente di consumo è stato soddisfatto e il cliente può quindi acquistare di nuovo il componente di consumo. L'utente non può acquistare di nuovo il consumabile finché l'app non ha notificato allo Store che l'acquisto è stato completato.
    • Per un componente di consumo gestito dallo Store, specificare il numero effettivo di unità utilizzate. Lo Store aggiornerà il saldo rimanente per il componente di consumo.
  • ID di tracciamento per l'adempimento. Si tratta di un GUID fornito dal sviluppatore che identifica la transazione specifica con cui l'operazione di evasione è associata per scopi di tracciamento. Per ulteriori informazioni, vedere le osservazioni in ReportConsumableFulfillmentAsync.

In questo esempio viene illustrato come segnalare un consumabile 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 di consumo gestito dallo Store

In questo esempio viene illustrato 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;
    }
}