Habilitar complementos de assinatura para o aplicativo

  • Artigo

O aplicativo UWP pode oferecer compras no aplicativo de complementos de assinatura para seus clientes. Você pode usar assinaturas para vender produtos digitais em seu app (como os recursos do app ou conteúdo digital) com períodos de cobrança recorrentes automatizados.

Observação

Para habilitar a compra de complementos de assinatura no aplicativo, o projeto deve ser direcionada para o 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), e ele deve usar as APIs no namespace Windows.Services.Store para implementar a experiência de compra realizada em aplicativo, em vez do namespace ApplicationModel. Para obter mais informações sobre as diferenças entre esses namespaces, consulte Compras no aplicativo e avaliações.

Destaques do recurso

Os complementos de assinatura para aplicativos UWP dão suporte aos seguintes recursos:

  • Você pode escolher entre períodos de assinatura de um mês, três meses, seis meses, um ano ou dois anos.
  • Você pode adicionar períodos de avaliação gratuita de uma semana ou de um mês à sua assinatura.
  • O SDK do Windows fornece APIs que você pode usar em seu app para obter informações sobre os complementos de assinatura disponíveis para o aplicativo e habilitar a compra de um complemento de assinatura. Também fornecemos APIs REST que você pode chamar dos seus serviços para gerenciar assinaturas para um usuário.
  • Você pode exibir relatórios analíticos que fornecem o número de aquisições de assinatura, os assinantes ativos e as assinaturas canceladas em um determinado período de tempo.
  • Os clientes podem gerenciar suas assinaturas na página https://account.microsoft.com/services da conta da Microsoft. Os clientes podem usar essa página para exibir todas as assinaturas que eles adquiriram, cancelar uma assinatura e alterar a forma de pagamento associada à sua assinatura.

Etapas para habilitar um complemento de assinatura para o app

Para habilitar a compra de complementos de assinatura em seu app, siga estas etapas.

  1. Crie um envio de complemento para sua assinatura no Partner Center e publique o envio. Conforme você segue o processo de envio de complemento, preste atenção às seguintes propriedades:

    • Tipo de produto: selecione Assinatura.

    • Período de assinatura: escolha o período de cobrança recorrente para sua assinatura. Você não poderá alterar o período de assinatura depois de publicar o complemento.

      Cada complemento de assinatura dá suporte a um único período de assinatura e período de avaliação. Você deve criar um complemento de assinatura diferente para cada tipo de assinatura que deseja oferecer em seu app. Por exemplo, se você quiser oferecer uma assinatura mensal sem avaliação, uma assinatura mensal com uma versão de avaliação de um mês, uma assinatura anual sem avaliação e uma assinatura anual com uma versão de avaliação de um mês, precisará criar quatro complementos de assinatura.

    • Período de avaliação: considere a escolha de um período de avaliação de uma semana ou de um mês para sua assinatura para permitir que os usuários experimentem o conteúdo da assinatura antes de comprá-la. Você não poderá alterar ou remover o período de assinatura depois de publicar o complemento da assinatura.

      Para adquirir uma avaliação gratuita de sua assinatura, um usuário precisará comprar sua assinatura por meio do processo padrão de compra no aplicativo, incluindo uma forma de pagamento válida. Eles não são cobrados durante o período de avaliação. No final do período de avaliação, a assinatura é automaticamente convertida na assinatura completa e o instrumento de pagamento do usuário será cobrado pelo primeiro período da assinatura paga. Se o usuário optar por cancelar sua assinatura durante o período de avaliação, a assinatura permanecerá ativa até o final do período de avaliação. Alguns períodos de avaliação não estão disponíveis para todos os períodos de assinatura.

      Observação

      Cada cliente pode adquirir uma avaliação gratuita para um complemento de assinatura somente uma vez. Depois que um cliente adquire uma avaliação gratuita de uma assinatura, a Store impede que o mesmo cliente adquira a mesma assinatura de avaliação gratuita novamente.

    • Visibilidade: se você estiver criando um complemento de teste que usará somente para testar a experiência de compra no aplicativo para a sua assinatura, nós recomendamos que você selecione uma das opções Oculto na Store. Caso contrário, você pode selecionar a melhor opção de visibilidade para seu cenário.

    • Preço: escolha o preço de sua assinatura nesta seção. Você não poderá elevar o preço da assinatura depois de publicar o complemento. No entanto, você poderá reduzir o preço mais tarde.

      Importante

      Por padrão, quando você criar qualquer complemento, o preço será inicialmente definido como Grátis. Como você não pode aumentar o preço de um complemento de assinatura depois de concluir o envio de complemento, escolha o preço de sua assinatura aqui.

  2. Em seu app, use as APIs no namespace Windows.Services.Store para determinar se o usuário atual já adquiriu o complemento de assinatura e então oferecê-lo para venda ao usuário como uma compra no aplicativo. Consulte os exemplos de código neste artigo para obter mais detalhes.

  3. Teste a implementação de compra no aplicativo de sua assinatura em seu app. Será necessário baixar seu app uma vez da Store para seu dispositivo de desenvolvimento para usar sua licença para teste. Para obter mais informações, consulte nossas diretrizes de teste para compras no aplicativo.

  4. Criar e publicar um envio de aplicativo que inclui o pacote do app atualizado, incluindo seu código testado. Para obter mais informações, consulte Envios de aplicativo.

Exemplos de código

Os exemplos de código nesta seção demonstram como usar as APIs no namespace Windows.Services.Store para obter informações sobre os complementos de assinatura para o app atual e solicitar a compra de um complemento de assinatura em nome do usuário atual.

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

  • Um projeto do Visual Studio para um aplicativo da Plataforma Universal do Windows (UWP) destinado ao Windows 10 Anniversary Edition (10.0; Build 14393) ou uma versão posterior.
  • Você criou um envio de aplicativo no Partner Center e esse aplicativo é publicado na Store. Opcionalmente, é possível configurar o app para que ele não possa ser descoberto na Store enquanto você o testa. Para obter mais informações, consulte diretrizes para teste.
  • Você criou um complemento de assinatura para o aplicativo no Partner Center.

O código nestes exemplos pressupõe que:

  • O arquivo de código tenha instruções using para Windows.Services.Store e namespaces System.Threading.Tasks.
  • O app seja um app de usuário único executado somente no contexto do usuário que o iniciou. Para obter mais informações, consulte Compras no aplicativo e avaliações.

Observação

Se você tiver um aplicativo da área de trabalho que utilize a Ponte de Desktop, talvez seja necessário adicionar outro código não mostrado nestes exemplos para configurar o objeto StoreContext. Para obter mais informações, consulte Usando a classe StoreContext em um aplicativo da área de trabalho que usa o Desktop Bridge.

Comprar um complemento de assinatura

Este exemplo demonstra como solicitar a compra de um complemento de assinatura conhecido para o seu app em nome do cliente atual. Este exemplo também mostra como tratar o caso em que a assinatura tem um período de avaliação.

  1. O código primeiro determina se o cliente já tem uma licença ativa da assinatura. Se o cliente já tiver uma licença ativa, seu código deverá desbloquear os recursos de assinatura conforme necessário (como isso é proprietário do seu app, é identificado com um comentário no exemplo).
  2. Em seguida, o código obtém o objeto StoreProduct que representa a assinatura que você deseja comprar em nome do cliente. O código presume que você já conheça a ID da Store do complemento da assinatura que deseja comprar e que você atribuiu esse valor à variável subscriptionStoreId.
  3. O código determina então se uma avaliação está disponível para a assinatura. Opcionalmente, seu aplicativo pode usar essas informações para exibir detalhes sobre a avaliação disponível ou a assinatura completa para o cliente.
  4. Por fim, o código chama o método RequestPurchaseAsync para solicitar a compra da assinatura. Se houver uma avaliação disponível para a assinatura, a avaliação será oferecida ao cliente para compra. Caso contrário, a assinatura completa será oferecida para compra.
private StoreContext context = null;
StoreProduct subscriptionStoreProduct;

// Assign this variable to the Store ID of your subscription add-on.
private string subscriptionStoreId = "";  

// This is the entry point method for the example.
public async Task SetupSubscriptionInfoAsync()
{
    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.
    }

    bool userOwnsSubscription = await CheckIfUserHasSubscriptionAsync();
    if (userOwnsSubscription)
    {
        // Unlock all the subscription add-on features here.
        return;
    }

    // Get the StoreProduct that represents the subscription add-on.
    subscriptionStoreProduct = await GetSubscriptionProductAsync();
    if (subscriptionStoreProduct == null)
    {
        return;
    }

    // Check if the first SKU is a trial and notify the customer that a trial is available.
    // If a trial is available, the Skus array will always have 2 purchasable SKUs and the
    // first one is the trial. Otherwise, this array will only have one SKU.
    StoreSku sku = subscriptionStoreProduct.Skus[0];
    if (sku.SubscriptionInfo.HasTrialPeriod)
    {
        // You can display the subscription trial info to the customer here. You can use 
        // sku.SubscriptionInfo.TrialPeriod and sku.SubscriptionInfo.TrialPeriodUnit 
        // to get the trial details.
    }
    else
    {
        // You can display the subscription purchase info to the customer here. You can use 
        // sku.SubscriptionInfo.BillingPeriod and sku.SubscriptionInfo.BillingPeriodUnit
        // to provide the renewal details.
    }

    // Prompt the customer to purchase the subscription.
    await PromptUserToPurchaseAsync();
}

private async Task<bool> CheckIfUserHasSubscriptionAsync()
{
    StoreAppLicense appLicense = await context.GetAppLicenseAsync();

    // Check if the customer has the rights to the subscription.
    foreach (var addOnLicense in appLicense.AddOnLicenses)
    {
        StoreLicense license = addOnLicense.Value;
        if (license.SkuStoreId.StartsWith(subscriptionStoreId))
        {
            if (license.IsActive)
            {
                // The expiration date is available in the license.ExpirationDate property.
                return true;
            }
        }
    }

    // The customer does not have a license to the subscription.
    return false;
}

private async Task<StoreProduct> GetSubscriptionProductAsync()
{
    // Load the sellable add-ons for this app and check if the trial is still 
    // available for this customer. If they previously acquired a trial they won't 
    // be able to get a trial again, and the StoreProduct.Skus property will 
    // only contain one SKU.
    StoreProductQueryResult result =
        await context.GetAssociatedStoreProductsAsync(new string[] { "Durable" });

    if (result.ExtendedError != null)
    {
        System.Diagnostics.Debug.WriteLine("Something went wrong while getting the add-ons. " +
            "ExtendedError:" + result.ExtendedError);
        return null;
    }

    // Look for the product that represents the subscription.
    foreach (var item in result.Products)
    {
        StoreProduct product = item.Value;
        if (product.StoreId == subscriptionStoreId)
        {
            return product;
        }
    }

    System.Diagnostics.Debug.WriteLine("The subscription was not found.");
    return null;
}

private async Task PromptUserToPurchaseAsync()
{
    // Request a purchase of the subscription product. If a trial is available it will be offered 
    // to the customer. Otherwise, the non-trial SKU will be offered.
    StorePurchaseResult result = await subscriptionStoreProduct.RequestPurchaseAsync();

    // 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 StorePurchaseStatus.Succeeded:
            // Show a UI to acknowledge that the customer has purchased your subscription 
            // and unlock the features of the subscription. 
            break;

        case StorePurchaseStatus.NotPurchased:
            System.Diagnostics.Debug.WriteLine("The purchase did not complete. " +
                "The customer may have cancelled the purchase. ExtendedError: " + extendedError);
            break;

        case StorePurchaseStatus.ServerError:
        case StorePurchaseStatus.NetworkError:
            System.Diagnostics.Debug.WriteLine("The purchase was unsuccessful due to a server or network error. " +
                "ExtendedError: " + extendedError);
            break;

        case StorePurchaseStatus.AlreadyPurchased:
            System.Diagnostics.Debug.WriteLine("The customer already owns this subscription." +
                    "ExtendedError: " + extendedError);
            break;
    }
}

Obter informações sobre complementos de assinatura para o app atual

Este exemplo de código demonstra como obter informações para todos os complementos de assinatura que estão disponíveis em seu app. Para obter essas informações, primeiro use o método GetAssociatedStoreProductsAsync para obter a coleção de objetos StoreProduct que representam cada um dos complementos disponíveis para o app. Em seguida, obtenha a StoreSku para cada produto e use as propriedades IsSubscription e SubscriptionInfo para acessar as informações da assinatura.

private StoreContext context = null;

public async Task GetSubscriptionsInfo()
{
    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.
    }

    // Subscription add-ons are Durable products.
    string[] productKinds = { "Durable" };
    List<String> filterList = new List<string>(productKinds);

    StoreProductQueryResult queryResult =
        await context.GetAssociatedStoreProductsAsync(productKinds);

    if (queryResult.ExtendedError != null)
    {
        // The user may be offline or there might be some other server failure.
        System.Diagnostics.Debug.WriteLine($"ExtendedError: {queryResult.ExtendedError.Message}");
        return;
    }

    foreach (KeyValuePair<string, StoreProduct> item in queryResult.Products)
    {
        // Access the Store product info for the add-on.
        StoreProduct product = item.Value;

        // For each add-on, the subscription info is available in the SKU objects in the add-on. 
        foreach (StoreSku sku in product.Skus)
        {
            if (sku.IsSubscription)
            {
                // Use the sku.SubscriptionInfo property to get info about the subscription. 
                // For example, the following code gets the units and duration of the 
                // subscription billing period.
                StoreDurationUnit billingPeriodUnit = sku.SubscriptionInfo.BillingPeriodUnit;
                uint billingPeriod = sku.SubscriptionInfo.BillingPeriod;
            }
        }
    }
}

Gerenciar assinaturas de seus serviços

Depois que seu app atualizado estiver na Store e os clientes puderem comprar seu complemento de assinatura, talvez haja cenários onde será necessário gerenciar a assinatura para um cliente. Nós fornecemos APIs REST que você pode chamar de seus serviços para realizar as seguintes tarefas de gerenciamento de assinatura:

Cancelamentos

Os clientes podem usar a página https://account.microsoft.com/services da conta da Microsoft para exibir todas as assinaturas que eles adquiriram, cancelar uma assinatura e alterar a forma de pagamento associada à assinatura. Quando um cliente cancela uma assinatura usando esta página, ele continuam a ter acesso à assinatura durante o período de cobrança atual. Ele não obtém reembolso de qualquer parte do período de cobrança atual. No final do período de cobrança atual, a assinatura é desativada.

Você também pode cancelar uma assinatura em nome de um usuário usando a API REST para alterar o estado de cobrança de uma assinatura para um determinado usuário.

Períodos de carência e renovações de assinatura

Em algum momento durante cada período de cobrança, tentaremos cobrar o cartão de crédito do cliente pelo próximo período de cobrança. Se a cobrança falhar, a assinatura do cliente entrará no estado de cobrança. Isso significa que suas assinaturas ainda estarão ativas pelo restante do período de cobrança atual, mas nós tentaremos periodicamente cobrar do cartão de crédito para renovarmos automaticamente a assinatura. Esse estado pode durar até duas semanas, até o final do período de cobrança e a data de renovação para o próximo período de cobrança atual.

Não oferecemos períodos de carência para cobrança de assinatura. Se não pudermos cobrar o cartão de crédito do cliente até o final do período de cobrança atual, a assinatura será cancelada e o cliente não terá mais acesso à assinatura após o período de cobrança atual.

Cenários sem suporte

No momento, os cenários a seguir não têm suporte para complementos de assinatura.

  • No momento, não há suporte para a venda de assinaturas para clientes diretamente por meio da Store. As assinaturas só estão disponíveis para compras no aplicativo de produtos digitais.
  • Os clientes não podem trocar de períodos de assinatura usando a página https://account.microsoft.com/services para a conta da Microsoft. Para mudar para um período de assinatura diferente, os clientes devem cancelar sua assinatura atual e, em seguida, comprar uma assinatura com um período de assinatura diferente do seu aplicativo.
  • No momento, a troca de camada não tem suporte para complementos de assinatura (por exemplo, alternar um cliente de uma assinatura básica para uma assinatura premium com mais recursos).
  • No momento, não há suporte a vendas e códigos promocionais para complementos de assinatura.
  • Renovação de assinaturas existentes depois de definir a visibilidade do complemento de sua assinatura como Parar aquisição. Confira Definir preço e disponibilidade do complemento para obter mais detalhes.