Acquisti in-app e versioni di valutazione

Acquisti in-app e versioni di valutazione mediante lo spazio dei nomi Windows.Services.Store

Questa sezione offre una panoramica delle attività e dei concetti importanti per lo spazio dei nomi Windows.Services.Store. Questo spazio dei nomi è disponibile solo per le app destinate a Windows 10 Anniversary Edition (10.0; Build 14393) o versione successiva in Visual Studio (corrispondente a Windows 10, versione 1607). Consigliamo che le app usino lo spazio dei nomi Windows.Services.Store anziché lo spazio dei nomi Windows.ApplicationModel.Store, se possibile. Per informazioni sullo spazio dei nomi Windows.ApplicationModel.Store, vedere questo articolo.

In questa sezione

• Video
• Introduzione alla classe StoreContext
• Implementare gli acquisti in-app
• Implementare la funzionalità di valutazione
• Testare l'implementazione dell'acquisto in-app o della versione di valutazione
• Ricevute per gli acquisti in-app
• Uso della classe StoreContext con Desktop Bridge
• Prodotti, SKU e disponibilità
• ID dello Store

Introduzione alla classe StoreContext

Il punto di ingresso principale dello spazio dei nomi Windows.Services.Store è la classe StoreContext. Questa classe fornisce metodi che è possibile usare per ottenere informazioni per l'app corrente e i relativi componenti aggiuntivi disponibili, ottenere informazioni sulla licenza per l'app corrente o i relativi componenti aggiuntivi, acquistare un'app o un componente aggiuntivo per l'utente corrente ed eseguire altre attività. Per ottenere un oggetto StoreContext, eseguire una delle operazioni seguenti:

• In un'app a utente singolo (ossia un'app che viene eseguita solo nel contesto dell'utente che l'ha avviata), usare il metodo statico GetDefault per ottenere un oggetto StoreContext che è possibile usare per accedere ai dati di Microsoft Store per l'utente. La maggior parte delle app UWP (Universal Windows Platform) sono app a utente singolo.

  Windows.Services.Store.StoreContext context = StoreContext.GetDefault();
  

• In un'app multiutente usare il metodo statico GetForUser per ottenere un oggetto StoreContext che è possibile usare per accedere ai dati di Microsoft Store per un utente specifico che ha eseguito l'accesso con i proprio account Microsoft durante l'uso dell'app. L'esempio seguente ottiene un oggetto StoreContext per il primo utente disponibile.

  var users = await Windows.System.User.FindAllAsync();
  Windows.Services.Store.StoreContext context = StoreContext.GetForUser(users[0]);
  

Dopo aver creato un oggetto StoreContext, è possibile iniziare a chiamare metodi per questo oggetto per ottenere informazioni sul prodotto dello Store per l'app corrente e i relativi componenti aggiuntivi, recuperare informazioni sulla licenza per l'app corrente e i relativi componenti aggiuntivi, acquistare un'app o un componente aggiuntivo per l'utente corrente ed eseguire altre attività. Per ulteriori informazioni sulle attività comuni che è possibile eseguire mediante questo oggetto, vedere gli articoli seguenti:

• Ottenere info sul prodotto per le app e i componenti aggiuntivi
• Ottenere info sulla licenza per le app e i componenti aggiuntivi
• Abilitare gli acquisti in-app di app e componenti aggiuntivi
• Abilitare gli acquisti di componenti aggiuntivi di consumo
• Abilitare i componenti aggiuntivi di sottoscrizione per la tua app
• Implementare una versione di prova dell'app

Per un'app di esempio che illustra come usare StoreContext e altri tipi nello spazio dei nomi Windows.Services.Store, vedere l'Esempio di Store.

Implementare gli acquisti in-app

Per offrire un acquisto in-app ai clienti nell'app usando lo spazio dei nomi Windows.Services.Store:

1. Se l'app offre componenti aggiuntivi che i clienti possono acquistare, creare invii di componenti aggiuntivi per l'app nel Centro per i partner.

2. Scrivere il codice nell'app per recuperare le informazioni sui prodotto per l'app o un componente aggiuntivo offerto dall'app, quindi determinare se la licenza è attiva (ossia, se l'utente dispone di una licenza per l'uso dell'app o del componente aggiuntivo). Se la licenza non è attiva, visualizzare un elemento dell'interfaccia utente che offra l'app o il componente aggiuntivo per la vendita all'utente come acquisto in-app.

3. Se l'utente sceglie di acquistare l'app o il componente aggiuntivo, usare il metodo appropriato per l'acquisto del prodotto:

   • Se l'utente acquista l'app o un componente aggiuntivo durevole, seguire le istruzioni in Abilitare gli acquisti in-app di app e componenti aggiuntivi.
   • Se l'utente acquista un componente aggiuntivo di consumo, seguire le istruzioni in Abilitare gli acquisti di componenti aggiuntivi di consumo.
   • Se l'utente acquista un componente aggiuntivo di sottoscrizione, seguire le istruzioni in Abilitare i componenti aggiuntivi di sottoscrizione per l'app.

4. Testare l'implementazione seguendo le linee guida per i test in questo articolo.

Implementare la funzionalità di valutazione

Per escludere o limitare le funzionalità in una versione di valutazione dell'app usando lo spazio dei nomi Windows.Services.Store :

1. Configurare l'app come versione di valutazione gratuita nel Centro per i partner.

2. Scrivere il codice nell'app per recuperare le informazioni sul prodotto per l'app o un componente aggiuntivo offerto dall'app, quindi determinare se la licenza associata all'app è una licenza di valutazione.

3. Escludere o limitare determinate funzionalità nell'app se si tratta di una versione di valutazione e quindi abilitare le funzionalità quando l'utente acquista una licenza completa. Per ulteriori informazioni e un esempio di codice, vedere Implementare una versione di valutazione dell'app.

4. Testare l'implementazione seguendo le linee guida per i test in questo articolo.

Testare l'implementazione dell'acquisto in-app o della versione di valutazione

Se l'app usa API nello spazio dei nomi Windows.Services.Store per implementare gli acquisti in-app o la funzionalità di valutazione, è necessario pubblicare l'app nello Store e scaricarla nel dispositivo di sviluppo per usarne la licenza per il test. Seguire questo processo per testare il codice:

1. Se la tua app non è ancora pubblicata e disponibile nello Store, assicurarsi che soddisfi i requisiti minimi del Kit di certificazione app Windows, inviare l'app nel Centro per i partner e assicurarsi che superi il processo di certificazione. È possibile configurare l'app in modo che non sia individuabile nello Store durante il test. Prendere nota della configurazione corretta dei pacchetti in anteprima. I pacchetti in anteprima non configurati correttamente potrebbero non essere scaricabili.

2. Quindi, assicurarsi di aver completato quanto segue:

   • Scrivere il codice nell'app che usa la classe StoreContext e altri tipi correlati nello spazio dei nomi Windows.Services.Store per implementare gli acquisti in-app o la funzionalità di valutazione.
   • Se l'app offre un componente aggiuntivo che i clienti possono acquistare, creare un invio del componente aggiuntivo per l'app nel Centro per i partner.
   • Per escludere o limitare alcune funzionalità in una versione di valutazione dell'app, configurare l'app come versione di valutazione gratuita nel Centro per i partner.

3. Con il progetto aperto in Visual Studio, fare clic sul menu Progetto, scegliere Store, quindi fare clic su Associa app allo Store. Completare le istruzioni della procedura guidata per associare il progetto dell'app all'app nel proprio account del Centro per i partner che si desidera usare per i test.

   Nota

   Se non si associa il progetto all'app nello Store, i metodi StoreContext impostano la proprietà ExtendedError dei loro valori restituiti sul valore di codice di errore 0x803F6107. Questo valore indica che lo Store non conosce l'app.

4. Se non lo si è ancora fatto, installare l'app dallo Store specificata nel passaggio precedente, eseguire l'app una volta e quindi chiuderla. Ciò assicura che venga installata una licenza valida per l'app nel dispositivo di sviluppo.

5. In Visual Studio avviare l'esecuzione o il debug del progetto. Il codice deve recuperare i dati dell'app e del componente aggiuntivo dall'app dello Store associata al progetto locale. Se viene richiesto di reinstallare l'app, seguire le istruzioni ed eseguire il progetto o sottoporlo a debug.

   Nota

   Dopo aver completato questi passaggi, è possibile continuare ad aggiornare il codice dell'app e quindi eseguire il debug del progetto aggiornato nel computer di sviluppo senza inviare nuovi pacchetti dell'app allo Store. È sufficiente scaricare una volta nel computer di sviluppo la versione dell'app presente nello Store per ottenere la licenza locale che verrà usata per i test. È solo necessario inviare i nuovi pacchetti dell'app allo Store dopo aver completato i test per rendere disponibili ai clienti gli acquisti in-app o le funzionalità di valutazione.

Se l'app usa lo spazio dei nomi Windows.ApplicationModel.Store, è possibile usare la classe CurrentAppSimulator nell'app per simulare le informazioni sulla licenza durante i test prima di inviare l'app allo Store. Per ulteriori informazioni, vedere Introduzione alle classi CurrentApp e CurrentAppSimulator.

Ricevute per gli acquisti in-app

Lo spazio dei nomi Windows.Services.Store non fornisce un'API che è possibile usare per ottenere una ricevuta della transazione per gli acquisti effettuati nel codice dell'app. L'esperienza di utilizzo è diversa rispetto alle app che usano lo spazio dei nomi Windows.ApplicationModel.Store, i quali possono usare un'API lato client per recuperare una ricevuta di transazione.

Se si implementano acquisti in-app mediante lo spazio dei nomi Windows.Services.Store e si desidera verificare se un determinato cliente ha acquistato un'app o un componente aggiuntivo, è possibile usare il metodo di query per i prodotti nell'API rest di riscossione di Microsoft Store. I dati restituiti per questo metodo confermano se il cliente specificato ha diritto a un determinato prodotto e fornisce i dati per la transazione con cui l'utente ha acquisito il prodotto. L'API di riscossione di Microsoft Store usa l'autenticazione Azure AD per recuperare queste informazioni.

Uso della classe StoreContext con Desktop Bridge

Le applicazioni desktop che usano Desktop Bridge possono usare la classe StoreContext per implementare acquisti in-app e versioni di valutazione. Tuttavia, se si ha un'applicazione desktop Win32 o un'applicazione desktop che presenta un handle di finestra (HWND) associato al framework di rendering (ad esempio un'applicazione WPF o Windows App SDK), tale applicazione deve configurare l'oggetto StoreContext per specificare quale finestra dell'applicazione è la finestra del proprietaria per le finestre di dialogo modali visualizzate dall'oggetto.

Molti membri StoreContext (e membri di altri tipi correlati a cui si accede tramite l'oggetto StoreContext) mostrano all'utente una finestra di dialogo per le operazioni relative allo Store, quali l'acquisto di un prodotto. Se un'applicazione desktop non configura l'oggetto StoreContext per specificare la finestra proprietaria per le finestre di dialogo modali, questo oggetto restituirà dati non accurati o errori.

Per configurare un oggetto StoreContext in un'applicazione desktop che usa Desktop Bridge, seguire questa procedura.

Per .NET 6 o versione successiva

Se l'applicazione è scritta in C# con .NET 6 o versione successiva, seguire questa procedura.

1. Assicurarsi che la proprietà TargetFramework nel file del progetto sia impostata su una versione di Windows SDK specifica per accedere alle API di Windows Runtime, che fornisce accesso allo spazio dei nomi WinRT.Interop. Ad esempio:

   <PropertyGroup>
     <!-- You can also target other versions of the Windows SDK and .NET, e.g. "net6.0-windows10.0.19041.0" -->
     <TargetFramework>net6.0-windows10.0.22000.0</TargetFramework>
   </PropertyGroup>
   

2. Ottenere un oggetto StoreContext usando il metodo GetDefault (o GetForUser se l'app è un'app multiutente) come descritto in precedenza in questo articolo). Per inizializzare la finestra di dialogo con l'handle di finestra specificato, usare i metodi WinRT.Interop.WindowNative.GetWindowHandle e WinRT.Interop.InitializeWithWindow.Initialize (vedere Recuperare un handle di finestra e Visualizzare gli oggetti di interfaccia utente WinRT che dipendono da CoreWindow).

   StoreContext context = StoreContext.GetDefault();
   // Obtain window handle by passing in pointer to the window object
   var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(windowObject);
   // Initialize the dialog using wrapper function for IInitializeWithWindow
   WinRT.Interop.InitializeWithWindow.Initialize(context, hwnd); 
   

Per le versioni precedenti di .NET o C++

Se l'applicazione è scritta con una versione precedente di .NET o in C++, seguire questa procedura.

1. Eseguire una delle operazioni seguenti per consentire all'app di accedere all'interfaccia IInitializeWithWindow:

   • Se l'applicazione è scritta in un linguaggio gestito quale C# o Visual Basic (precedente a .NET 6), dichiarare l'interfaccia IInitializeWithWindow nel codice dell'app con l'attributo ComImport come illustrato nell'esempio seguente di C#. Questo esempio presuppone che il file di codice abbia un'istruzione using per lo spazio dei nomi System.Runtime.InteropServices.

     [ComImport]
     [Guid("3E68D4BD-7135-4D10-8018-9FB6D9F33FA1")]
     [InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
     public interface IInitializeWithWindow
     {
         void Initialize(IntPtr hwnd);
     }
     

   • Se l'applicazione è scritta in C++, aggiungere un riferimento al file di intestazione shobjidl.h nel codice. Questo file di intestazione contiene la dichiarazione dell'interfaccia IInitializeWithWindow.

2. Ottenere un oggetto StoreContext usando il metodo GetDefault (o GetForUser se l'app è un'app multiutente) come descritto in precedenza in questo articolo ed eseguire il cast di questo oggetto a un oggetto IInitializeWithWindow. Quindi, chiamare il metodo IInitializeWithWindow.Initialize e passare l'handle della finestra che si desidera sia proprietaria delle finestre di dialogo modali visualizzate dai metodi StoreContext. L'esempio C# seguente illustra come passare l'handle della finestra principale dell'app al metodo. Vedere anche Recuperare un handle di finestra (HWND) e Visualizzare oggetti interfaccia utente WinRT che dipendono da CoreWindow.

   StoreContext context = StoreContext.GetDefault();
   IInitializeWithWindow initWindow = (IInitializeWithWindow)(object)context;
   initWindow.Initialize(System.Diagnostics.Process.GetCurrentProcess().MainWindowHandle);
   

Prodotti, SKU e disponibilità

Ogni prodotto nello Store ha almeno uno SKU e ogni SKU ha almeno una disponibilità. Questi concetti non rientrano nell'ambito di lavoro della maggior parte degli sviluppatori nel Centro per i partner e la maggior parte degli sviluppatori non definirà mai SKU o disponibilità per le proprie app o i propri componenti aggiuntivi. Tuttavia, poiché il modello a oggetti per i prodotti Store nello spazio dei nomi Windows.Services.Store include SKU e disponibilità, una conoscenza di base di questi concetti può essere utile in alcuni scenari.

ID dello Store

A ogni app, componente aggiuntivo o altro prodotto nello Store è associato un ID dello Store (anche denominato ID dello Store del prodotto). Molte API richiedono l'ID dello Store per eseguire un'operazione su un'app o su un componente aggiuntivo.

L'ID dello Store di qualsiasi prodotto nello Store è una stringa alfanumerica di 12 caratteri, ad esempio 9NBLGGH4R315. Esistono diversi modi per ottenere l'ID dello Store per un prodotto nello Store:

• Per un'app, è possibile ottenere l'ID dello Store nella pagina di identità dell'app nel Centro per i partner.
• Per un componente aggiuntivo, è possibile ottenere l'ID dello Store nella pagina di panoramica del componente aggiuntivo nel Centro per i partner.
• Per qualsiasi prodotto, è anche possibile ottenere l'ID dello Store a livello di codice usando la proprietà StoreId dell'oggetto StoreProduct che rappresenta il prodotto.

Per i prodotti con SKU e disponibilità, anche gli SKU e le disponibilità hanno i relativi ID dello Store con formati diversi.

Come usare gli ID prodotto per i componenti aggiuntivi nel codice

Se si desidera rendere disponibile un componente aggiuntivo ai clienti nel contesto dell'app, è necessario immettere un ID prodotto univoco per il componente aggiuntivo quando si crea l'invio del componente aggiuntivo nel Centro per i partner. È possibile usare questo ID prodotto per fare riferimento al componente aggiuntivo nel codice, anche se gli scenari specifici in cui è possibile usare l'ID prodotto dipendono dallo spazio dei nomi usato per gli acquisti in-app nell'app.

App che usano lo spazio dei nomi Windows.Services.Store

Se l'app usa lo spazio dei nomi Windows.Services.Store, è possibile usare l'ID prodotto per identificare agevolmente l'oggetto StoreProduct che rappresenta il componente aggiuntivo o l'oggetto StoreLicense che rappresenta la licenza del componente aggiuntivo. L'ID prodotto è esposto dalle proprietà StoreProduct.InAppOfferToken e StoreLicense.InAppOfferToken.

App che usano lo spazio dei nomi Windows.ApplicationModel.Store

Se l'app usa lo spazio dei nomi Windows.ApplicationModel.Store, per la maggior parte delle operazioni sarà necessario usare l'ID prodotto che assegni a un componente aggiuntivo nel Centro per i partner. Ad esempio:

• Usare l'ID prodotto per identificare l'oggetto ProductListing che rappresenta il componente aggiuntivo o l'oggetto ProductLicense che rappresenta la licenza del componente aggiuntivo. L'ID prodotto è esposto dalle proprietà ProductListing.ProductId e ProductLicense.ProductId.

• Specificare l'ID prodotto quando si acquista il componente aggiuntivo per l'utente usando il metodo RequestProductPurchaseAsync. Per altre informazioni, vedere Abilitare gli acquisti di prodotti in-app.

• Specificare l'ID prodotto quando si segnala il componente aggiuntivo di consumo come evaso usando il metodo ReportConsumableFulfillmentAsync. Per ulteriori informazioni, vedere Abilitare gli acquisti di prodotti di consumo in-app.

Argomenti correlati

• Ottenere info sul prodotto per le app e i componenti aggiuntivi
• Ottenere info sulla licenza per le app e i componenti aggiuntivi
• Abilitare gli acquisti in-app di app e componenti aggiuntivi
• Abilitare gli acquisti di componenti aggiuntivi di consumo
• Abilitare i componenti aggiuntivi di sottoscrizione per la tua app
• Implementare una versione di prova dell'app
• Codici di errore per le operazioni nello Store
• Acquisti in-app e versioni di valutazione mediante lo spazio dei nomi Windows.ApplicationModel.Store