Habilitar compras de produto no aplicativo consumível (HTML)

Artigo
12/12/2015

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

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

O que você precisa saber

Tecnologias

Windows Runtime
Windows.ApplicationModel.Store

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, use 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 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 aplicativo pela primeira vez, mas também é possível carregar um arquivo personalizado no tempo de execução. Para saber mais, consulte a documentação do CurrentAppSimulator.
Este tópico também faz referência a exemplos de código fornecidos no Exemplo de aplicativo de avaliação e de compra no aplicativo disponível na Galeria de Códigos do MSDN. Este exemplo é uma ótima maneira de obter experiência prática com as diferentes opções de monetização fornecidas para os aplicativos da Windows Store.

Instruções

Etapa 1: Fazendo a solicitação de compra

A solicitação de compra inicial é feita com o RequestProductPurchaseAsync como com qualquer outra compra feita pela Loja. A diferença no caso dos produtos no aplicativo consumíveis é 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 aplicativo deve conduzir seu atendimento local do produto no aplicativo consumível para dois cenários diferentes — quando a solicitação de compra é bem-sucedida, e quando a solicitação de compra não é bem-sucedida devido a uma compra não atendida do mesmo produto.


function purchaseProduct1() {
    CurrentAppSimulator.requestProductPurchaseAsync("product1").done(
        function (purchaseResults) {
            if (purchaseResults.status === ProductPurchaseStatus.succeeded) {
                tempTransactionId["product1"] = purchaseResults.transactionId;

        // Grant the user their purchase here, and then pass the product ID and transaction ID to currentApp.reportConsumableFulfillment
        // To indicate local fulfillment to the Windows Store.

            } else if (purchaseResults.status === ProductPurchaseStatus.notFulfilled) {
                tempTransactionId["product1"] = 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 currentApp.reportConsumableFulfillment
        // To indicate local fulfillment to the Windows Store.
            }
        }
    );
}

Etapa 2: Rastreando atendimento local do consumível

Ao conceder o acesso para o seu cliente ao produto no aplicativo consumível, é importante manter o controle de qual produto é atendido (productId) e com 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 seus clientes.

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

function grantFeatureLocally(productId, transactionId) {
    var nextIndex = grantedIds[productId].length;
    grantedIds[productId][nextIndex] = transactionId;

    // Grant the user the content, such as by increasing some kind of 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, são usados para comunicar o atendimento à Windows Store.

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.

function isLocallyFulfilled(productId, transactionId) {
    for (var i in grantedIds[productId]) {
        if (grantedIds[productId][i] === transactionId) {
            return true;
        }
    }
    return false;
}

Etapa 3: Gerando relatórios para o atendimento do produto junto à Windows Store

Depois que o atendimento local for concluído, o aplicativo deverá fazer uma chamada ReportConsumableFulfillmentAsync que inclui 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.


var result = FulfillmentResult; 
result = CurrentAppSimulator.reportConsumableFulfillmentAsync("product1", tempTransactionId["product1"]);

Etapa 4: Identificando compras não atendidas

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

O exemplo a seguir demonstra como o GetUnfulfilledConsumablesAsync pode ser usado para enumerar consumíveis não atendidos e como o aplicativo pode iterar através dessa lista para concluir o atendimento local.

CurrentAppSimulator.getUnfulfilledConsumablesAsync().done(
function (unfulfilledList) {

    unfulfilledList.forEach(function (product) {
        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.
    });
});

Tópicos relacionados

Habilitar compras de produto no aplicativo

Exemplo de aplicativo de avaliação e de compra no próprio aplicativo

Windows.ApplicationModel.Store