In-app Billing API

A In-app Billing Version 3 API facilita a integração do Faturamento no aplicativo aos aplicativos. Os recursos dessa versão contêm um fluxo de compra síncrono melhor, APIs que permitem controlar a posse de bens consumíveis e armazenamento em cache local de dados de compras internas do aplicativo.

Tipos de produto

Você define os produtos usando o Google Play Developer Console, inclusive tipo de produto, SKU, preço, descrição e assim por diante. Para mais informações, consulte Administração do faturamento no aplicativo. A versão 3 da API é compatível com produtos internos do aplicativo e assinaturas.

Produto gerenciado interno do aplicativo

Produtos gerenciados internos do aplicativo são itens que têm informações de propriedade controladas e gerenciadas pelo Google Play. Quando um usuário compra um item gerenciado interno do aplicativo, o Google Play armazena as informações de compra de cada item para cada usuário. Isso permite consultar posteriormente o Google Play, a qualquer momento, para restaurar o estado dos itens que determinado usuário comprou. Essa informação é persistente nos servidores do Google Play, mesmo que o usuário desinstale o aplicativo ou troque de dispositivo.

Se você estiver usando a versão 3 da API, também é possível consumir itens gerenciados dentro do aplicativo. Você normalmente implementaria o consumo para itens que podem ser comprados diversas vezes (como moeda do jogo, combustível ou magias). Depois de comprado, um item gerenciado não pode ser comprado novamente até ser consumido, por meio de uma solicitação de consumo enviada à Google Play. Para saber mais sobre o consumo de produtos internos do aplicativo, consulte Consumo de itens.

Assinaturas

Uma assinatura é um tipo de produto oferecido em Faturamento no aplicativo que permite vender conteúdo, serviços ou recursos a usuários de dentro do aplicativo, com faturamento recorrente mensal ou anual. É possível vender assinaturas a quase todos os tipos de conteúdo digital, em qualquer tipo de aplicativo ou jogo. Para entender como as assinaturas funcionam, veja Assinaturas de faturamento no aplicativo.

Com a versão 3 da API, é possível usar o mesmo fluxo de compra para comprar assinaturas e recuperar informações de compra da assinatura que o usado para produtos internos do aplicativo. Para ver um exemplo de código, acesse Implementar assinaturas.

Importante: Diferentemente de produtos internos do aplicativo, assinaturas não podem ser consumidas.

Comprar itens

Imagem 1. A sequência básica de uma solicitação de compra.

Eis um fluxo de compra típico com a versão 3 da API:

  1. O aplicativo envia uma solicitação de isBillingSupported ao Google Play para determinar se a versão-alvo da In-app Billing API que você usa é compatível.
  2. Quando o aplicativo inicia ou o usuário acessa com a senha, é recomendável verificar com o Google Play para determinar que itens o usuário possui. Para consultar as compras no aplicativo do usuário, envie uma solicitação de getPurchases. Se a solicitação for bem-sucedida, o Google Play retornará um Bundle contendo uma lista de IDs de produto dos itens comprados, uma lista de dados de compra individuais e uma lista de assinaturas das compras.
  3. Normalmente, é preferível informar ao usuários os produtos disponíveis para compra. Para consultar os detalhes dos produtos internos do aplicativo, que você definiu no Google Play, seu aplicativo pode enviar uma solicitação de getSkuDetails. Você deve especificar uma lista de IDs de produto na solicitação de consulta. Se a solicitação for bem-sucedida, o Google Play retornará um Bundle contendo detalhes do produto, inclusive preço, título, descrição e o tipo de compra.
  4. Se o usuário não possuir determinado produto interno do aplicativo, você pode iniciar uma compra para ele. Para iniciar uma solicitação de compra, o aplicativo envia uma solicitação de getBuyIntent, especificando o ID de produto do item a comprar junto com outros parâmetros. Você deve registrar o ID de produto ao criar um novo produto interno do aplicativo no Console do desenvolvedor.
    1. O Google Play retornará um Bundle contendo uma PendingIntent que o aplicativo usará para iniciar a IU do processo de finalização da compra.
    2. Seu aplicativo inicializará o intent pendente chamando o método startIntentSenderForResult.
    3. Quando o fluxo de finalização for concluído (ou seja, o usuário confirmar ou cancelar a compra do item), o Google Play enviará uma Intent de resposta ao método onActivityResult. O código resultante do onActivityResult indica se a compra foi efetuada ou cancelada. A Intent de resposta contém informações sobre o item comprado, inclusive uma string purchaseToken, que é gerada pelo Google Play para identificar essa transação de compra. A Intent também contém a assinatura da compra, efetivada com sua chave privada de desenvolvedor.

Para conhecer melhor as chamadas e respostas do servidor da versão 3 da API, veja Referência de faturamento no aplicativo.

Consumir produtos internos do aplicativo

Você pode usar o mecanismo de consumo para controlar os produtos internos do aplicativo que o usuário tem.

Na versão 3, todos os produtos internos do aplicativo são gerenciados. Isso significa que a posse de todas as compras de item do usuário dentro do aplicativo é mantida pelo Google Play, e seu aplicativo pode consultar as informações de compra do usuário sempre que necessário. Quando o usuário compra um produto no aplicativo com sucesso, essa compra é registrada no Google Play. Quando um produto interno do aplicativo é comprado, ele é considerado “detido”. Produtos internos do aplicativo com estado de “detido” não podem ser comprados no Google Play. É preciso enviar uma solicitação de consumo para o produto interno do aplicativo “detido” antes de o Google Play disponibilizá-lo para compra novamente. Consumir o produto interno do aplicativo retorna-o ao estado de “não detido” e descarta os dados de compra anteriores.

Imagem 2. A sequência básica de uma solicitação de consumo.

Para obter a lista de produtos detidos pelo usuário, seu aplicativo envia uma chamada de getPurchases ao Google Play. O aplicativo pode fazer uma solicitação de consumo enviando uma chamada de consumePurchase. No argumento da solicitação, é preciso especificar a string purchaseToken exclusiva do produto, obtida no Google Play no ato da compra. O Google Play retorna um código de status que indica se o consumo foi registrado com sucesso.

Produtos internos do aplicativo consumíveis e não consumíveis

Você decide se quer tratar seus produtos internos do aplicativo com itens não consumíveis ou consumíveis.

Itens não consumíveis.
Normalmente, não se implementaria consumo para produtos internos do aplicativo que só possam ser comprados no aplicativo e forneçam benefício permanente. Depois de comprados, esses itens serão associados permanentemente à conta Google do usuário. Um exemplo de produto interno do aplicativo não consumível é uma atualização premium ou um pacote de nível.
Itens consumíveis.
Por outro lado, você pode implementar consumo para itens que podem ser comprados diversas vezes. Normalmente, esses itens fornecem determinados efeitos temporários. Por exemplo, o personagem do usuário no jogo pode ganhar pontos de vida ou moedas de ouro extras no inventário. Fornecer os benefícios ou efeitos do item comprado no aplicativo é conhecido como provisionamento do produto interno do aplicativo. Você é responsável por controlar e acompanhar como os produtos no aplicativo são provisionados aos usuários.

Importante: Antes de provisionar o produto consumível no aplicativo, você deve enviar uma solicitação de consumo ao Google Play e receber uma resposta positiva indicando que o consumo foi registrado.

Gerenciar compras de consumíveis no aplicativo

Veja o fluxo básico de compra de um produto consumível no aplicativo:

  1. Inicie um fluxo de compra com uma chamada de getBuyIntent
  2. Obtenha um Bundle de resposta do Google Play que indique se a compra foi realizada com sucesso.
  3. Se foi, consuma o item fazendo uma chamada de consumePurchase.
  4. Obtenha um código de resposta do Google Play que indique se o consumo foi realizado com sucesso.
  5. Se sim, provisione o produto no aplicativo.

Em seguida, quando o usuário inicializar ou acessar o aplicativo, você deve verificar se ele possui algum produto consumível interno do aplicativo pendente. Se sim, certifique-se de consumir e provisionar esse produto. Veja a fluxo recomendado de inicialização do aplicativo ao implementar produtos consumíveis no aplicativo:

  1. Envie uma solicitação de getPurchases para consultar os produtos internos do aplicativo detidos do usuário.
  2. Se houver algum produto consumível interno do aplicativo, consuma os itens chamando consumePurchase. Essa etapa é necessária porque o aplicativo pode concluir a ordem de compra do item consumível, mas parar ou desconectar-se antes de o aplicativo conseguir enviar uma solicitação de consumo.
  3. Obtenha um código de resposta do Google Play que indique se o consumo foi realizado com sucesso.
  4. Se sim, provisione o produto no aplicativo.

Armazenamento em cache local

Como o cliente do Google Play agora armazena informações de faturamento no aplicativo em cache localmente no dispositivo, você pode usar a versão 3 da API para consultar essas informações com mais frequência, por exemplo, por meio de uma chamada de getPurchases. Diferentemente das versões anteriores da API, muitas chamadas da versão 3 da API serão fornecidas por meio de pesquisas de cache, em vez de por uma conexão de rede ao Google Play, o que acelera significativamente o tempo de resposta da API.