Habilitar compras de produtos consumíveis no aplicativo

  • Artigo

Ofereça produtos consumíveis no aplicativo — itens que podem ser comprados, usados e comprados novamente — por meio da plataforma de comércio da Loja para proporcionar aos seus clientes uma experiência de compra robusta e confiável. Isso é especialmente útil para itens como moedas em jogos (ouro, moedas etc.) que podem ser comprados e então usados para comprar power-ups específicos.

Importante

Este artigo demonstra como usar os membros do namespace Windows.ApplicationModel.Store para habilitar compras de produto consumível no aplicativo. Esse namespace não está sendo atualizado com os novos recursos e recomendamos que você use o namespace Windows.Services.Store em vez disso. O namespace Windows.Services.Store dá suporte aos tipos de complementos mais recentes, como complementos e assinaturas consumíveis gerenciados pela Store, e foi projetado para ser compatível com tipos futuros de produtos e recursos compatíveis com o Partner Center e a Store. O namespace Windows.Services.Store foi introduzido no Windows 10, versão 1607 e pode ser usada somente em projetos para Windows 10 Anniversary Edition (10.0; Compilação 14393) ou uma versão posterior no Visual Studio. Para obter informações sobre como habilitar as compras de produtos consumíveis no aplicativo usando o namespace Windows.Services.Store, consulte este artigo.

Pré-requisitos

  • Este tópico trata dos relatórios de compra e atendimento de produtos no aplicativo consumíveis. Se você não tiver familiaridade com produtos no aplicativo, examine Habilitar compras de produto no aplicativo para saber mais sobre informações de licença e como listar adequadamente produto nos aplicativo na Loja.
  • Ao codificar e testar novos produtos no aplicativo pela primeira vez, você deve usar o objeto CurrentAppSimulator em vez do objeto CurrentApp. Dessa forma, é possível verificar a lógica do licenciamento usando chamadas simuladas ao servidor de licenças, em vez de chamar o servidor ativo. Para fazer isso, você precisa personalizar o arquivo chamado WindowsStoreProxy.xml em %userprofile%\AppData\local\packages\<package name>\LocalState\Microsoft\Windows Store\ApiData. O simulador do Microsoft Visual Studio cria esse arquivo quando você executa seu app pela primeira vez, mas também é possível carregar um arquivo personalizado em tempo de execução. Para obter mais informações, consulte Usando o arquivo WindowsStoreProxy.xml com CurrentAppSimulator.
  • Este tópico também faz referência a exemplos de código fornecidos no Exemplo da Loja. Este exemplo é uma ótima maneira de obter experiência prática com as diferentes opções de monetização fornecidas para os aplicativos UWP (Plataforma Universal do Windows).

Etapa 1: Fazendo a solicitação de compra

A solicitação de compra inicial é feita com RequestProductPurchaseAsync, como acontece com qualquer outra compra feita na Loja. A diferença no caso dos produtos consumíveis no aplicativo é que, depois de uma compra bem-sucedida, um cliente não pode comprar o mesmo produto outra vez até que o aplicativo tenha notificado a Loja de que a compra anterior foi atendida com êxito. É de responsabilidade do seu aplicativo atender aos consumíveis comprados e notificar a Windows Store do atendimento.

O próximo exemplo mostra uma solicitação de compra de produto no aplicativo consumível. Você perceberá comentários de código que indicam quando seu app deve realizar seu atendimento local do produto consumível no aplicativo para dois cenários diferentes — quando a solicitação é bem-sucedida e quando ela não é bem-sucedida devido a uma compra não atendida do mesmo produto.

PurchaseResults purchaseResults = await CurrentAppSimulator.RequestProductPurchaseAsync("product1");
switch (purchaseResults.Status)
{
    case ProductPurchaseStatus.Succeeded:
        product1TempTransactionId = purchaseResults.TransactionId;

        // Grant the user their purchase here, and then pass the product ID and transaction ID to
        // CurrentAppSimulator.ReportConsumableFulfillment to indicate local fulfillment to the
        // Windows Store.
        break;

    case ProductPurchaseStatus.NotFulfilled:
        product1TempTransactionId = purchaseResults.TransactionId;

        // First check for unfulfilled purchases and grant any unfulfilled purchases from an
        // earlier transaction. Once products are fulfilled pass the product ID and transaction ID
        // to CurrentAppSimulator.ReportConsumableFulfillment to indicate local fulfillment to the
        // Windows Store.
        break;
}

Etapa 2: Rastreando o atendimento local do consumível

Ao conceder ao seu cliente acesso ao produto consumível no aplicativo, é importante manter o controle de qual produto é atendido (productId) e a qual transação o atendimento está associado (transactionId).

Importante

O aplicativo é responsável pelo atendimento de relatórios precisos junto à Windows Store. Essa etapa é essencial para manter uma experiência de compras justa e confiável para os seus clientes.

O exemplo a seguir demonstra o uso das propriedades PurchaseResults da chamada a RequestProductPurchaseAsync na etapa anterior para identificar o produto comprado para atendimento. Uma coleção é usada para armazenar as informações do produto em um local que, mais tarde, pode ser referenciado para confirmar se o atendimento local foi bem-sucedido.

private void GrantFeatureLocally(string productId, Guid transactionId)
{
    if (!grantedConsumableTransactionIds.ContainsKey(productId))
    {
        grantedConsumableTransactionIds.Add(productId, new List<Guid>());
    }
    grantedConsumableTransactionIds[productId].Add(transactionId);

    // Grant the user their content. You will likely increase some kind of gold/coins/some other asset count.
}

Este próximo exemplo mostra como usar a matriz do exemplo anterior para acessar pares de ID do produto/ID da transação que, mais tarde, serão usados para relatar o atendimento à Loja.

Importante

Seja qual for a metodologia que seu aplicativo use para controlar e confirmar o atendimento, o aplicativo precisa demonstrar discernimento para garantir que os clientes não sejam cobrados por itens que não receberam.

private Boolean IsLocallyFulfilled(string productId, Guid transactionId)
{
    return grantedConsumableTransactionIds.ContainsKey(productId) &&
        grantedConsumableTransactionIds[productId].Contains(transactionId);
}

Etapa 3: Comunicando o atendimento do produto à Windows Store

Concluído o atendimento local, o app deve fazer uma chamada a ReportConsumableFulfillmentAsync que inclua a productId e a transação na qual a compra do produto está incluída.

Importante

A falha em gerar relatórios de produtos no aplicativo consumíveis atendidos para a Loja fará com que o usuário não possa comprar o produto novamente enquanto o atendimento da compra anterior não for relatado.

FulfillmentResult result = await CurrentAppSimulator.ReportConsumableFulfillmentAsync(
    "product2", product2TempTransactionId);

Etapa 4: Identificando compras não atendidas

Seu app pode usar o método GetUnfulfilledConsumablesAsync para verificar a qualquer momento se há produtos consumíveis não atendidos no aplicativo. Esse método deve ser chamado regularmente para verificar se existem consumíveis não atendidos devido a eventos de aplicativo não previstos, como uma interrupção na conectividade de rede ou encerramento do aplicativo.

O exemplo a seguir demonstra como GetUnfulfilledConsumablesAsync pode ser usado para enumerar consumíveis não atendidos e como o seu app pode iterar por essa lista para concluir o atendimento local.

private async void GetUnfulfilledConsumables()
{
    products = await CurrentApp.GetUnfulfilledConsumablesAsync();

    foreach (UnfulfilledConsumable product in products)
    {
        logMessage += "\nProduct Id: " + product.ProductId + " Transaction Id: " + product.TransactionId;
        // This is where you would pass the product ID and transaction ID to
        // currentAppSimulator.reportConsumableFulfillment to indicate local fulfillment to the Windows Store.
    }
}