Abilitare i componenti aggiuntivi di sottoscrizione per la tua app

  • Articolo

L'app UWP (Universal Windows Platform) può offrire ai clienti acquisti in-app di componenti aggiuntivi di sottoscrizione. È possibile usare le sottoscrizioni per vendere prodotti digitali nell'app (ad esempio funzionalità dell'app o contenuti digitali) con periodi di fatturazione ricorrenti automatizzati.

Nota

Per abilitare l'acquisto di componenti aggiuntivi di sottoscrizione nell'app, il progetto deve essere destinato a Windows 10 Anniversary Edition (10.0; Build 14393) o versione successiva in Visual Studio (corrisponde a Windows 10, versione 1607) e deve usare le API nello spazio dei nomi Windows.Services.Store per implementare l'esperienza di acquisto in-app anziché lo spazio dei nomi Windows.ApplicationModel.Store. Per ulteriori informazioni sulle differenze tra questi spazi dei nomi, vedere Acquisti in-app e versioni di valutazione.

Caratteristiche essenziali delle funzionalità

I componenti aggiuntivi di sottoscrizione per le app UWP supportano le seguenti funzionalità:

  • È possibile scegliere tra periodi di sottoscrizione di 1 mese, 3 mesi, 6 mesi, 1 anno o 2 anni.
  • È possibile aggiungere periodi di valutazione gratuita di 1 settimana o 1 mese alla sottoscrizione.
  • Windows SDK fornisce le API che si usano nell'app per ottenere informazioni sui componenti aggiuntivi di sottoscrizione disponibili per l'app e abilitare l'acquisto di un componente aggiuntivo di sottoscrizione. Sono inoltre disponibili API REST che è possibile chiamare dai servizi per gestire le sottoscrizioni per un utente.
  • È possibile visualizzare report analitici che forniscono il numero di acquisizioni di sottoscrizioni, di sottoscrittori attivi e di sottoscrizioni annullate in un determinato periodo di tempo.
  • I clienti possono gestire la sottoscrizione nella pagina https://account.microsoft.com/services del loro account Microsoft. I clienti possono usare questa pagina per visualizzare tutte le sottoscrizioni che hanno acquisito, annullare una sottoscrizione e modificare la forma di pagamento associata alla sottoscrizione.

Passaggi per abilitare un componente aggiuntivo di sottoscrizione per l'app

Per abilitare l'acquisto di componenti aggiuntivi di sottoscrizione nell'app, seguire questa procedura.

  1. Creare un invio di un componente aggiuntivo per la sottoscrizione nel Centro per i partner e pubblicarlo. Quando si segue il processo di invio di un componente aggiuntivo, prestare particolare attenzione alle proprietà seguenti:

    • Tipo di prodotto: assicurarsi di selezionare Sottoscrizione.

    • Periodo di sottoscrizione: scegliere il periodo di fatturazione ricorrente per la sottoscrizione. Non è possibile modificare il periodo di sottoscrizione dopo aver pubblicato il componente aggiuntivo.

      Ogni componente aggiuntivo di sottoscrizione supporta un singolo periodo di sottoscrizione e un periodo di valutazione. È necessario creare un componente aggiuntivo di sottoscrizione diverso per ogni tipo di sottoscrizione che si desidera offrire nell'app. Ad esempio, se si desidera offrire una sottoscrizione mensile senza periodo di valutazione, una sottoscrizione mensile con un periodo di valutazione di un mese, una sottoscrizione annuale senza periodo di valutazione e una sottoscrizione annuale con un periodo di valutazione di un mese, è necessario creare quattro componenti aggiuntivi di sottoscrizione.

    • Periodo di valutazione: considerare se scegliere un periodo di valutazione di una settimana o un mese per la sottoscrizione per consentire agli utenti di provare il contenuto della sottoscrizione prima di acquistarlo. Non è possibile modificare o rimuovere il periodo di valutazione dopo aver pubblicato il componente aggiuntivo di sottoscrizione.

      Per acquisire una versione di valutazione gratuita della sottoscrizione, un utente deve acquistare la sottoscrizione tramite il processo di acquisto standard in-app che include una forma di pagamento valida. Durante il periodo di valutazione non vengono addebitati costi. Al termine del periodo di valutazione, la sottoscrizione viene automaticamente convertita nella sottoscrizione completa e sullo strumento di pagamento dell'utente verrà addebitato il primo periodo della sottoscrizione a pagamento. Se l'utente sceglie di annullare la sottoscrizione durante il periodo di valutazione, la sottoscrizione rimane attiva fino alla fine del periodo di valutazione. Alcuni periodi di valutazione non sono disponibili per tutti i periodi di sottoscrizione.

      Nota

      Ogni cliente può acquisire una versione di valutazione gratuita per un componente aggiuntivo di sottoscrizione una sola volta. Dopo che un cliente acquisisce una versione di valutazione gratuita per una sottoscrizione, lo Store impedisce allo stesso cliente di acquisire nuovamente la stessa sottoscrizione di valutazione gratuita.

    • Visibilità: se si crea un componente aggiuntivo di prova che si userà esclusivamente per testare l'esperienza di acquisto in-app per la sottoscrizione, si consiglia di selezionare una delle opzioni Nascosto nello Store. In caso contrario, è possibile selezionare l'opzione di visibilità migliore per lo scenario in questione.

    • Prezzi: scegliere il prezzo della sottoscrizione in questa sezione. Non è possibile aumentare il prezzo della sottoscrizione dopo aver pubblicato il componente aggiuntivo. Viceversa, è possibile ridurre il prezzo in un secondo momento.

      Importante

      Per impostazione predefinita, quando si crea un componente aggiuntivo, il prezzo viene inizialmente impostato su Gratuito. Poiché non è possibile aumentare il prezzo di un componente aggiuntivo di sottoscrizione dopo averne completato l'invio, assicurarsi di scegliere il prezzo della sottoscrizione qui.

  2. Nell'app usare le API nello spazio dei nomi Windows.Services.Store per determinare se l'utente corrente ha già acquisito il componente aggiuntivo di sottoscrizione e quindi offrirlo per la vendita all'utente come acquisto in-app. Per ulteriori dettagli, vedere gli esempi di codice in questo articolo.

  3. Testare l'implementazione dell'acquisto in-app della sottoscrizione nell'app. È necessario scaricare l'app una volta dallo Store perché il dispositivo di sviluppo usi la licenza per il test. Per ulteriori informazioni, vedere le linee guida per i test per gli acquisti in-app.

  4. Creare e pubblicare un invio di un'app che include il pacchetto dell'app aggiornato, con il codice testato. Per ulteriori informazioni, vedere Invii di app.

Esempi di codice

Gli esempi di codice in questa sezione illustrano come usare le API nello spazio dei nomi Windows.Services.Store per ottenere informazioni sui componenti aggiuntivi di sottoscrizione per l'app corrente e richiedere l'acquisto di un componente aggiuntivo di sottoscrizione per conto dell'utente corrente.

Questi esempi hanno i seguenti prerequisiti:

Il codice in questi esempi presuppone quanto segue:

  • Il file di codice include istruzioni using per gli spazi dei nomi Windows.Services.Store e System.Threading.Tasks.
  • 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.

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.

Acquistare un componente aggiuntivo di sottoscrizione

Questo esempio illustra come richiedere l'acquisto di un componente aggiuntivo di sottoscrizione noto per l'app per conto del cliente corrente. Questo esempio illustra anche come gestire il caso in cui la sottoscrizione ha un periodo di valutazione.

  1. Il codice determina innanzitutto se il cliente ha già una licenza attiva per la sottoscrizione. Se il cliente ha già una licenza attiva, il codice deve sbloccare le funzionalità della sottoscrizione in base alle esigenze (poiché si tratta di codice proprietario dell'app, questo viene identificato con un commento nell'esempio).
  2. Il codice ottiene quindi l'oggetto StoreProduct che rappresenta la sottoscrizione da acquistare per conto del cliente. Il codice presuppone che si conosca già l'ID dello Store del componente aggiuntivo di sottoscrizione che si desidera acquistare e che si abbia assegnato questo valore alla variabile subscriptionStoreId.
  3. Il codice determina quindi se è disponibile una versione di valutazione per la sottoscrizione. Facoltativamente, l'app può usare queste informazioni per mostrare al cliente i dettagli sulla versione di valutazione disponibile o sulla sottoscrizione completa.
  4. Infine, il codice chiama il metodo RequestPurchaseAsync per richiedere l'acquisto della sottoscrizione. Se è disponibile una versione di valutazione per la sottoscrizione, verrà offerta al cliente per l'acquisto. In caso contrario, verrà offerta al cliente la sottoscrizione completa.
private StoreContext context = null;
StoreProduct subscriptionStoreProduct;

// Assign this variable to the Store ID of your subscription add-on.
private string subscriptionStoreId = "";  

// This is the entry point method for the example.
public async Task SetupSubscriptionInfoAsync()
{
    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.
    }

    bool userOwnsSubscription = await CheckIfUserHasSubscriptionAsync();
    if (userOwnsSubscription)
    {
        // Unlock all the subscription add-on features here.
        return;
    }

    // Get the StoreProduct that represents the subscription add-on.
    subscriptionStoreProduct = await GetSubscriptionProductAsync();
    if (subscriptionStoreProduct == null)
    {
        return;
    }

    // Check if the first SKU is a trial and notify the customer that a trial is available.
    // If a trial is available, the Skus array will always have 2 purchasable SKUs and the
    // first one is the trial. Otherwise, this array will only have one SKU.
    StoreSku sku = subscriptionStoreProduct.Skus[0];
    if (sku.SubscriptionInfo.HasTrialPeriod)
    {
        // You can display the subscription trial info to the customer here. You can use 
        // sku.SubscriptionInfo.TrialPeriod and sku.SubscriptionInfo.TrialPeriodUnit 
        // to get the trial details.
    }
    else
    {
        // You can display the subscription purchase info to the customer here. You can use 
        // sku.SubscriptionInfo.BillingPeriod and sku.SubscriptionInfo.BillingPeriodUnit
        // to provide the renewal details.
    }

    // Prompt the customer to purchase the subscription.
    await PromptUserToPurchaseAsync();
}

private async Task<bool> CheckIfUserHasSubscriptionAsync()
{
    StoreAppLicense appLicense = await context.GetAppLicenseAsync();

    // Check if the customer has the rights to the subscription.
    foreach (var addOnLicense in appLicense.AddOnLicenses)
    {
        StoreLicense license = addOnLicense.Value;
        if (license.SkuStoreId.StartsWith(subscriptionStoreId))
        {
            if (license.IsActive)
            {
                // The expiration date is available in the license.ExpirationDate property.
                return true;
            }
        }
    }

    // The customer does not have a license to the subscription.
    return false;
}

private async Task<StoreProduct> GetSubscriptionProductAsync()
{
    // Load the sellable add-ons for this app and check if the trial is still 
    // available for this customer. If they previously acquired a trial they won't 
    // be able to get a trial again, and the StoreProduct.Skus property will 
    // only contain one SKU.
    StoreProductQueryResult result =
        await context.GetAssociatedStoreProductsAsync(new string[] { "Durable" });

    if (result.ExtendedError != null)
    {
        System.Diagnostics.Debug.WriteLine("Something went wrong while getting the add-ons. " +
            "ExtendedError:" + result.ExtendedError);
        return null;
    }

    // Look for the product that represents the subscription.
    foreach (var item in result.Products)
    {
        StoreProduct product = item.Value;
        if (product.StoreId == subscriptionStoreId)
        {
            return product;
        }
    }

    System.Diagnostics.Debug.WriteLine("The subscription was not found.");
    return null;
}

private async Task PromptUserToPurchaseAsync()
{
    // Request a purchase of the subscription product. If a trial is available it will be offered 
    // to the customer. Otherwise, the non-trial SKU will be offered.
    StorePurchaseResult result = await subscriptionStoreProduct.RequestPurchaseAsync();

    // 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 StorePurchaseStatus.Succeeded:
            // Show a UI to acknowledge that the customer has purchased your subscription 
            // and unlock the features of the subscription. 
            break;

        case StorePurchaseStatus.NotPurchased:
            System.Diagnostics.Debug.WriteLine("The purchase did not complete. " +
                "The customer may have cancelled the purchase. ExtendedError: " + extendedError);
            break;

        case StorePurchaseStatus.ServerError:
        case StorePurchaseStatus.NetworkError:
            System.Diagnostics.Debug.WriteLine("The purchase was unsuccessful due to a server or network error. " +
                "ExtendedError: " + extendedError);
            break;

        case StorePurchaseStatus.AlreadyPurchased:
            System.Diagnostics.Debug.WriteLine("The customer already owns this subscription." +
                    "ExtendedError: " + extendedError);
            break;
    }
}

Ottenere informazioni sui componenti aggiuntivi di sottoscrizione per l'app corrente

Questo esempio di codice illustra come ottenere informazioni per tutti i componenti aggiuntivi di sottoscrizione disponibili nell'app. Per ottenere queste informazioni, usare innanzitutto il metodo GetAssociatedStoreProductsAsync per ottenere la raccolta di oggetti StoreProduct che rappresentano ognuna dei componenti aggiuntivi disponibili per l'app. Ottenere quindi StoreSku per ogni prodotto e usare le proprietà IsSubscription e SubscriptionInfo per accedere alle informazioni sulla sottoscrizione.

private StoreContext context = null;

public async Task GetSubscriptionsInfo()
{
    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.
    }

    // Subscription add-ons are Durable products.
    string[] productKinds = { "Durable" };
    List<String> filterList = new List<string>(productKinds);

    StoreProductQueryResult queryResult =
        await context.GetAssociatedStoreProductsAsync(productKinds);

    if (queryResult.ExtendedError != null)
    {
        // The user may be offline or there might be some other server failure.
        System.Diagnostics.Debug.WriteLine($"ExtendedError: {queryResult.ExtendedError.Message}");
        return;
    }

    foreach (KeyValuePair<string, StoreProduct> item in queryResult.Products)
    {
        // Access the Store product info for the add-on.
        StoreProduct product = item.Value;

        // For each add-on, the subscription info is available in the SKU objects in the add-on. 
        foreach (StoreSku sku in product.Skus)
        {
            if (sku.IsSubscription)
            {
                // Use the sku.SubscriptionInfo property to get info about the subscription. 
                // For example, the following code gets the units and duration of the 
                // subscription billing period.
                StoreDurationUnit billingPeriodUnit = sku.SubscriptionInfo.BillingPeriodUnit;
                uint billingPeriod = sku.SubscriptionInfo.BillingPeriod;
            }
        }
    }
}

Gestire le sottoscrizioni dai servizi

Quando l'app aggiornata si trova nello Store e i clienti possono acquistare il componente aggiuntivo di sottoscrizione, possono presentarsi scenari in cui è necessario gestire la sottoscrizione per un cliente. Sono disponibili API REST che è possibile chiamare dai servizi per eseguire le attività di gestione delle sottoscrizioni seguenti:

Annullamenti

I clienti possono usare la pagina https://account.microsoft.com/services del loro account Microsoft per visualizzare tutte le sottoscrizioni che hanno acquisito, annullare una sottoscrizione e cambiare la forma di pagamento associata alla sottoscrizione. Quando un cliente annulla una sottoscrizione usando questa pagina, continua ad avere accesso alla sottoscrizione per la durata del periodo di fatturazione corrente. Non riceve un rimborso per una parte del periodo di fatturazione corrente. Al termine del periodo di fatturazione corrente, la sottoscrizione viene disattivata.

È anche possibile annullare una sottoscrizione per conto di un utente usando l'API REST per cambiare lo stato di fatturazione di una sottoscrizione per un determinato utente.

Rinnovi e periodi di tolleranza delle sottoscrizioni

In un dato momento durante ogni periodo di fatturazione, tenteremo di effettuare un addebito sulla carta di credito del cliente per il periodo di fatturazione successivo. Se l'addebito non riesce, la sottoscrizione del cliente entra nello stato di sollecito. Ciò significa che la sottoscrizione è ancora attiva per il resto del periodo di fatturazione corrente, ma che tenteremo periodicamente di effettuare addebiti sulla carta di credito per rinnovare automaticamente la sottoscrizione. Questo stato può durare per un massimo di due settimane, fino alla fine del periodo di fatturazione corrente e alla data di rinnovo per il periodo di fatturazione successivo.

Non sono disponibili periodi di tolleranza per la fatturazione della sottoscrizione. Se non è possibile effettuare l'addebito previsto sulla carta di credito del cliente entro la fine del periodo di fatturazione corrente, la sottoscrizione verrà annullata e il cliente non avrà più accesso alla sottoscrizione dopo il periodo di fatturazione corrente.

Scenari non supportati

Gli scenari seguenti non sono attualmente supportati per i componenti aggiuntivi di sottoscrizione.

  • La vendita di sottoscrizioni ai clienti direttamente tramite lo Store non è attualmente supportata. Le sottoscrizioni sono disponibili solo per gli acquisti in-app di prodotti digitali.
  • I clienti non possono cambiare i periodi di sottoscrizione usando la pagina https://account.microsoft.com/services del loro account Microsoft. Per passare a un periodo di sottoscrizione diverso, i clienti devono annullare la sottoscrizione corrente e acquistare una sottoscrizione con un periodo di sottoscrizione diverso dall'app.
  • Il cambio di livello non è attualmente supportato per i componenti aggiuntivi di sottoscrizione (ad esempio, il passaggio di un cliente da una sottoscrizione di base a una sottoscrizione premium con più funzionalità).
  • Saldi e codici promozionali non sono attualmente supportati per i componenti aggiuntivi di sottoscrizione.
  • Il rinnovo delle sottoscrizioni esistenti dopo l'impostazione della visibilità del componente aggiuntivo di sottoscrizione su Interrompi acquisizione. Per ulteriori dettagli, vedere Impostare il prezzo e la disponibilità del componente aggiuntivo.