Habilitar compras de adicionais consumíveis

Este artigo demonstra como usar métodos da classe StoreContext no namespace Windows.Services.Store para gerenciar o cumprimento dos complementos consumíveis do usuário em seus aplicativos UWP. Use complementos consumíveis para itens que podem ser comprados, usados e comprados novamente. Isso é especialmente útil para coisas como moeda no jogo (ouro, moedas etc.) que podem ser compradas e usadas para comprar power-ups específicas.

Visão geral dos complementos consumíveis

Os aplicativos podem oferecer dois tipos de complementos consumíveis que diferem na maneira como as realizações são gerenciadas:

• Consumível gerenciado pelo desenvolvedor. Para esse tipo de consumível, você é responsável por manter o controle do saldo de itens do usuário que o suplemento representa e por informar à Loja que a compra do suplemento foi concluída após o usuário consumir todos os itens. O usuário não pode comprar o complemento novamente até que seu aplicativo tenha relatado a compra do complemento anterior conforme atendido.

  Por exemplo, se o complemento representar 100 moedas em um jogo e o usuário consumir 10 moedas, seu aplicativo ou serviço deverá manter o novo saldo restante de 90 moedas para o usuário. Depois que o usuário tiver consumido todas as 100 moedas, seu aplicativo deverá relatar o complemento conforme atendido e, em seguida, o usuário poderá comprar o complemento de 100 moedas novamente.

• Consumível gerenciado pela loja. Para esse tipo de consumível, a Loja mantém o controle do saldo de itens do usuário que o complemento representa. Quando o usuário consome todos os itens, você é responsável por relatar esses itens conforme atendido na Loja e a Loja atualiza o saldo do usuário. O usuário pode comprar o complemento quantas vezes quiser (ele não precisa consumir os itens primeiro). Seu aplicativo pode consultar a Loja para obter o saldo atual para o usuário a qualquer momento.

  Por exemplo, se o complemento representar uma quantidade inicial de 100 moedas em um jogo e o usuário consumir 50 moedas, seu aplicativo informará à Store que 50 unidades do complemento foram atendidas e a Loja atualizará o saldo restante. Se o usuário então recomprar seu add-on para adquirir mais 100 moedas, ele agora terá 150 moedas no total.

  Observação

  Os consumíveis gerenciados pela loja foram introduzidos no Windows 10, versão 1607.

Para oferecer um complemento consumível a um usuário, siga este processo geral:

1. Permitam que os usuários comprem o complemento do seu aplicativo.
2. Quando o usuário consome o complemento (por exemplo, ele gasta moedas dentro de um jogo), relatar o complemento como concluído.

A qualquer momento, você também pode obter o saldo restante para um consumível gerenciado pela loja.

Pré-requisitos

Estes exemplos têm os seguintes pré-requisitos:

• Um projeto do Visual Studio para um aplicativo UWP (Plataforma Universal do Windows) destinado ao Windows 10 Anniversary Edition (10.0; Build 14393) ou a uma versão posterior.
• Você criou uma submissão de aplicativo no Partner Center, e este aplicativo está publicado na Microsoft Store. Opcionalmente, você pode configurar o aplicativo para que ele não seja detectável na Loja enquanto você o testa. Para mais informações, consulte as diretrizes de teste .
• Você criou um complemento consumível para o aplicativo no Partner Center.

O código nestes exemplos pressupõe:

• O código é executado no contexto de uma página que contém um ProgressRing chamado workingProgressRing e um TextBlock chamado textBlock. Esses objetos são usados para indicar que uma operação assíncrona está ocorrendo e exibir mensagens de saída, respectivamente.
• O arquivo de código contém uma instrução usando para o namespace Windows.Services.Store.
• O aplicativo é um aplicativo de usuário único que é executado somente no contexto do usuário que iniciou o aplicativo. Para obter mais informações, consulte compras e avaliações no aplicativo.

Para obter um aplicativo de exemplo completo, consulte o exemploda Store.

Relatar um complemento consumível conforme atendido

Depois que o usuário compra o complemento do seu aplicativo e consome o complemento, seu aplicativo deve relatar o complemento conforme atendido chamando o método ReportConsumableFulfillmentAsync da classe StoreContext. Você deve passar as seguintes informações para este método:

• O ID da loja do complemento que você deseja relatar como atendido.
• As unidades do complemento que você deseja informar como atendidas.
  • Para um consumível gerenciado por desenvolvedor, especifique 1 para o parâmetro de quantidade . Isso alerta a Loja de que o produto consumível foi satisfeito, e o cliente pode comprar o produto consumível novamente. O usuário não poderá comprar o consumível novamente até que seu aplicativo tenha notificado a Loja de que ele foi atendido.
  • Para um consumível gerenciado pela Store, especifique o número real de unidades que foram consumidas. A loja atualizará o saldo remanescente do consumível.
• A ID de acompanhamento para o cumprimento. Esse é um GUID fornecido pelo desenvolvedor que identifica a transação específica à qual a operação de cumprimento está associada para fins de acompanhamento. Para obter mais informações, consulte as observações em ReportConsumableFulfillmentAsync.

Este exemplo demonstra como informar um consumível gerenciado pela Loja como atendido.

private StoreContext context = null;

public async void ConsumeAddOn(string addOnStoreId)
{
    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.
    }

    // This is an example for a Store-managed consumable, where you specify the actual number
    // of units that you want to report as consumed so the Store can update the remaining
    // balance. For a developer-managed consumable where you maintain the balance, specify 1
    // to just report the add-on as fulfilled to the Store.
    uint quantity = 10;
    Guid trackingId = Guid.NewGuid();

    workingProgressRing.IsActive = true;
    StoreConsumableResult result = await context.ReportConsumableFulfillmentAsync(
        addOnStoreId, quantity, trackingId);
    workingProgressRing.IsActive = false;

    // 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 StoreConsumableStatus.Succeeded:
            textBlock.Text = "The fulfillment was successful. " + 
                $"Remaining balance: {result.BalanceRemaining}";
            break;

        case StoreConsumableStatus.InsufficentQuantity:
            textBlock.Text = "The fulfillment was unsuccessful because the remaining " +
                $"balance is insufficient. Remaining balance: {result.BalanceRemaining}";
            break;

        case StoreConsumableStatus.NetworkError:
            textBlock.Text = "The fulfillment was unsuccessful due to a network error. " +
                "ExtendedError: " + extendedError;
            break;

        case StoreConsumableStatus.ServerError:
            textBlock.Text = "The fulfillment was unsuccessful due to a server error. " +
                "ExtendedError: " + extendedError;
            break;

        default:
            textBlock.Text = "The fulfillment was unsuccessful due to an unknown error. " +
                "ExtendedError: " + extendedError;
            break;
    }
}

Obter o saldo restante para um consumível gerenciado pela Store

Este exemplo demonstra como usar o método GetConsumableBalanceRemainingAsync da classe StoreContext para obter o saldo restante de um complemento consumível gerenciado pela Store.

private StoreContext context = null;

public async void GetRemainingBalance(string addOnStoreId)
{
    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.
    }

    workingProgressRing.IsActive = true;
    StoreConsumableResult result = await context.GetConsumableBalanceRemainingAsync(addOnStoreId);
    workingProgressRing.IsActive = false;

    // 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 StoreConsumableStatus.Succeeded:
            textBlock.Text = "Remaining balance: " + result.BalanceRemaining;
            break;

        case StoreConsumableStatus.NetworkError:
            textBlock.Text = "Could not retrieve balance due to a network error. " +
                "ExtendedError: " + extendedError;
            break;

        case StoreConsumableStatus.ServerError:
            textBlock.Text = "Could not retrieve balance due to a server error. " +
                "ExtendedError: " + extendedError;
            break;

        default:
            textBlock.Text = "Could not retrieve balance due to an unknown error. " +
                "ExtendedError: " + extendedError;
            break;
    }
}

Tópicos relacionados

• Compras e testes dentro do aplicativo
• Obter informações do produto para aplicativos e complementos
• Obter informações de licença para aplicativos e complementos
• Habilitar compras no aplicativo e aquisição de complementos
• Implementar uma versão de avaliação do aplicativo
• Amostra de loja