Ciclo de vida da assinatura

As compras de assinaturas podem passar por vários estados diferentes durante o ciclo de vida. Isso depende de muitos fatores, incluindo comportamento de renovação automática, situações de pagamento recusado e ações de gerenciamento do desenvolvedor.

Processar o ciclo de vida das assinaturas de renovação automática

Quando o estado de assinatura de um usuário muda, o servidor de back-end recebe uma mensagem SubscriptionNotification.

Figura 1. Estados de ciclo de vida e eventos de transição para compras de assinaturas de renovação automática.

Para atualizar o estado no back-end, chame a API purchases.subscriptionsv2.get com o token de compra incluído na notificação. Esse endpoint fornece o estado mais recente da assinatura considerando um token de compra e é tido como a fonte da verdade para o gerenciamento de assinaturas.

Observação: o token de compra é válido até 60 dias após a data de validade das assinaturas. Após essa data, o token de compra não será mais válido para chamar a API Google Play Developer.

Novas compras de assinaturas de renovação automática

Quando um usuário compra uma assinatura, uma mensagem SubscriptionNotification com o tipo SUBSCRIPTION_PURCHASED é enviada ao cliente de RTDN. Independente de você receber essa notificação ou registrar uma nova compra no app com PurchasesUpdatedListener ou buscar compras manualmente no método onResume(), processe a nova compra no seu back-end seguro. Para isso, siga estas etapas:

  1. Consulte o endpoint purchases.subscriptionsv2.get para conferir um recurso de assinatura que contenha o estado mais recente.
  2. Confira se o valor do campo subscriptionState é SUBSCRIPTION_STATE_ACTIVE.
  3. Verifique a compra.
  4. Conceda ao usuário o acesso ao conteúdo. A conta de usuário associada à compra pode ser identificada com o objeto ExternalAccountIdentifiers do recurso de assinatura. Isso será possível se os identificadores tiverem sido definidos no momento da compra usando setObfuscatedAccountId e setObfuscatedProfileId.

A Biblioteca Play Faturamento também inclui um método para confirmar uma assinatura, acknowledgePurchase(), e um método para conferir o status de confirmação, isAcknowledged(). No entanto, recomendamos processar as compras no back-end para maior segurança.

O recurso de assinatura para novas compras é parecido com este exemplo:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  "startTime": "2022-04-22T18:39:58.270Z",
  "regionCode": "US",
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  "latestOrderId": "GPA.3333-4137-0319-36762",
  "acknowledgementState": "ACKNOWLEDGEMENT_STATE_PENDING", // need to acknowledge new purchases
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": next_renewal_date,
      "autoRenewingPlan": {
        "autoRenewEnabled": true
      }
    }
  ],
}

Renovações de assinaturas

Para assinaturas sem parcelamento e com renovação automática, um SUBSCRIPTION_RENEWED uma notificação será enviada quando a assinatura for renovada. Para parcelas inscrições, uma notificação SUBSCRIPTION_RENEWED é enviada sempre que o assinatura é cobrada na data de faturamento. Verifique se o usuário ainda está o titular da assinatura e, em seguida, atualizar o estado da assinatura com o novo expiryTime fornecido na assinatura recurso retornado do Google Play API Developer. O recurso de assinatura é parecido com este exemplo:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  "startTime": "2022-04-22T18:39:58.270Z",
  "regionCode": "US",
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  "latestOrderId": "GPA.3333-4137-0319-36762",
  "acknowledgementState": "ACKNOWLEDGEMENT_STATE_ACKNOWLEDGED",
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": next_renewal_date,
      "autoRenewingPlan": {
        "autoRenewEnabled": true
      }
    }
  ]
}

Não é necessário confirmar as renovações de assinatura.

Período de carência

Se houver problemas de pagamento com a renovação de uma assinatura, o Google notificará o e tenta renovar periodicamente a assinatura por algum tempo antes a assinatura expirar. Esse período de recuperação pode consistir em um período de carência seguido por um período de suspensão da conta. Durante esse período, o usuário precisa ainda terão acesso aos direitos da assinatura.

O método queryPurchasesAsync() continua retornando compras que estão no período de carência. Se o app depender exclusivamente de queryPurchasesAsync para conferir se um usuário tem o direito de acesso uma assinatura, ele processará automaticamente os períodos de carência, já que essas assinaturas aparecem como ativas na Biblioteca Play Faturamento.

A sincronização do estado da assinatura com seu back-end permite que você esteja mais ciente de recusas de pagamento e dá mais contexto à medida que você tenta reduzir o número de desistência de usuários. Ouça mensagens SubscriptionNotification com o tipo SUBSCRIPTION_IN_GRACE_PERIOD para receber uma notificação quando o usuário entrar em um período de carência. Enquanto o usuário está no período de carência, o recurso de assinatura contém autoRenewEnabled = true. O Google Play estende dinamicamente o valor expiryTime até o período de carência terminar, porque o direito precisa durar até que ele cancele a assinatura ou o período de carência termine. O valor do campo subscriptionState durante esse período é SUBSCRIPTION_STATE_IN_GRACE_PERIOD. O recurso de assinatura é parecido com este exemplo:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_IN_GRACE_PERIOD",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": timestamp_in_future,
      "autoRenewingPlan": {
        "autoRenewEnabled": true
      }
    }
  ],
}

O Google Play informa aos usuários que estão em um período de carência que o pagamento foi recusado e solicita que corrijam os problemas com a forma de pagamento na Play Store. Quando um usuário entra em um período de carência, você também precisa incentivá-lo a corrigir a forma de pagamento, caso a falha tenha sido involuntária. Uma maneira simples de fazer isso é usando a API In-App Messaging. Se você chamar essa API quando o usuário abrir o app, ele receberá uma mensagem do Google Play em uma snackbar temporária informando que o pagamento foi recusado. Essa mensagem também inclui um link direto para que ele corrija a forma de pagamento no Google Play.

Assim que o usuário corrige a forma de pagamento, a assinatura é renovada com a data de renovação original, e você pode processar essa ação conforme descrito em Renovações.

Se o usuário não corrigir a forma de pagamento durante o período de carência, a assinatura vai ativar a suspensão de conta, e ele perderá o direito de acesso.

Acesso e recuperação no período de carência

A Figura 2 mostra uma linha do tempo de uma assinatura que entra em um período de carência e é recuperada quando o usuário corrige a forma de pagamento. Após o término do período de carência, o usuário perderá os benefícios da assinatura e a conta entrará em suspensão.

Figura 2. Cronograma para uma assinatura que entra em um período de carência e é recuperada antes que ela termine.

É importante se lembrar dos seguintes pontos:

  • Durante o período de carência, o usuário precisa manter o acesso aos benefícios da assinatura.
  • Quando uma assinatura é recuperada durante um período de carência, a data de renovação não é redefinida.
  • Se você aumentar o período de carência, por exemplo, de 7 para 14 dias, os usuários que estiverem nesse período terão acesso estendido aos benefícios da assinatura.
  • Se você diminuir o período de carência, os usuários que tiverem excedido o novo período de carência terão os benefícios da assinatura revogados imediatamente. Por exemplo, se você diminuir o período de carência de 14 para 7 dias, os usuários que estiverem entre os dias 8 e 14 do período de carência antigo terão os benefícios da assinatura revogados imediatamente.
  • A assinatura permanecerá em estado ativo, e você não receberá um período de carência período de RTDN até o término do período de carência silencioso

Período de carência silencioso

É possível definir um período de carência de 0 dias, mas o Google Play vai esperar no mínimo um dia para garantir tempo suficiente para novas tentativas de pagamento. Esse período de carência silencioso oferece a rede de segurança para o processamento de pagamentos. Durante esse período de 24 horas, a assinatura permanece estado ACTIVE.

A melhor maneira de ficar em sincronia com as alterações de estado da assinatura é ouça e reaja às Notificações do desenvolvedor em tempo real (RTDN, na sigla em inglês). Chame o método purchases.subscriptionsv2.get() no horário da RTDN em vez do horário de expiração para obter uma status da assinatura.

Dependendo do status da assinatura após o período de carência silencioso de 24 horas período, você receberá uma das seguintes notificações:

  • SUBSCRIPTION_ON_HOLD (se ativado)
  • SUBSCRIPTION_CANCELED (se cancelado)
  • SUBSCRIPTION_EXPIRED (se estiver vencido)
  • SUBSCRIPTION_RENEWED (se renovado)

Também é possível chamar o método subscriptionV2.get() a qualquer momento após a Período de carência silencioso de 24 horas para receber o status mais recente da assinatura.

Suspensão de conta

Se houver problemas de pagamento com a renovação de uma assinatura, será iniciado um período de suspensão de conta após o término de qualquer período de carência. Quando uma assinatura entra em suspensão de conta, é necessário bloquear o acesso ao direito de assinatura.

Durante a suspensão de conta, continue a processar os cancelamentos, as restaurações ou as renovações das suas assinaturas, conforme necessário, já que o usuário pode fazer essas mudanças enquanto a assinatura está suspensa.

As RTDNs notificam você quando a conta entra no período de suspensão. Assim, você pode informar o mais rápido possível ao usuário por que o acesso à assinatura foi suspenso. Uma maneira simples de fazer isso é usando a API In-App Messaging. Chamar essa API quando o usuário abrir o app mostrará uma mensagem em uma snackbar temporária informando que o pagamento foi recusado. Essa mensagem também inclui um link direto para que o usuário corrija a forma de pagamento no Google Play.

Se os usuários tiverem acesso ao conteúdo da assinatura fora do app, eles poderão descobrir que perderam o acesso em diferentes plataformas. Envie uma notificação push ou um e-mail para informar que a assinatura não está mais ativa devido a uma recusa de pagamento.

A assinatura não é retornada pelo método queryPurchasesAsync() durante a suspensão da conta. Portanto, se o app depende desse método para mostrar compras, é necessário oferecer suporte à suspensão de conta por padrão.

Com as Notificações do desenvolvedor em tempo real, você recebe uma mensagem SubscriptionNotification com o tipo SUBSCRIPTION_ON_HOLD quando uma assinatura entra em suspensão de conta. Chame o método purchases.subscriptionsv2.get do servidor de back-end seguro para acessar as novas informações da assinatura. Durante a suspensão da conta, o campo expiryTime do recurso de assinatura é definido como um carimbo de data/hora no passado, e o campo subscriptionState é definido como SUBSCRIPTION_STATE_ON_HOLD:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ON_HOLD",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": timestamp_in_past,
      ...
    }
  ],
}

Para restaurar o acesso, os usuários precisam corrigir a forma de pagamento. O Google Play informa aos usuários na suspensão de conta a recusa do pagamento. Você também precisa incentivá-los a corrigir a forma de pagamento.

Depois que o usuário corrige a forma de pagamento, a assinatura retorna a um estado ativo, e você precisa restaurar o acesso ao conteúdo assinado. Nesse caso, o token de compra é o mesmo de antes da suspensão da conta, já que a mesma compra está sendo recuperada, e você recebe uma RTDN com o tipo SUBSCRIPTION_RECOVERED.

Para assinaturas de parcelas, podem ocorrer recusas e recuperações de pagamento para qualquer tentativa de pagamento individual.

Após a recuperação, a Biblioteca Play Faturamento retorna a assinatura novamente pelo método queryPurchasesAsync(). Se você usar esse método para determinar se um usuário tem direito de acesso a uma assinatura, o app vai processar automaticamente a assinatura que está sendo recuperada.

Ouça uma mensagem de SubscriptionNotification com o tipo SUBSCRIPTION_RECOVERED para receber uma notificação quando uma assinatura é recuperada e o acesso do usuário é restabelecido. Se você consultar uma assinatura após receber essa notificação, o campo expiryTime será definido como um carimbo de data/hora no futuro, e o campo subscriptionState será definido como SUBSCRIPTION_STATE_ACTIVE novamente:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": next_renewal_date,
      ...
    }
  ],
}

Se o usuário não corrigir a forma de pagamento antes do final do período de suspensão de conta, você receberá uma RTDN com o tipo SUBSCRIPTION_CANCELED. Para conferir instruções para o processamento de cancelamentos, consulte Cancelamentos. Quando você consulta uma assinatura que foi cancelada dessa maneira, o campo expiryTime retornado é definido como um carimbo de data/hora no passado:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_CANCELED",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": timestamp_in_past,
      ...
    }
  ],
}

Imediatamente após receber a notificação do cancelamento durante a suspensão da conta, você também receberá uma RTDN com o tipo SUBSCRIPTION_EXPIRED, já que o usuário não terá o direito de pagamento e a assinatura terá sido cancelada. Processe essa expiração normalmente.

O usuário pode recuperar o acesso comprando o mesmo plano de assinatura ou qualquer outro oferecido pelo app durante o período de suspensão de conta da compra original. Nesse caso, um novo token de compra será emitido, e o novo valor será retornado como parte de um evento SUBSCRIPTION_PURCHASED que representa essa nova instância.

Acesso e recuperação de suspensão de conta

A Figura 3 mostra uma linha do tempo de uma assinatura que entra na suspensão de conta e é recuperada quando o usuário corrige a forma de pagamento.

Figura 3. Cronograma para uma assinatura que entra em suspensão de conta e é recuperada antes que ela termine.

Como no exemplo anterior, a Figura 4 mostra uma linha do tempo de uma assinatura que primeiro entra em um período de carência antes de entrar na suspensão de conta e ser recuperada durante a suspensão.

Figura 4. Linha do tempo de uma assinatura que entra em um período de carência, depois entra em suspensão de conta e finalmente é recuperada antes que a suspensão de conta termine.

É importante se lembrar dos seguintes pontos:

  • Antes que uma assinatura entre em suspensão de conta, o Google Play faz outras tentativas de cobrança na forma de pagamento por até 48 horas. O usuário mantém os benefícios da assinatura durante esse período. Após o período de nova tentativa, a assinatura entra em suspensão de conta, e o usuário perde o acesso aos benefícios associados a ela.
  • A assinatura entra em suspensão de conta diretamente quando é retomada de um estado pausado com uma forma de pagamento com falha.
  • Quando a assinatura se recupera da suspensão de conta, a data de renovação é redefinida.

Expirações

Quando uma assinatura expira, o usuário perde o acesso a ela. Nesse caso, uma mensagem SubscriptionNotification com o tipo SUBSCRIPTION_EXPIRED é enviada. Quando você receber essa notificação, consulte a API Google Play Developer para conferir o recurso de assinatura mais recente. Depois de confirmar que subscriptionState é SUBSCRIPTION_STATE_EXPIRED, remova o direito e registre o estado de compra como inválido no back-end. O recurso de assinatura é parecido com este exemplo:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_EXPIRED",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": expiration_time_in_past,
      ...
    }
  ],
}

Cancelamentos

Um usuário pode cancelar uma assinatura na central de assinaturas do Google Play por vontade própria ou ter a assinatura cancelada automaticamente se não a recuperar depois de uma suspensão de conta. Os desenvolvedores também podem acionar um cancelamento com purchases.subscriptions.cancel. Quando uma assinatura é cancelada, o usuário mantém o acesso ao conteúdo até o fim do ciclo de faturamento atual. Quando o ciclo de faturamento termina, o acesso é revogado.

O cancelamento de uma assinatura sem parcelamento e com renovação automática aciona uma SUBSCRIPTION_CANCELED. Quando você recebe essa notificação, o recurso de assinatura retornado da API Google Play Developer tem o campo subscriptionState definido como SUBSCRIPTION_STATE_CANCELED, e o campo expiryTime contém a data em que o usuário vai perder o acesso à assinatura. Se essa data estiver no passado, o usuário perderá o direito imediatamente. Isso pode acontecer, por exemplo, se um usuário cancelar uma assinatura enquanto estiver em suspensão de conta devido a um pagamento recusado.

O recurso de assinatura para uma compra cancelada é parecido com este exemplo:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_CANCELED",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": expiration_time,
      ...
    }
  ],
}

Para assinaturas parceladas, um SUBSCRIPTION_CANCELLATION_SCHEDULED a notificação é enviada após um cancelamento iniciado pelo usuário quando os pagamentos permanecem para o período de compromisso. O cancelamento está pendente e entra em vigor no fim do período de compromisso atual. Quando você receber essa notificação, o recurso de assinatura retornado da API Google Play Developer tem o O campo subscriptionState foi definido como SUBSCRIPTION_STATE_ACTIVE porque A assinatura de parcelas vai continuar ativa até o fim do período de contrato. No entanto, há um objeto pendingCancellation vazio presente. Uma notificação SUBSCRIPTION_CANCELED é enviada seguida por SUBSCRIPTION_EXPIRED no final do período de compromisso.

O recurso de assinatura para uma compra de parcelamento que é O cancelamento pendente é parecido com este exemplo:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  ...
  "lineItems": [
    {
      "productId": "sub_plan01",
      "expiryTime": expiration_time,
      "autoRenewingPlan": {
        "autoRenewEnabled": true,
        "recurringPrice": {
          "currencyCode": "USD",
          "units": "1",
          "nanos": 990000000
        },
        "installmentDetails": {
          "initialCommittedPaymentsCount": 6,
          "remainingCommittedPaymentsCount": 5,
          "pendingCancellation": {}
      ...
        }
      }
    }
  ],
}

Consulte o campo canceledStateContext no recurso de assinatura para saber por que a assinatura foi cancelada. Por exemplo, ela pode ter sido cancelada pelo usuário, pelo sistema ou por você. Se a assinatura tiver sido cancelada pelo usuário, analise o campo userInitiatedCancellation para saber por que o usuário a cancelou. Isso pode ajudar a informar estratégias de comunicação.

Quando uma assinatura é cancelada, mas ainda não expirou, ela ainda é retornada de queryPurchasesAsync(). Você pode mostrar uma mensagem no app informando ao usuário que a assinatura foi cancelada e informando a data de validade.

Revogações

A assinatura pode ser revogada por vários motivos, incluindo a revogação pelo back-end usando purchases.subscriptionsv2.revoke ou devido ao estorno da compra. Nessa situação, revogue o direito do usuário imediatamente. Uma mensagem SubscriptionNotification com o tipo SUBSCRIPTION_REVOKED é enviada quando isso ocorre. Quando você recebe essa notificação, o recurso de assinatura retornado da API Google Play Developer tem o campo subscriptionState definido como SUBSCRIPTION_STATE_EXPIRED.

O recurso de assinatura para uma compra revogada é parecido com este exemplo:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_EXPIRED",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": expiration_time,
      ...
    }
  ]
}

Assinaturas adiadas

Há vários motivos para estender o direito de um usuário. Por exemplo, você pode oferecer aos usuários uma promoção especial, como uma semana grátis na compra de um filme ou acesso gratuito como gesto de boa vontade. Use o método purchases.subscriptions.defer da API Play Developer para adiantar a próxima data de faturamento de uma assinatura com renovação automática. Quando você fizer isso, uma mensagem SubscriptionNotification com o tipo SUBSCRIPTION_DEFERRED será enviada. Durante o período de adiamento, o usuário será assinante do conteúdo com acesso total, mas não será cobrado. A data de renovação da assinatura é atualizada para a nova data.

Para planos pré-pagos, use a API de adiamento de faturamentos para adiar o prazo de vencimento.

O recurso de assinatura adiada é parecido com este exemplo:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": timestamp_in_future,
      ...
    }
  ],
}

Assinaturas pausadas

Você pode reduzir a desistência voluntária de usuários permitindo que eles pausem a assinatura. Quando o recurso de pausa é ativado, os usuários podem optar por pausar a assinatura por um período entre uma semana e três meses, dependendo do período recorrente.

Recorrência da assinatura Semanal Mensal Três meses Seis meses Anual
Duração das pausas disponíveis* 1 semana
2 semanas
3 semanas
4 semanas		 1 mês
2 meses
3 meses		 1 mês
2 meses
3 meses		 1 mês
2 meses
3 meses		 N/A
*Sujeito a alterações a qualquer momento.

Uma pausa de assinatura entra em vigor somente após o término do período de faturamento atual. Enquanto estiver em pausa, o usuário não terá acesso à assinatura e não pagará o preço da renovação. No final do período de pausa, a assinatura será retomada, e o Google tentará fazer a renovação. Se a retomada for bem-sucedida, a assinatura será reativada. Se a retomada falhar devido a um problema de pagamento, o usuário vai entrar no estado de suspensão da conta, conforme mostrado nas Figuras 5 e 6:

Figura 5. Um usuário faz uma pausa e, em seguida, retoma a assinatura.
Figura 6. Um usuário faz uma pausa na assinatura, e a conta entra no estado de suspensão.

Um usuário também pode retomar manualmente uma assinatura a qualquer momento durante o período de pausa, conforme mostrado na Figura 6. Quando isso acontece, a data de faturamento muda para a data de retomada manual.

Quando a assinatura de um usuário é pausada, a Biblioteca Play Faturamento não a retorna pelo método queryPurchasesAsync(). Se a assinatura for retomada, o método queryPurchasesAsync() vai retorná-la de novo.

Ouça as RTDNs para saber quando um usuário pausar a assinatura. Essas notificações também permitem que você informe seus usuários no app que eles pausaram a assinatura e não têm acesso a ela. Ofereça também uma maneira para o usuário retomar manualmente a assinatura a qualquer momento usando um link direto para o Google Play.

Uma mensagem SubscriptionNotification com o tipo SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED é enviada quando o usuário inicia uma pausa na assinatura. Nesse momento, o usuário mantém o acesso à assinatura até a próxima data de renovação, e o recurso da assinatura contém autoRenewEnabled = true. O valor do campo subscriptionState é SUBSCRIPTION_STATE_ACTIVE.

Uma mensagem SubscriptionNotification com o tipo SUBSCRIPTION_PAUSED é enviada quando a pausa entra em vigor. Quando isso acontece, o usuário perde o acesso à assinatura, o recurso de assinatura contém autoRenewEnabled = true e o campo subscriptionState está definido como SUBSCRIPTION_STATE_PAUSED. É possível conferir quando a assinatura será renovada novamente no objeto PausedStateContext.

Uma mensagem SubscriptionNotification com o tipo SUBSCRIPTION_RENEWED será enviada se a assinatura for retomada automaticamente no final do período de pausa ou se o usuário retomar a assinatura manualmente. Isso precisa ser processado conforme descrito em Renovações.

Uma mensagem SubscriptionNotification com o tipo SUBSCRIPTION_ON_HOLD será enviada se houver uma falha no pagamento ao tentar retomar a assinatura após a pausa. Isso precisa ser processado conforme descrito em Suspensão da conta.

Renovar assinaturas

Para planos básicos de assinatura com renovação automática, a Google Play Store pode mostrar um botão Renovar assinatura. Esse botão permite que os usuários recuperem o acesso a uma assinatura. Ele pode não aparecer por vários motivos, como quando uma assinatura expirou há muito tempo.

Figura 7. Seção Conta > Assinaturas no app da Google Play Store mostrando uma assinatura cancelada com um botão Renovar assinatura.

Embora o botão seja sempre marcado como Renovar assinatura, a funcionalidade depende do estado da assinatura.

Quando uma assinatura estiver cancelada, mas ainda não tiver expirado, o usuário ainda estará inscrito e terá acesso aos benefícios. Se o usuário tocar em "Renovar assinatura", o cancelamento será revertido e a assinatura continuará sendo renovada. Essa ação é conhecida como restauração na documentação do desenvolvedor e nas APIs do Google Play.

Depois que uma assinatura de renovação automática expirar, você poderá permitir que os usuários comprem o mesmo plano básico de assinatura. Essa ação é conhecida como renovar assinatura na documentação do desenvolvedor e nas APIs do Google Play. É possível configurar essa opção para cada plano básico no Play Console ou usando a API.

Restaurar antes da expiração

Caso seu app dependa apenas do método queryPurchasesAsync() para determinar se um usuário tem direito de acesso a uma assinatura, as restaurações serão processadas automaticamente, já que o método queryPurchasesAsync() continua retornando compras canceladas antes da data de validade. Uma assinatura restaurada continuará sendo renovada como se não tivesse sido cancelada.

Se o app sincronizar o estado da assinatura com um back-end, ouça uma mensagem SubscriptionNotification com o tipo SUBSCRIPTION_RESTARTED. Depois de receber essa RTDN, seu app poderá responder à notificação, registrar que a assinatura está configurada para ser renovada e parar de mostrar mensagens de restauração. O recurso de assinatura é parecido com este exemplo:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": next_renewal_date
      ...
    }
  ],
}

Renovar assinatura após a expiração

Se um plano básico com renovação automática estiver configurado usando o Google Play Console ou a API para permitir a renovação da assinatura, os usuários poderão comprar novamente uma assinatura expirada na Google Play Store.

Essas são novas compras. O Google Play emite um novo token de compra, e seu back-end recebe uma RTDN com o tipo SUBSCRIPTION_PURCHASED. Nesse caso, o status desse tipo de compra fora do app não inclui um linkedPurchaseToken associado à compra original, já que a assinatura original expirou totalmente. Essas são novas compras que seu back-end precisa processar e confirmar como qualquer outra compra.

Upgrades, downgrades e renovações de assinatura

Quando um usuário faz upgrade, downgrade ou assina de novo antes do vencimento após cancelar a assinatura no app, a antiga será invalidada, e uma nova assinatura será criada com um novo token de compra.

Além disso, o recurso de assinatura retornado da API Google Play Developer contém um campo linkedPurchaseToken que indica a compra antiga que o usuário usou para fazer upgrade, downgrade ou renovação. Use o token de compra nesse campo para procurar a assinatura antiga e identificar a conta do usuário. Assim, é possível associar a nova compra à mesma conta.

Antes de oferecer as opções de upgrade, downgrade ou renovação de assinatura a um usuário no app, confirme a assinatura atual. Qualquer mudança ou reativação de plano será bloqueada se a assinatura atual ainda estiver com confirmação pendente.

Se o usuário fizer upgrade, downgrade ou assinar de novo, essa será uma nova compra que você precisará confirmar. A maneira recomendada de fazer isso é usando a API Google Play Developer. O recurso de assinatura é parecido com este exemplo:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  ...
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  "linkedPurchaseToken": old_purchase_token,
  ...
  "lineItems": [
    {
      "productId": "sub_variant_plan01",
      "expiryTime": next_renewal_date,
      "autoRenewingPlan": {
        "autoRenewEnabled": true
      }
    }
  ],
}

Mudanças no preço

Consulte o guia de práticas recomendadas para mudanças de preço para saber mais sobre a mudança dos preços de renovação automática e como notificar os usuários quando for adequado.

Quando as mudanças de preço forem aplicadas para pedir a permissão do usuário, você receberá uma RTDN se o usuário tomar medidas para confirmar ou rejeitar o novo preço.

Processar a confirmação do usuário sobre uma mudança de preço

Quando um usuário aceita o aumento no preço da assinatura, você recebe uma mensagem SubscriptionNotification com o tipo SUBSCRIPTION_PRICE_CHANGED_CONFIRMED. Quando ocorrer uma desistência de redução no preço ou quando o aumento no preço da assinatura for renovado, você receberá uma mensagem SubscriptionNotification com o tipo SUBSCRIPTION_RENEWED. Trate essa notificação como qualquer outra renovação.

Processar casos em que um aumento de preço não é aceito

Se um usuário não concordar com um aumento de preço antes de precisar renovar com o novo valor, a assinatura será cancelada automaticamente, e você receberá uma mensagem SubscriptionNotification com o tipo SUBSCRIPTION_CANCELED. Processe esse evento conforme descrito em Cancelamentos.

Os usuários também podem cancelar as assinaturas para recusar o aumento no preço seguindo o mesmo mecanismo.

Processar o ciclo de vida dos planos pré-pagos

Assim como acontece com as assinaturas de renovação automática, você precisa confirmar o recebimento dos planos pré-pagos após cada nova compra. No caso de planos pré-pagos, você precisa processar completamente a compra inicial e as recargas, já que o usuário sempre precisa passar pelo fluxo de compra.

Alguns planos pré-pagos podem ter prazos de duração curtos. Por isso, é importante confirmar a compra o mais rápido possível. Planos pré-pagos com prazo de uma semana ou mais precisam ser confirmados dentro de três dias. Planos com prazo menor que uma semana precisam ser confirmados em até metade do período de assinatura do plano. Por exemplo, para a compra de um plano pré-pago de três dias, os desenvolvedores têm até um dia e meio para enviar a confirmação.

Figura 8. Estados de ciclo de vida e eventos de transição para compras de assinaturas.

Uma mensagem SubscriptionNotification com o tipo SUBSCRIPTION_PURCHASED é enviada ao cliente RTDN sempre que uma assinatura do plano pré-pago é comprada, incluindo todas as recargas. Chame o método purchases.subscriptionsv2.get para conferir o estado mais recente da assinatura do plano pré-pago.

Um novo token de compra é emitido para recargas, e você recebe o token anterior no campo linkedPurchaseToken como parte do novo estado de compra da assinatura. O token de compra é válido a partir da assinatura até 60 dias após a expiração. Após essa data, o token de compra será não é mais válido para chamar a API Google Play Developer.

O recurso de assinatura para uma compra de plano pré-pago é parecido com este exemplo:

{
  "kind": "androidpublisher#subscriptionPurchaseV2",
  "startTime": "2022-04-22T18:39:58.270Z",
  "regionCode": "US",
  "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
  "latestOrderId": "GPA.3333-4137-0319-36762",
  "acknowledgementState": "ACKNOWLEDGEMENT_STATE_ACKNOWLEDGED",
  "lineItems": [
    {
      "productId": "prepaid_plan01",
      "expiryTime": expiry_date,
      "prepaidPlan": {
        "allowExtendAfterTime": timestamp_after_which_topups_are_allowed
      }
    }
  ]
}

Confira quando o direito de acesso termina no campo expiryTime. As compras de recarga acumulam o período do direito para aumentar a duração. Isso significa que, se o usuário fizer a recarga antes do término do direito original, o novo período será adicionado sobre a data de validade anterior.

Mostre uma mensagem no app informando ao usuário que as assinaturas pré-pagas podem ser estendidas com uma recarga. Para saber quando um usuário poderá fazer a recarga, confira o campo allowExtendAfterTime no recurso de assinatura.

Os planos pré-pagos não são renovados automaticamente, então não podem ser cancelados. Se um usuário quiser cancelar, ele pode deixar que o plano pré-pago atinja a data de validade.