Assinatura com complementos

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

A assinatura com complementos permite agrupar vários produtos de assinatura que podem ser comprados, faturados e gerenciados juntos. Suas assinaturas do catálogo de produtos podem ser oferecidas como complementos sem nenhuma especificação antecipada ou configuração extra. É possível 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 com complementos com cobrança mensal.

• Você pode 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 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 app, inicializar o BillingClient e se conectar ao Google Play. Esta seção se concentra nos aspectos da integração do PBL específicos à assinatura com complementos.

Iniciar um fluxo de compra

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

1. Use o método BillingClient.queryProductDetailsAsync para buscar todos os itens de assinatura.

2. Defina o objeto ProductDetailsParams para cada item.

   O item representado pelo objeto ProductDetailsParams especifica o ProductDetails indicando o item de assinatura e um offerToken selecionando uma assinatura específica base plan ou offer.

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 de 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 aos itens da compra

• Para garantir que as datas de renovação de complementos sejam alinhadas ao item base, o Google Play pode inserir uma cobrança proporcional após as fases de preços de teste ou de introdução.
• A qualificação da oferta será avaliada separadamente para cada item.

Processar compras

O processamento de assinaturas com complementos é o mesmo que o 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 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 upgrade ou downgrade. Para mais informações, consulte fazer upgrade ou downgrade de assinaturas.

Para mudar ou restaurar uma compra de assinatura com complementos no app, chame a API launchBillingFlow com parâmetros adicionais e siga estas instruções:

• Chame setOldPurchaseToken sempre com o token de compra da assinatura atual.
• Para fazer upgrade, downgrade ou crossgrade do item básico, chame setSubscriptionReplacementMode para especificar como a mudança de plano deve ser gerenciada entre os itens básicos do antigo e o novo item da compra de assinatura com complementos. Caso contrário, não é preciso definir esse parâmetro.
• Quando o item base não é alterado, ainda é possível chamar setSubscriptionReplacementMode para aplicar um comportamento de rateio específico. Para saber quais regras se aplicam a esse 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 ao item básico da assinatura.
• Os complementos removidos vão expirar no final dos períodos de faturamento atuais.
• Ao iniciar o fluxo de faturamento, você precisa especificar todos os itens ativos na assinatura com complementos, excluindo 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 de assinatura com complementos e o comportamento correspondente.

Notificações do desenvolvedor em tempo real

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

Mudanças no preço de assinaturas existentes

Mudar os preços de assinaturas para assinantes de uma assinatura com compra de complementos é semelhante a mudar os preços de assinaturas de um único item, 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

O encerramento de uma coorte legada também afeta a assinatura com compras de complementos. As seguintes regras se aplicam:

• Todos os aumentos de preço em vigor precisam ter o mesmo período de renovação com o novo preço. Se um item de uma assinatura com compra de complementos tiver um aumento de preço de aceitação que ainda não foi confirmado pelo usuário, qualquer novo aumento de preço de aceitação 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 OUTSTANDING. Depois que o usuário confirmar o aumento de preço, as mudanças mais recentes serão registradas. E os usuários só podem aceitar todos os aumentos de preço de ativação não confirmados de uma vez.

  Exemplo:

  • Considere uma assinatura com complementos (itens A e B), que é renovada no dia 7 de cada mês.
  • O item A está em migração de preço de US $7 para US $10, e o aumento de preço deve ser aplicado em 7 de julho.
  • Uma nova migração de preço de US $5 para US $6 começa no item B em 2 de junho. Como o aumento de preço com permissão começa 37 dias após a migração, o aumento de preço mais cedo para o 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 CONFIRMED), a mudança de preço do item B não será registrada para essa compra de assinatura, e a SubscriptionPurchaseV2 não vai retornar os detalhes da mudança de preço do item B. Depois que o usuário confirma a mudança de preço do item A, a mudança de preço do item B começa. O usuário recebe o aumento de preço do item B apenas depois de aceitar o aumento de preç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 a compra de uma assinatura com complementos na Central de assinaturas do Google Play. Você só pode cancelar 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 a ter acesso aos itens qualificados até o fim dos períodos de faturamento correspondentes.

Revogar e reembolsar assinaturas com complementos

Confira a seguir algumas diretrizes para revogar e reembolsar as assinaturas:

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

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

• Chame purchases.subscriptionsv2.revoke para revogar imediatamente o acesso a todos os itens de 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 faça um reembolso total.

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

Revogar um item individual em uma assinatura com complementos

Para revogar itens de assinatura individuais em uma assinatura com complementos sem revogar a compra inteira, 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 na compra da assinatura após a revogação do 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 da assinatura está em qualquer um dos estados de pagamento recusado ou o item especificado em ItemBasedRefund não é de propriedade ou está expirado, a recusa do item é bloqueada.
• A recusa de itens não é compatível com a assinatura pré-paga.

Item expirado durante a recusa do pagamento

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

Independentemente dos itens envolvidos em uma renovação, se o pagamento da renovação for rejeitado, a compra da assinatura vai entrar no período de carência e a conta será retida, 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 de acesso 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 sobre todos os itens ativos é selecionado, e o período de carência e o período de suspensão da conta como o período de recuperação é aplicado para essa renovação.

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

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

Período de carência

Quando um pagamento de renovação de assinatura é recusado, a compra da assinatura entra no estado de período de carência. Durante o período de carência, o usuário vai continuar a ter 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 chegarem à 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 se recuperar da recusa de pagamento.

Suspensão de conta

Enquanto a compra da assinatura estiver em suspensão, 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 da assinatura 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 resto dos períodos de faturamento.

Exemplo:

• Um usuário tem uma assinatura My Base Plan que é renovada no dia 1º de cada mês. Em 15 de agosto, ele adiciona um Add-on plan 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 de conta de 30 dias.

• Em 22 de agosto, o usuário é cobrado em US $2,90 (10*9/31) para ser rateado até 31 de agosto, mas a forma de pagamento do usuário 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 estão sendo renovados será devolvido aos usuários quando a assinatura sair da suspensão, porque o pagamento foi recuperado ou cancelado.

No exemplo anterior, uma assinatura entra na 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 Meu Base Plan e 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 e vai retomar o acesso ao Meu plano básico até 30 de setembro.

Neste exemplo, é necessário 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 financeiros e reconciliação

Use o Relatório de ganhos para reconciliar suas assinaturas ativas com as transações no Google Play. Cada item de linha de transação tem um código de pedido. Com compras que representam vários itens, os relatórios de lucros e vendas estimadas vão incluir linhas separadas para cada transação, como cobrança, taxa, imposto 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 assinaturas com complementos e mostra listas detalhadas do que foi comprado. No gerenciamento de pedidos, é possível revogar, cancelar ou reembolsar totalmente a compra de um usuário.