Assinatura com complementos

Com uma assinatura com complementos, você pode agrupar vários produtos por assinatura que podem ser comprados, faturados e gerenciados juntos. As assinaturas do catálogo de produtos podem ser oferecidas como complementos sem especificação inicial ou configuração adicional. Você pode iniciar um fluxo de compra com vários produtos por assinatura e vendê-los como complementos.

Considerações

Considere os seguintes pontos ao usar o recurso de assinatura com complementos:

• A assinatura com complementos só é compatível com planos básicos de renovação automática.

• Todos os itens na compra precisam ter o mesmo período de faturamento recorrente. Por exemplo, não é possível ter uma assinatura com cobrança anual e complementos com cobrança mensal.

• É possível ter no máximo 50 itens em uma assinatura com compra de complementos.

• Esse recurso não está disponível nas regiões da Índia (IN) e da Coreia do Sul (KR).

Integrar com a Biblioteca Play Faturamento

Esta seção descreve como integrar o recurso de assinatura com complementos à Biblioteca Google Play Faturamento (PBL). Ele pressupõe que você conheça as etapas iniciais de integração do PBL, como adicionar a dependência do PBL ao seu app, inicializar o BillingClient e conectar ao Google Play. Esta seção se concentra nos aspectos da integração do PBL específicos para assinaturas com complementos.

Iniciar um fluxo de compra

Para iniciar um fluxo de compra de uma assinatura com complementos, siga estas etapas:

1. Extraia todos os itens de assinatura usando o método BillingClient.queryProductDetailsAsync.

2. Defina o objeto ProductDetailsParams para cada item.

   O item representado pelo objeto ProductDetailsParams especifica o ProductDetails, que indica o item de assinatura, e um offerToken, que seleciona uma base plan ou offer específica.

3. Especifique os detalhes do item no método BillingFlowParams.Builder.setProductDetailsParamsList. A classe BillingFlowParams especifica os detalhes de um fluxo de compra.

   O exemplo a seguir mostra como iniciar o fluxo de faturamento para uma compra de assinatura com vários itens:

   Java

      BillingClient billingClient = …;
   
       // ProductDetails obtained from queryProductDetailsAsync().
       ProductDetailsParams productDetails1 = ...;
       ProductDetailsParams productDetails2 = ...;
       ArrayList productDetailsList = new ArrayList<>();
       productDetailsList.add(productDetails1);
       productDetailsList.add(productDetails2);
   
       BillingFlowParams billingFlowParams =
           BillingFlowParams.newBuilder()
              .setProductDetailsParamsList(productDetailsList)
              .build();
       billingClient.launchBillingFlow(billingFlowParams);

Regras aplicáveis a itens na compra

• Para garantir que as datas de renovação do complemento se alinhem ao item principal, o Google Play pode inserir uma cobrança proporcional após qualquer período de teste ou de preço inicial.
• A qualificação para a oferta será avaliada separadamente para cada item.

Processar compras

O processamento de assinaturas com complementos é igual ao de compras de um único item, conforme descrito em Integrar a Biblioteca Google Play Faturamento ao app. A única diferença é que o usuário pode receber vários direitos com uma única compra. Uma compra de assinatura com complementos retorna vários itens que podem ser recuperados usando Purchase.getProducts() na Biblioteca Google Play Faturamento e, em seguida, a lista lineItems em purchases.subscriptionsv2.get da API Google Play Developer.

Modificar assinaturas com complementos

Qualquer mudança na sua assinatura com complementos resulta em um upgrade ou um downgrade. Para mais informações, consulte fazer upgrade ou downgrade de assinaturas.

Para mudar ou restaurar uma compra de assinatura com complementos no seu app, chame a API launchBillingFlow com outros parâmetros e verifique se o seguinte está correto:

• Sempre chame setOldPurchaseToken com o token de compra da compra de assinatura atual.
• Para fazer upgrade, downgrade ou crossgrade de um item, chame SubscriptionProductReplacementParams.setReplacementMode para especificar como a mudança de plano deve ser processada entre o item de compra antigo e o novo. Caso contrário, não é necessário definir esse parâmetro.
• Quando o item de base não é alterado, ainda é possível chamar SubscriptionProductReplacementParams.setSubscriptionReplacementMode para aplicar um comportamento de substituição específico. Para conferir as regras aplicáveis neste caso, consulte Renovar assinatura ou mudar de plano na mesma assinatura.
• Os novos complementos serão aplicados imediatamente com uma cobrança proporcional para alinhar a próxima data de renovação com o item básico na assinatura.
• Os complementos removidos vão expirar no fim dos períodos de faturamento atuais.
• Ao iniciar o fluxo de faturamento, você precisa especificar todos os itens ativos na assinatura com complementos, exceto aqueles que serão removidos, além de novos complementos.

O exemplo a seguir mostra como chamar a API launchBillingFlow ao mudar uma compra de assinatura com complementos:

BillingClient billingClient = …;

int replacementMode =…;

// ProductDetails obtained from queryProductDetailsAsync().
ProductDetailsParams productDetails1 = ...;
ProductDetailsParams productDetails2 = ...;
ProductDetailsParams productDetails3 = ...;

ArrayList newProductDetailsList = new ArrayList<>();
newProductDetailsList.add(productDetails1);
newProductDetailsList.add(productDetails1);
newProductDetailsList.add(productDetails1);

BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setSubscriptionUpdateParams(
          SubscriptionUpdateParams.newBuilder()
              .setOldPurchaseToken(purchaseTokenOfExistingSubscription)
              // No need to set if change does not affect the base item.
             .setSubscriptionReplacementMode(replacementMode)
             .build())
        .setProductDetailsParamsList(productDetailsList)
        .build();

billingClient.launchBillingFlow(billingFlowParams);

Cenários de modificação de assinatura

A tabela a seguir lista os vários cenários de modificação para assinaturas com complementos e o comportamento correspondente.

Ao usar SubscriptionProductReplacementParams

Ao usar SubscriptionUpdateParams

Notificações do desenvolvedor em tempo real

O campo subscriptionId não é fornecido no RTDN para compras de assinaturas com complementos, que contêm vários direitos de itens. Em vez disso, use as APIs Play Developer para receber a compra e ver os direitos associados ao item.

Mudanças no preço de assinaturas existentes

Mudar os preços de assinaturas com compra de complementos para assinantes atuais é semelhante a mudar os preços de assinaturas de item único, conforme descrito em Mudar os preços de assinaturas. No entanto, há algumas limitações e diferenças funcionais, conforme descrito nesta seção.

Encerrar uma coorte de preço legada

Encerrar uma coorte legada também afeta as assinaturas com compras de complementos. Aplicam-se as seguintes regras:

• Todos os aumentos de preço pendentes precisam ter o mesmo período de renovação com o novo preço. Se um item em uma assinatura com compra de complementos tiver um aumento de preço opcional que ainda não foi confirmado pelo usuário, qualquer novo aumento de preço opcional para outros itens na compra será ignorado, a menos que resulte no mesmo tempo de renovação da aplicação do novo preço que o aumento de preço atual no estado PENDENTE. Depois que o usuário confirmar o aumento de preço, as mudanças mais recentes serão registradas. Além disso, os usuários só podem aceitar todos os aumentos de preço com permissão não confirmados de uma só vez.

  Exemplo:

  • Considere uma assinatura com complementos (itens A e B) que é renovada no dia 7 de cada mês.
  • O item A está passando por uma migração de preço de US $7 para US $10, e o aumento deve ser aplicado em 7 de julho.
  • Uma nova migração de preço de US $5 para US $6 começa para o item B em 2 de junho. Como o aumento de preço com opção de ativação começa 37 dias após a migração, o primeiro aumento de preço do item B será em 7 de agosto.

  Nesse cenário, até que o usuário aceite a mudança de preço do item A (até que ele esteja no estado CONFIRMADO), a mudança de preço do item B não será registrada para essa compra de assinatura, e SubscriptionPurchaseV2 não vai retornar detalhes da mudança de preço do item B. Depois que o usuário confirmar a mudança de preço do item A, a mudança de preço do item B vai começar. O usuário recebe o aumento de preço de aceitação do item B somente depois de aceitar o aumento de aceitação do item A.

• O e-mail do Google Play contém uma lista de todos os itens com aumentos ou reduções de preço que entram em vigor no mesmo dia.

Cancelar assinatura com complementos

Os usuários podem cancelar toda a compra de uma assinatura com complementos na central de assinaturas do Google Play, e você só pode cancelar toda a compra de uma assinatura com complementos usando a API Google Play Developer.

Quando uma compra de assinatura é cancelada sem ser revogada, nenhum dos itens na compra é renovado automaticamente, mas o usuário continua tendo acesso aos itens qualificados até o fim dos períodos de faturamento correspondentes.

Revogar e reembolsar assinaturas com complementos

Confira algumas diretrizes para revogar e reembolsar assinaturas:

• Use o Play Console para emitir um reembolso com base em um valor para um pedido específico sem revogar o acesso à assinatura.

• Chame orders.refund para reembolsar totalmente pagamentos de assinatura específicos que o usuário fez sem revogar o acesso à assinatura.

• Ligue para purchases.subscriptionsv2.revoke para revogar imediatamente o acesso a todos os itens da assinatura. Com essa API, você pode:

  • Revogar o acesso a todos os itens e oferecer um reembolso proporcional.

  • Ao revogar uma assinatura com complementos usando reembolsos proporcionais, um reembolso será emitido para o pedido mais recente de cada item com um valor proporcional com base no tempo restante até a próxima renovação.

  • Revogue o acesso a todos os itens e ofereça um FullRefund.

  • Revogar o acesso de um item específico com reembolso total do item.

Revogar um item individual em uma assinatura com complementos

Para revogar itens individuais de uma assinatura com complementos sem revogar toda a compra, chame purchases.subscriptionsv2.revoke com o campo ItemBasedRefund definido no RevocationContext. O productId do item que precisa ser revogado e reembolsado pode ser definido no campo ItemBasedRefund.

O campo ItemBasedRefund pode ser definido para compras com um ou mais itens de assinatura com renovação automática.

• Se ainda houver itens ativos na compra da assinatura após a revogação do item especificado em ItemBasedRefund, apenas o item será revogado e totalmente reembolsado sem interromper o status da assinatura.
• Se não houver itens ativos restantes na compra da assinatura após revogar o item especificado em ItemBasedRefund, o item será revogado, totalmente reembolsado e a assinatura será cancelada.

Considerações

• Ao usar o ItemBasedRefund, apenas um item pode ser revogado por vez. A solicitação pode ser chamada várias vezes se diferentes itens precisarem ser revogados.
• Quando a compra por assinatura está em qualquer um dos estados de pagamento recusado ou o item especificado em ItemBasedRefund não é de propriedade ou expirou, a recusa do item é bloqueada.
• Não é possível reduzir o número de itens em uma assinatura pré-paga.

Validade do item durante uma recusa de pagamento

Para uma compra de assinatura com complementos, algumas renovações podem precisar apenas estender um subconjunto de direitos de itens, sem afetar itens com uma data de expiração futura.

Independente de quais itens estão envolvidos em uma renovação, se o pagamento for recusado, a compra geral da assinatura vai entrar em período de carência e retenção de conta, conforme descrito na documentação a seguir.

Seleção do período de recuperação

Como o período de carência ainda concede o direito ao usuário, após uma compra de assinatura com complementos, o pagamento de renovação é recusado, o item com o período de carência mínimo em todos os itens ativos é selecionado, e o período de carência e de suspensão de conta como o período de recuperação é aplicado a essa renovação.

Os itens ativos incluem aqueles que estavam ativos na compra de uma assinatura com complementos pouco antes da tentativa de renovação, excluem itens recém-adicionados (que não terão direito até depois da recuperação) e excluem itens que não estão mais ativos devido à remoção ou desativação.

A configuração de suspensão de conta do item com o período de carência mínima selecionado é aplicada. Se houver mais de um item com o período de carência mínima, mas períodos de suspensão de conta diferentes, o mais longo será aplicado.

Período de carência

Quando um pagamento de renovação de assinatura é recusado, a compra da assinatura entra em período de carência. Durante o período de carência, o usuário continua tendo acesso a todos os itens ativos do período de renovação anterior. Após o período de carência, se a forma de pagamento não for corrigida, toda a compra da assinatura será suspensa. Se outros itens atingirem a data de renovação durante o período de carência, uma nova tentativa de cobrança será iniciada para esses itens assim que a assinatura for recuperada da recusa de pagamento.

Suspensão de conta

Enquanto a compra da assinatura estiver em suspensão de conta, o acesso a todos os itens da assinatura será suspenso até que o pagamento seja recuperado.

Se a assinatura em suspensão de conta for recuperada, a compra vai continuar existindo. Se a assinatura não for recuperada, os itens em pagamento recusado vão expirar, e o acesso aos outros itens será retomado pelo restante dos períodos de faturamento.

Exemplo:

• Um usuário tem uma assinatura do Meu plano básico com renovação no dia 1º de todo mês. Em 15 de agosto, ele adiciona um plano complementar de US $10 por mês com um teste sem custo financeiro de sete dias. Nenhum dos itens tem um período de carência definido, e ambos têm um período de suspensão da conta de 30 dias.

• Em 22 de agosto, o usuário recebe uma cobrança de US $2,90 (10*9/31) para o período até 31 de agosto, mas a forma de pagamento expira antes disso, e a assinatura é recusada em 22 de agosto.

Quando a assinatura entra em suspensão de conta devido à recusa de pagamento, o usuário não tem acesso a nenhum dos itens da assinatura com complementos. O tempo restante dos itens que não serão renovados será devolvido aos usuários quando a assinatura sair da suspensão de conta, seja porque o pagamento foi recuperado ou cancelado.

No exemplo anterior, uma assinatura entra em suspensão de conta em 22 de agosto.

• Se a conta for recuperada em 25 de agosto, antes da data de renovação mais ampla, em 1º de setembro, o usuário vai recuperar o acesso ao Base Plan e ao plano complementar no mesmo dia. A próxima data de faturamento foi alterada para 4 de setembro.

• Se a conta não for recuperada após 30 dias, a assinatura será cancelada em 21 de setembro, e o usuário perderá o acesso ao Plano complementar. Ele poderá retomar o acesso ao Meu plano básico até 30 de setembro.

Neste exemplo, você precisa receber o expiryTime atualizado para TODOS os itens na assinatura com complementos, já que alguns itens podem retomar o direito após o período de carência e a suspensão da conta.

Relatórios e conciliação financeira

Use o Relatório de ganhos para conciliar suas assinaturas ativas com transações no Google Play. Cada item de linha de transação tem um ID de pedido. Como as compras representam vários itens, os relatórios de ganhos e vendas estimadas incluem linhas separadas para cada transação, como cobrança, taxa, tributo e reembolso, para cada item envolvido.

Para painéis no Play Console:

• As estatísticas de receita apresentadas na seção Relatórios financeiros do console são divididas por itens.

• O gerenciamento de pedidos reflete a compra de uma assinatura com complementos e mostra listas detalhadas do que foi comprado. No gerenciamento de pedidos, você pode revogar, cancelar ou reembolsar totalmente a compra de um usuário.