Compras no aplicativo e avaliaçõesIn-app purchases and trials

O SDK do Windows fornece APIs que você pode usar para implementar os seguintes recursos para ganhar mais dinheiro com seu aplicativo da Plataforma Universal do Windows (UWP):The Windows SDK provides APIs you can use to implement the following features to make more money from your Universal Windows Platform (UWP) app:

  • Compras no aplicativo  Seja seu aplicativo gratuito ou não, você pode vender conteúdo ou uma nova funcionalidade do aplicativo (como o desbloqueio do próximo nível de um jogo) no próprio aplicativo.In-app purchases  Whether your app is free or not, you can sell content or new app functionality (such as unlocking the next level of a game) from right within the app.

  • Funcionalidade de avaliação  @ No__t-2If você configura seu aplicativo como uma avaliação gratuita no Partner Center, você pode convencer seus clientes a comprar a versão completa do seu aplicativo excluindo ou limitando alguns recursos durante o período de avaliação.Trial functionality  If you configure your app as a free trial in Partner Center, you can entice your customers to purchase the full version of your app by excluding or limiting some features during the trial period. Você também pode habilitar recursos, como faixas ou marcas-d'água, que são mostrados apenas durante a avaliação, antes de o cliente comprar o aplicativo.You can also enable features, such as banners or watermarks, that are shown only during the trial, before a customer buys your app.

Este artigo fornece uma visão geral de como as compras no aplicativo e as avaliações funcionam em aplicativos UWP.This article provides an overview of how in-app purchases and trials work in UWP apps.

Escolha qual namespace usarChoose which namespace to use

Há dois namespaces diferentes que você pode usar para adicionar compras no aplicativo e funcionalidade de avaliação aos seus aplicativos UWP, dependendo da versão do Windows 10 à qual seus aplicativos se destinam.There are two different namespaces you can use to add in-app purchases and trial functionality to your UWP apps, depending on which version of Windows 10 your apps target. Embora as APIs nesses namespaces tenha os mesmos objetivos, elas foram criadas de forma bem diferente, e o código não é compatível entre as duas APIs.Although the APIs in these namespaces serve the same goals, they are designed quite differently, and code is not compatible between the two APIs.

Importante

O namespace Windows.ApplicationModel.Store não está sendo atualizado com os novos recursos e recomendamos que você use o namespace Windows.Services.Store em vez disso, se possível para seu app.The Windows.ApplicationModel.Store namespace is no longer being updated with new features, and we recommend that you use the Windows.Services.Store namespace instead if possible for your app. Não há suporte para o namespace Windows. ApplicationModel. Store em aplicativos de área de trabalho do Windows que usam a ponte de desktop ou em aplicativos ou jogos que usam uma área restrita de desenvolvimento no Partner Center (por exemplo, esse é o caso de qualquer jogo que integra-se ao Xbox Live).The Windows.ApplicationModel.Store namespace is not supported in Windows desktop applications that use the Desktop Bridge or in apps or games that use a development sandbox in Partner Center (for example, this is the case for any game that integrates with Xbox Live).

Conceitos básicosBasic concepts

Cada item que é oferecido na Loja é geralmente chamado de produto.Every item that is offered in the Store is generally called a product. A maioria dos desenvolvedores só trabalha com os seguintes tipos de produtos: apps e complementos.Most developers only work with the following types of products: apps and add-ons.

Um complemento é um produto ou recurso que você disponibiliza para os clientes no contexto do aplicativo: por exemplo, a moeda a ser usada em um aplicativo ou jogo, novos mapas ou armas para um jogo, a possibilidade de usar o aplicativo sem anúncios ou conteúdo digital, como músicas ou vídeos, para aplicativos que tenham a possibilidade de oferecer esse tipo de conteúdo.An add-on is a product or feature that you make available to your customers in the context of your app: for example, currency to be used in an app or game, new maps or weapons for a game, the ability to use your app without ads, or digital content such as music or videos for apps that have the ability to offer that type of content. Todos os aplicativos e complementos têm uma licença associada que indica se o usuário tem direito de usar o aplicativo ou complemento.Every app and add-on has an associated license that indicates whether the user is entitled to use the app or add-on. Se o usuário tiver direito de usar o aplicativo ou complemento como avaliação, a licença também fornece informações adicionais sobre a avaliação.If the user is entitled to use the app or add-on as a trial, the license also provides additional info about the trial.

Para oferecer um complemento aos clientes em seu aplicativo, você deve definir o complemento para seu aplicativo no Partner Center para que a loja saiba sobre ele.To offer an add-on to customers in your app, you must define the add-on for your app in Partner Center so the Store knows about it. Em seguida, seu aplicativo pode usar APIs no namespace Windows.Services.Store ou Windows.ApplicationModel.Store para oferecer o complemento para venda ao usuário como uma compra no aplicativo.Then, your app can use APIs in the Windows.Services.Store or Windows.ApplicationModel.Store namespace to offer the add-on for sale to the user as an in-app purchase.

Aplicativos UWP podem oferecer os seguintes tipos de complementos.UWP apps can offer the following types of add-ons.

Tipo de complementoAdd-on type DescriçãoDescription
DurávelDurable Um complemento que persiste durante o tempo de vida especificado no Partner Center.An add-on that persists for the lifetime that you specify in Partner Center.

Por padrão, os complementos duráveis nunca expiram, podendo ser adquiridos somente uma vez.By default, durable add-ons never expire, in which case they can only be purchased once. Se você especificar uma duração específica para o complemento, o usuário poderá comprar novamente o complemento depois que ele expirar.If you specify a particular duration for the add-on, the user can repurchase the add-on after it expires.

Consumível gerenciado pelo desenvolvedorDeveloper-managed consumable Um complemento que pode ser comprado, usado e comprado novamente após o consumo.An add-on that can be purchased, used, and then purchased again after it is consumed. Você é responsável por controlar o saldo de itens do usuário que o complemento representa.You are responsible for keeping track of the user's balance of items that the add-on represents.

Quando o usuário consome qualquer item associado ao complemento, você é responsável pela manutenção do saldo do usuário e por relatar a compra do complemento como providenciada para a Store depois que o usuário consome todos os itens.When the user consumes any items that are associated with the add-on, you are responsible for maintaining the user's balance and for reporting the purchase of the add-on as fulfilled to the Store after the user has consumed all the items. O usuário não pode comprar o complemento novamente até que seu aplicativo tenha informado a compra anterior do complemento como providenciada.The user cannot purchase the add-on again until your app has reported the previous add-on purchase as fulfilled.

Por exemplo, se o seu complemento representar 100 moedas em um jogo e o usuário consumir 10 moedas, seu aplicativo ou o serviço deverá manter o novo saldo restante de 90 moedas para o usuário.For example, if your add-on represents 100 coins in a game and the user consumes 10 coins, your app or service must maintain the new remaining balance of 90 coins for the user. Depois que o usuário tiver consumido todas as 100 moedas, seu aplicativo deverá declarar o complemento como providenciado e, em seguida, o usuário poderá comprar o complemento de 100 moedas novamente.After the user has consumed all 100 coins, your app must report the add-on as fulfilled, and then the user can purchase the 100 coin add-on again.

Consumível gerenciado pela LojaStore-managed consumable Um complemento que pode ser comprado, usado e comprado a qualquer momento.An add-on that can be purchased, used, and purchased again at any time. A Store mantém o controle do saldo de itens do usuário que o complemento representa.The Store keeps track of the user's balance of items that the add-on represents.

Quando o usuário consome todos os itens associados ao complemento, você é responsável por relatar esses itens como providenciados para a Store, e esta atualiza o saldo do usuário.When the user consumes any items that are associated with the add-on, you are responsible for reporting those items as fulfilled to the Store, and the Store updates the user's balance. O usuário pode adquirir o complemento quantas vezes desejar (não é necessário consumir os itens primeiro).The user can purchase the add-on as many times as they want (they do not need to consume the items first). Seu aplicativo pode consultar o saldo atual para o usuário a qualquer momento.Your app can query for the current balance for the user at any time.

Por exemplo, se o complemento representar uma quantidade inicial de 100 moedas em um jogo e o usuário consumir 50 moedas, o aplicativo relatará para a Store que 50 unidades do complemento foram providenciadas, e a Store atualizará o saldo restante.For example, if your add-on represents an initial quantity of 100 coins in a game and the user consumes 50 coins, your app reports to the Store that 50 units of the add-on were fulfilled, and the Store updates the remaining balance. Se o usuário comprar o complemento novamente para adquirir mais 100 moedas, ele agora terá 150 moedas no total.If the user then repurchases your add-on to acquire 100 more coins, they will now have 150 coins total.

Observação  Para usar consumíveis gerenciados pela Microsoft Store, o aplicativo deve ser direcionado ao Windows 10 Anniversary Edition (10.0; Compilação 14393) ou uma versão posterior no Visual Studio, e deve usar o namespace Windows.Services.Store em vez do namespace Windows.ApplicationModel.Store.Note  To use Store-managed consumables, your app must target Windows 10 Anniversary Edition (10.0; Build 14393) or a later release in Visual Studio, and it must use the Windows.Services.Store namespace instead of the Windows.ApplicationModel.Store namespace.

AssinaturaSubscription Um complemento durável em que o cliente continua a ser cobrado em intervalos recorrentes para continuar usando o complemento.A durable add-on where the customer continues to be charged at recurring intervals in order to keep using the add-on. O cliente pode cancelar a assinatura a qualquer momento para evitar cobranças futuras.The customer can cancel the subscription at any time to avoid further charges.

Observação  Para usar complementos de assinatura, o aplicativo deve ser direcionado ao Windows 10 Anniversary Edition (10.0; Build 14393) ou uma versão posterior no Visual Studio, e deve usar o namespace Windows.Services.Store em vez do namespace Windows.ApplicationModel.Store.Note  To use subscription add-ons, your app must target Windows 10 Anniversary Edition (10.0; Build 14393) or a later release in Visual Studio, and it must use the Windows.Services.Store namespace instead of the Windows.ApplicationModel.Store namespace.

Observação

Outros tipos de complementos, como complementos duráveis com pacotes (também conhecidos como conteúdo baixável ou DLC), estão disponíveis apenas para um conjunto restrito de desenvolvedores e não são abordados nesta documentação.Other types of add-ons, such as durable add-ons with packages (also known as downloadable content or DLC) are only available to a restricted set of developers, and are not covered in this documentation.

Compras no aplicativo e avaliações usando o namespace Windows.Services.StoreIn-app purchases and trials using the Windows.Services.Store namespace

Esta seção fornece uma visão geral das tarefas e dos conceitos importantes para o namespace Windows.Services.Store.This section provides an overview of important tasks and concepts for the Windows.Services.Store namespace. Esse namespace está disponível somente para aplicativos destinados ao Windows 10 Anniversary Edition (10.0; Compilação 14393) ou uma versão posterior no Visual Studio (isso corresponde ao Windows 10, versão 1607).This namespace is available only to apps that target Windows 10 Anniversary Edition (10.0; Build 14393) or a later release in Visual Studio (this corresponds to Windows 10, version 1607). Recomendamos que os aplicativos usem o namespace Windows.Services.Store em vez do namespace Windows.ApplicationModel.Store, se possível.We recommend that apps use the Windows.Services.Store namespace instead of the Windows.ApplicationModel.Store namespace if possible. Para obter informações sobre o namespace Windows.ApplicationModel.Store, consulte este artigo.For information about the Windows.ApplicationModel.Store namespace, see this article.

Nesta seçãoIn this section

VídeoVideo

Assista ao vídeo a seguir para obter uma visão geral de como implementar compras no aplicativo em seu app usando o namespace Windows.Services.Store.Watch the following video for an overview of how to implement in-app purchases in your app using the Windows.Services.Store namespace.

Introdução à classe StoreContextGet started with the StoreContext class

O ponto de entrada principal para o namespace Windows.Services.Store é a classe StoreContext.The main entry point to the Windows.Services.Store namespace is the StoreContext class. Essa classe fornece métodos que você pode usar para obter informações do aplicativo atual e seus complementos disponíveis, obter informações de licença do aplicativo atual ou seus complementos, comprar um aplicativo ou um complemento para o usuário atual e realizar outras tarefas.This class provides methods you can use to get info for the current app and its available add-ons, get license info for the current app or its add-ons, purchase an app or add-on for the current user, and perform other tasks. Para obter um objeto StoreContext, siga um destes procedimentos:To get a StoreContext object, do one of the following:

  • Em um app de usuário único (ou seja, um app executado apenas no contexto do usuário que iniciou o app), use o método GetDefault estático para obter um objeto StoreContext que seja possível usar para acessar dados relacionados à Microsoft Store para o usuário.In a single-user app (that is, an app that runs only in the context of the user that launched the app), use the static GetDefault method to get a StoreContext object that you can use to access Microsoft Store-related data for the user. A maioria dos aplicativos da Plataforma Universal do Windows (UWP) é um aplicativo de usuário único.Most Universal Windows Platform (UWP) apps are single-user apps.

    Windows.Services.Store.StoreContext context = StoreContext.GetDefault();
    
  • Em um app multiusuário, use o método GetForUser estático para obter um objeto StoreContext que seja possível usar para acessar dados relacionados à Microsoft Store para um usuário específico que tenha feito logon usando a conta da Microsoft durante o uso do app.In a multi-user app, use the static GetForUser method to get a StoreContext object that you can use to access Microsoft Store-related data for a specific user who is signed in with their Microsoft account while using the app. O exemplo a seguir obtém um objeto StoreContext para o primeiro usuário disponível.The following example gets a StoreContext object for the first available user.

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

Observação

Os aplicativos da área de trabalho do Windows que usam o Ponte de Desktop devem realizar etapas adicionais para configurar o objeto StoreContext para poder usar esse objeto.Windows desktop applications that use the Desktop Bridge must perform additional steps to configure the StoreContext object before they can use this object. Para obter mais informações, consulte esta seção.For more information, see this section.

Depois que tiver um objeto StoreContext, você poderá começar a chamar métodos desse objeto para obter informações da Loja sobre o aplicativo atual e os complementos, recuperar informações de licença para o aplicativo atual e os complementos, comprar um aplicativo ou um complemento para o usuário atual e realizar outras tarefas.After you have a StoreContext object, you can start calling methods of this object to get Store product info for the current app and its add-ons, retrieve license info for the current app and its add-ons, purchase an app or add-on for the current user, and perform other tasks. Para obter mais informações sobre tarefas comuns que você pode realizar usando esse objeto, consulte os seguintes artigos:For more information about common tasks you can perform using this object, see the following articles:

Para obter um aplicativo de exemplo que demonstre como usar StoreContext e outros tipos no namespace Windows.Services.Store, consulte o exemplo da Loja.For a sample app that demonstrates how to use StoreContext and other types in the Windows.Services.Store namespace, see the Store sample.

Implementar compras no aplicativoImplement in-app purchases

Para oferecer uma compra no aplicativo aos clientes em seu aplicativo usando o namespace Windows.Services.Store:To offer an in-app purchase to customers in your app using the Windows.Services.Store namespace:

  1. Se seu aplicativo oferece complementos que os clientes podem comprar, crie envios de complemento para seu aplicativo no Partner Center .If your app offers add-ons that customers can purchase, create add-on submissions for your app in Partner Center .

  2. Escreva um código em seu aplicativo para recuperar informações de produto para o aplicativo ou um complemento oferecido pelo aplicativo e determinar se a licença está ativa (ou seja, se o usuário tiver uma licença para usar o aplicativo ou um complemento).Write code in your app to retrieve product info for your app or an add-on offered by your app and then determine whether the license is active (that is, whether the user has a license to use the app or add-on). Se a licença não estiver ativa, exiba uma interface do usuário que ofereça o aplicativo ou complemento para venda ao usuário como uma compra no aplicativo.If the license isn't active, display a UI that offers the app or add-on for sale to the user as an in-app purchase.

  3. Se o usuário optar por comprar o aplicativo ou o complemento, use o método indicado para comprar o produto:If the user chooses to purchase your app or add-on, use the appropriate method to purchase the product:

  4. Teste a implementação seguindo as diretrizes de teste neste artigo.Test your implementation by following the testing guidance in this article.

Implementar a funcionalidade de avaliaçãoImplement trial functionality

Para excluir ou limitar recursos em uma versão de avaliação do seu aplicativo usando o namespace Windows.Services.Store:To exclude or limit features in a trial version of your app using the Windows.Services.Store namespace:

  1. Configure seu aplicativo como uma avaliação gratuita no Partner Center.Configure your app as a free trial in Partner Center.

  2. Escreva um código em seu aplicativo para recuperar informações de produto para o aplicativo ou um complemento oferecido pelo aplicativo e determine se a licença associada ao aplicativo é uma licença de avaliação.Write code in your app to retrieve product info for your app or an add-on offered by your app and then determine whether the license associated with the app is a trial license.

  3. Exclua ou limite determinados recursos no aplicativo caso ela seja uma versão de avaliação e habilite os recursos quando o usuário comprar uma licença completa.Exclude or limit certain features in your app if it is a trial, and then enable the features when the user purchases a full license. Para obter mais informações e um exemplo de código, consulte Implementar uma versão de avaliação do aplicativo.For more information and a code example, see Implement a trial version of your app.

  4. Teste a implementação seguindo as diretrizes de teste neste artigo.Test your implementation by following the testing guidance in this article.

Testar a compra realizada em aplicativo ou a implementação de avaliaçãoTest your in-app purchase or trial implementation

Se seu app usa APIs no namespace Windows.Services.Store para implementar compras no aplicativo ou a funcionalidade de avaliação, você deve publicar seu aplicativo na Microsoft Store e baixá-lo em seu dispositivo de desenvolvimento para usar sua licença de teste.If your app uses APIs in the Windows.Services.Store namespace to implement in-app purchase or trial functionality, you must publish your app to the Store and download the app to your development device to use its license for testing. Siga este processo para testar seu código:Follow this process to test your code:

  1. Se seu aplicativo ainda não estiver publicado e disponível na loja, verifique se seu aplicativo atende aos requisitos mínimos do Kit de certificação de aplicativos do Windows , envie seu aplicativo no Partner Center e certifique-se de que seu aplicativo passe o processo de certificação.If your app is not yet published and available in the Store, make sure your app meets the minimum Windows App Certification Kit requirements, submit your app in Partner Center, and make sure your app passes the certification process. Você pode configurar seu app para que ele não possa ser descoberto na Store durante os testes.You can configure your app so it is not discoverable in the Store while you test it. Observe a configuração adequada dos voos do pacote.Please note the proper configuration of package flights. Os vôos de pacote configurados incorretamente talvez não possam ser baixados.Incorrectly configured package flights may be not be able to be downloaded.

  2. Em seguida, certifique-se de que você tenha concluído o seguinte:Next, make sure you have completed the following:

  3. Com seu projeto aberto no Visual Studio, clique no menu Projeto, aponte para Loja e clique em Associar Aplicativo à Loja.With your project open in Visual Studio, click the Project menu, point to Store, and then click Associate App with the Store. Conclua as instruções no Assistente para associar o projeto de aplicativo ao aplicativo em sua conta do Partner Center que você deseja usar para teste.Complete the instructions in the wizard to associate the app project with the app in your Partner Center account that you want to use for testing.

    Observação

    Se você não associar seu projeto a um aplicativo na Store, os métodos StoreContext definirão a propriedade ExtendedError dos valores de retorno como o valor de código de erro 0x803F6107.If you do not associate your project with an app in the Store, the StoreContext methods set the ExtendedError property of their return values to the error code value 0x803F6107. Esse valor indica que a Loja desconhece o aplicativo.This value indicates that the Store doesn't have any knowledge about the app.

  4. Se você não tiver feito isso ainda, instale o aplicativo da Loja que você especificou na etapa anterior, execute-o uma vez e, em seguida, feche-o.If you have not done so already, install the app from the Store that you specified in the previous step, run the app once, and then close this app. Isso garante que uma licença válida para o aplicativo seja instalada em seu dispositivo de desenvolvimento.This ensures that a valid license for the app is installed to your development device.

  5. No Visual Studio, comece a executar ou depurar seu projeto.In Visual Studio, start running or debugging your project. Seu código deverá recuperar dados do aplicativo e do complemento do aplicativo da Loja que você associou ao seu projeto local.Your code should retrieve app and add-on data from the Store app that you associated with your local project. Se for solicitada a reinstalação do aplicativo, siga as instruções e execute ou depure o projeto.If you are prompted to reinstall the app, follow the instructions and then run or debug your project.

    Observação

    Depois de concluir essas etapas, você poderá continuar atualizando o código do aplicativo e, em seguida, depurar o projeto atualizado no computador de desenvolvimento sem enviar novos pacotes de aplicativos para a Store.After you complete these steps, you can continue to update your app's code and then debug your updated project on your development computer without submitting new app packages to the Store. Você só precisa baixar a versão da Loja do aplicativo no computador de desenvolvimento uma vez para obter a licença local que será usada para teste.You only need to download the Store version of your app to your development computer once to obtain the local license that will be used for testing. Você só precisará enviar novos pacotes de aplicativos para a Loja depois de concluir o teste e se quiser disponibilizar os recursos relacionados à avaliação ou à compra no aplicativo no aplicativo para os clientes.You only need to submit new app packages to the Store after you complete your testing and you want to make the in-app purchase or trial-related features in your app available to your customers.

Se o seu app usa o namespace Windows.ApplicationModel.Store, você pode usar a classe CurrentAppSimulator em seu app para simular as informações de licença durante o teste antes de enviar seu app para a Store.If your app uses the Windows.ApplicationModel.Store namespace, you can use the CurrentAppSimulator class in your app to simulate license info during testing before you submit your app to the Store. Para obter mais informações, consulte Introdução às classes CurrentApp e CurrentAppSimulator.For more information, see Get started with the CurrentApp and CurrentAppSimulator classes.

Observação

O namespace Windows.Services.Store não fornece uma classe que seja possível usar para simular informações de licença durante o teste.The Windows.Services.Store namespace does not provide a class that you can use to simulate license info during testing. Se você usar o namespace Windows.Services.Store para implementar compras ou avaliações no aplicativo, deverá publicar seu app na Store e baixá-lo em seu dispositivo de desenvolvimento para usar sua licença de teste como descrito acima.If you use the Windows.Services.Store namespace to implement in-app purchases or trials, you must publish your app to the Store and download the app to your development device to use its license for testing as described above.

Recibos para compras no aplicativoReceipts for in-app purchases

O namespace Windows.Services.Store não fornece uma API que seja possível usar para obter um recibo de transação para compras bem-sucedidas no código do aplicativo.The Windows.Services.Store namespace does not provide an API you can use to obtain a transaction receipt for successful purchases in your app's code. Essa é uma experiência diferente de aplicativos que usam o namespace Windows.ApplicationModel.Store, que pode usar uma API do lado do cliente para recuperar um recibo de transação.This is a different experience from apps that use the Windows.ApplicationModel.Store namespace, which can use a client-side API to retrieve a transaction receipt.

Se você implementar compras no aplicativo usando o namespace Windows.Services.Store e você desejar validar se um determinado cliente comprou um app ou um complemento, você pode usar a consulta para o método de produtos na API REST da coleção da Microsoft Store.If you implement in-app purchases using the Windows.Services.Store namespace and you want to validate whether a given customer has purchased an app or add-on, you can use the query for products method in the Microsoft Store collection REST API. Os dados de retorno para esse método confirmam se o cliente especificado tem um direito para um determinado produto e fornecem dados para a transação na qual o usuário adquiriu o produto.The return data for this method confirms whether the specified customer has an entitlement for a given product, and provides data for the transaction in which the user acquired the product. A API de coleção da Microsoft Store usa a autenticação do Azure AD para recuperar essas informações.The Microsoft Store collection API uses Azure AD authentication to retrieve this information.

Como usar a classe StoreContext com o Desktop BridgeUsing the StoreContext class with the Desktop Bridge

Os aplicativos da área de trabalho que usam o Desktop Bridge podem utilizar a classe StoreContext para implementar compras no aplicativo e avaliações.Desktop applications that use the Desktop Bridge can use the StoreContext class to implement in-app purchases and trials. No entanto, se você tiver um aplicativo da área de trabalho Win32 ou um aplicativo da área de trabalho que tenha um identificador de janela (HWND) associado à estrutura de renderização (por exemplo, um aplicativo WPF), seu aplicativo deve configurar o objeto StoreContext para especificar qual janela do aplicativo é a janela do proprietário para caixas de diálogo modais que são mostradas pelo objeto.However, if you have a Win32 desktop application or a desktop application that has a window handle (HWND) that is associated with the rendering framework (such as a WPF application), your application must configure the StoreContext object to specify which application window is the owner window for modal dialogs that are shown by the object.

Muitos membros do StoreContext (e membros de outros tipos relacionados que são acessados por meio do objeto StoreContext) exibem uma caixa de diálogo modal para o usuário para operações relacionadas à Loja, como comprar um produto.Many StoreContext members (and members of other related types that are accessed through the StoreContext object) display a modal dialog to the user for Store-related operations such as purchasing a product. Se um aplicativo de desktop não configura o objeto StoreContext para especificar a janela do proprietário para caixas de diálogo modais, esse objeto retornará dados imprecisos ou erros.If a desktop application does not configure the StoreContext object to specify the owner window for modal dialogs, this object will return inaccurate data or errors.

Para configurar um objeto StoreContext em um aplicativo da área de trabalho que use o Desktop Bridge, siga estas etapas.To configure a StoreContext object in a desktop application that uses the Desktop Bridge, follow these steps.

  1. Siga um destes procedimentos para permitir que o aplicativo acesse a interface IInitializeWithWindow:Do one of the following to enable your app to access the IInitializeWithWindow interface:

    • Se o aplicativo estiver escrito em uma linguagem gerenciada, como C# ou Visual Basic, declare a interface IInitializeWithWindow no código do aplicativo com o atributo ComImport conforme mostrado no exemplo em C# a seguir.If your application is written in a managed language such as C# or Visual Basic, declare the IInitializeWithWindow interface in your app's code with the ComImport attribute as shown in the following C# example. Este exemplo pressupõe que o arquivo de código tenha uma declaração using para o namespace InteropServices.This example assumes that your code file has a using statement for the System.Runtime.InteropServices namespace.

      [ComImport]
      [Guid("3E68D4BD-7135-4D10-8018-9FB6D9F33FA1")]
      [InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
      public interface IInitializeWithWindow
      {
          void Initialize(IntPtr hwnd);
      }
      
    • Se o aplicativo estiver escrito em C++, adicione uma referência ao arquivo de cabeçalho shobjidl.h no código.If your application is written in C++, add a reference to the shobjidl.h header file in your code. Este arquivo de cabeçalho contém a declaração da interface IInitializeWithWindow.This header file contains the declaration of the IInitializeWithWindow interface.

  2. Obtenha um objeto StoreContext usando o método GetDefault (ou GetForUser caso o aplicativo seja um aplicativo multiusuário) conforme descrito anteriormente neste artigo, e converta esse objeto em um objeto IInitializeWithWindow.Get a StoreContext object by using the GetDefault method (or GetForUser if your app is a multi-user app) as described earlier in this article, and cast this object to an IInitializeWithWindow object. Em seguida, chame o método IInitializeWithWindow.Initialize e passe o identificador da janela da qual você deseja ser o proprietário para eventuais caixas de diálogo modais mostradas por métodos StoreContext.Then, call the IInitializeWithWindow.Initialize method, and pass the handle of the window that you want to be the owner for any modal dialogs that are shown by StoreContext methods. O exemplo em C# a seguir mostra como passar o identificador da janela principal do aplicativo para o método.The following C# example shows how to pass the handle of your app's main window to the method.

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

Produtos, SKUs e disponibilidadesProducts, SKUs, and availabilities

Cada produto na Loja tem pelo menos uma SKU, e cada SKU tem pelo menos uma disponibilidade.Every product in the Store has at least one SKU, and each SKU has at least one availability. Esses conceitos são dissociados da maioria dos desenvolvedores no Partner Center, e a maioria dos desenvolvedores nunca definirá SKUs ou Availabilities para seus aplicativos ou Complementos.These concepts are abstracted away from most developers in Partner Center, and most developers will never define SKUs or availabilities for their apps or add-ons. No entanto, como o objeto de modelo para produtos da Store no namespace Windows.Services.Store inclui disponibilidades e SKUs, um entendimento básico sobre esses conceitos pode ser útil para alguns cenários.However, because the object model for Store products in the Windows.Services.Store namespace includes SKUs and availabilities, a basic understanding of these concepts can be helpful for some scenarios.

ObjectObject DescriçãoDescription
ProdutoProduct Um produto refere-se a qualquer tipo de produto que esteja disponível na Store, incluindo um app ou um complemento.A product refers to any type of product that is available in the Store, including an app or add-on.

Cada produto na Store tem um objeto StoreProduct correspondente.Each product in the Store has a corresponding StoreProduct object. Essa classe fornece propriedades que você pode usar para acessar dados, como a ID da Loja do produto, as imagens e os vídeos para a listagem da Loja e informações de preços.This class provides properties you can use to access data such as the Store ID of the product, the images and videos for the Store listing, and pricing info. Também fornece métodos que você pode usar para comprar o produto.It also provides methods you can use to purchase the product.

SKUSKU A SKU é uma versão específica de um produto com sua própria descrição, preço e outros detalhes exclusivos do produto.A SKU is a specific version of a product with its own description, price, and other unique product details. Cada aplicativo ou complemento tem uma SKU padrão.Each app or add-on has a default SKU. O único momento em que a maioria dos desenvolvedores terá várias SKUs para um aplicativo é se publicarem uma versão completa do aplicativo e uma versão de avaliação (no catálogo da Loja, cada uma dessas versões é uma SKU diferente do mesmo aplicativo).The only time most developers will ever have multiple SKUs for an app is if they publish a full version of their app and a trial version (in the Store catalog, each of these versions is a different SKU of the same app).

Alguns fornecedores podem definir suas próprias SKUs.Some publishers have the ability to define their own SKUs. Por exemplo, um grande fornecedor de jogos pode lançar um jogo com uma SKU que mostre sangue verde em mercados que não permitem sangue vermelho e outra SKU que mostre sangue vermelho nos demais mercados.For example, a large game publisher might release a game with one SKU that shows green blood in markets that don't allow red blood and a different SKU that shows red blood in all other markets. Como alternativa, um fornecedor que vende conteúdo em vídeo digital pode publicar duas SKUs para um vídeo, uma SKU para a versão em alta definição e outra SKU para a versão em definição padrão.Alternatively, a publisher who sells digital video content might publish two SKUs for a video, one SKU for the high-definition version and a different SKU for the standard-definition version.

Cada SKU na Store tem um objeto StoreSku correspondente.Each SKU in the Store has a corresponding StoreSku object. Cada StoreProduct tem uma propriedade Skus que você pode usar para acessar as SKUs para o produto.Every StoreProduct has a Skus property you can use to access the SKUs for the product.

DisponibilidadeAvailability Uma disponibilidade é uma versão específica de uma SKU com suas próprias informações de preço.An availability is a specific version of a SKU with its own unique pricing info. Cada SKU tem uma disponibilidade padrão.Each SKU has a default availability. Alguns fornecedores podem definir suas próprias disponibilidade para apresentar opções de preço diferentes para determinada SKU.Some publishers have the ability to define their own availabilities to introduce different price options for a given SKU.

Cada disponibilidade na Store tem um objeto StoreAvailability correspondente.Each availability in the Store has a corresponding StoreAvailability object. Cada StoreSku tem uma propriedade Availabilities que você pode usar para acessar as disponibilidades para a SKU.Every StoreSku has an Availabilities property you can use to access the availabilities for the SKU. Para a maioria dos desenvolvedores, cada SKU tem uma única disponibilidade padrão.For most developers, each SKU has a single default availability.

IDs da LojaStore IDs

Cada app, complemento ou outro produto na Store tenha uma ID da Store associada (que às vezes também é chamada de ID da Store do produto).Every app, add-on, or other product in the Store has an associated Store ID (this is also sometimes called a product Store ID). Muitas APIs exigem a ID da LOja para executar uma operação em um app ou complemento.Many APIs require the Store ID in order to perform an operation on an app or add-on.

A ID da Loja de qualquer produto na Loja é uma cadeia de 12 caracteres alfanuméricos, como 9NBLGGH4R315.The Store ID of any product in the Store is 12-character alpha-numeric string, such as 9NBLGGH4R315. Há várias maneiras diferentes de se obter a ID da Store para um produto na Store:There are several different ways to get the Store ID for a product in the Store:

  • Para um aplicativo, você pode obter a ID da loja na página identidade do aplicativo no Partner Center.For an app, you can get the Store ID on the App identity page in Partner Center.
  • Para um complemento, você pode obter a ID da loja na página de visão geral do complemento no Partner Center.For an add-on, you can get the Store ID on the add-on's overview page in Partner Center.
  • Para qualquer produto, você também pode obter a ID da Store programaticamente usando a propriedade StoreId do objeto StoreProduct que representa o produto.For any product, you can also get the Store ID programmatically by using the StoreId property of the StoreProduct object that represents the product.

Para produtos com SKUs e disponibilidades, as SKUs e as disponibilidades também têm suas próprias IDs da Store com formatos diferentes.For products with SKUs and availabilities, the SKUs and availabilities also have their own Store IDs with different formats.

ObjectObject Formato da ID da LojaStore ID format
SKUSKU A ID da Store para uma SKU tem o formato <product Store ID>/xxxx, onde xxxx é uma cadeia de 4 caracteres alfanuméricos que identifica uma SKU do produto.The Store ID for a SKU has the format <product Store ID>/xxxx, where xxxx is a 4-character alpha-numeric string that identifies a SKU for the product. Por exemplo: 9NBLGGH4R315/000N.For example, 9NBLGGH4R315/000N. Essa ID é retornada pela propriedade StoreId de um objeto StoreSku e é chamada, às vezes, de ID da Loja para a SKU.This ID is returned by the StoreId property of a StoreSku object, and it is sometimes called the SKU Store ID.
DisponibilidadeAvailability A ID da Store para uma disponibilidade tem o formato <product Store ID>/xxxx/yyyyyyyyyyyy, onde xxxx é uma cadeia de 4 caracteres alfanuméricos que identifica uma SKU do produto e yyyyyyyyyyyy é uma cadeia de 12 caracteres alfanuméricos que identifica uma disponibilidade para a SKU.The Store ID for an availability has the format <product Store ID>/xxxx/yyyyyyyyyyyy, where xxxx is a 4-character alpha-numeric string that identifies a SKU for the product and yyyyyyyyyyyy is a 12-character alpha-numeric string that identifies an availability for the SKU. Por exemplo: 9NBLGGH4R315/000N/4KW6QZD2VN6X.For example, 9NBLGGH4R315/000N/4KW6QZD2VN6X. Essa ID é retornada pela propriedade StoreId de um objeto StoreAvailability e é chamada, às vezes, de ID da Loja para a disponibilidade.This ID is returned by the StoreId property of a StoreAvailability object, and it is sometimes called the availability Store ID.

Como usar IDs do produto (product IDs) para complementos no seu códigoHow to use product IDs for add-ons in your code

Se desejar disponibilizar um complemento para seus clientes no contexto do seu aplicativo, você deverá Inserir uma ID de produto exclusiva para seu complemento ao criar o envio do complemento no Partner Center.If you want to make an add-on available to your customers in the context of your app, you must enter a unique product ID for your add-on when you create your add-on submission in Partner Center. Você pode usar essa ID do produto (product ID) para fazer referência ao complemento em seu código, embora os cenários específicos nos quais você poderá usar a ID do produto dependerão do namespace usado para compras no aplicativo do seu app.You can use this product ID to refer to the add-on in your code, although the specific scenarios in which you can use the product ID depend on which namespace you use for in-app purchases in your app.

Observação

A ID do produto que você inseriu no Partner Center para um complemento é diferente da ID de armazenamentodo complemento.The product ID that you enter in Partner Center for an add-on is different than the add-on's Store ID. A ID da loja é gerada pelo Partner Center.The Store ID is generated by Partner Center.

Apps que usam o namespace Windows.Services.StoreApps that use the Windows.Services.Store namespace

Se seu app usar o namespace Windows.Services.Store, você poderá usar a ID do produto (product ID) para identificar com facilidade o StoreProduct que representa o complemento ou a StoreLicense que representa a licença do complemento.If your app uses the Windows.Services.Store namespace, you can use the product ID to easily identify the StoreProduct that represents your add-on or the StoreLicense that represents your add-on's license. A ID do produto (product ID) é exposta pelas propriedades StoreProduct.InAppOfferToken e StoreLicense.InAppOfferToken.The product ID is exposed by the StoreProduct.InAppOfferToken and StoreLicense.InAppOfferToken properties.

Observação

Embora a ID do produto (product ID) seja uma maneira útil de identificar um complemento em seu código, a maioria das operações no namespace Windows.Services.Store usa a ID da Store de um complemento em vez da ID do produto.Although the product ID is a useful way to identify an add-on in your code, most operations in the Windows.Services.Store namespace use the Store ID of an add-on instead of the product ID. Por exemplo, para recuperar programaticamente um ou mais complementos conhecidos para um app, passe as IDs da Store (em vez das IDs do produto (product IDs) dos complementos para o método GetStoreProductsAsync.For example, to programmatically retrieve one or more known add-ons for an app, pass the Store IDs (rather than the product IDs) of the add-ons to the GetStoreProductsAsync method. Da mesma forma, para reportar um complemento consumível como providenciado, passe a ID da Store do complemento (em vez da ID do produto (productID)) para o método ReportConsumableFulfillmentAsync.Similarly, to report a consumable add-on as fulfilled, pass the Store ID of the add-on (rather than the product ID) to the ReportConsumableFulfillmentAsync method.

Apps que usam o namespace Windows.ApplicationModel.StoreApps that use the Windows.ApplicationModel.Store namespace

Se seu aplicativo usar o namespace Windows. ApplicationModel. Store , você precisará usar a ID do produto que você atribui a um complemento no Partner Center para a maioria das operações.If your app uses the Windows.ApplicationModel.Store namespace, you'll need to use the product ID that you assign to an add-on in Partner Center for most operations. Por exemplo:For example: