Participe do evento ⁠#Android11: apresentação de lançamento da versão Beta no dia 3 de junho.

Referência de AIDL do Google Play Faturamento

Aviso: a AIDL agora está obsoleta e será removida em uma versão futura. Para implementar os recursos do Google Play Faturamento, use a Google Play Billing Library.

Esta documentação fornece informações técnicas de referência para usar a AIDL do Google Play Faturamento.

Códigos de resposta do servidor

A tabela abaixo lista todos os códigos de resposta do servidor enviados do Google Play para seu aplicativo. O Google Play envia o código de resposta de forma síncrona como um número inteiro mapeado para a chave RESPONSE_CODE na resposta Bundle. O aplicativo precisa processar todos esses códigos de resposta.

Tabela 1. Resumo dos códigos de resposta das chamadas de AIDL do Google Play Faturamento.

Código de resposta Valor Descrição
BILLING_RESPONSE_RESULT_OK 0 Pronto
BILLING_RESPONSE_RESULT_USER_CANCELED 1 O usuário pressionou "voltar" ou cancelou uma caixa de diálogo
BILLING_RESPONSE_RESULT_SERVICE_UNAVAILABLE 2 A conexão de rede está inativa
BILLING_RESPONSE_RESULT_BILLING_UNAVAILABLE 3 A versão da AIDL do Google Play Faturamento não é compatível com o tipo solicitado
BILLING_RESPONSE_RESULT_ITEM_UNAVAILABLE 4 O produto solicitado não está disponível para compra
BILLING_RESPONSE_RESULT_DEVELOPER_ERROR 5 Argumentos inválidos fornecidos para a API. Esse erro também pode indicar que o aplicativo não foi assinado corretamente ou configurado de maneira adequada para o Google Play Faturamento ou não tem as permissões necessárias no manifesto.
BILLING_RESPONSE_RESULT_ERROR 6 Erro fatal durante a ação da API
BILLING_RESPONSE_RESULT_ITEM_ALREADY_OWNED 7 Falha ao comprar porque o item já tem proprietário
BILLING_RESPONSE_RESULT_ITEM_NOT_OWNED 8 Falha ao consumir porque o item não tem proprietário

Compatibilidade da referência de AIDL do Google Play Faturamento

Esta seção descreve métodos para conseguir informações sobre os tipos de compatibilidade do Google Play Faturamento disponíveis para seu app.

Método isBillingSupported()

Esse método indica se:

  • a versão da AIDL é compatível com seu app;
  • o Google Play é compatível com faturamento no país do usuário;
  • o Google Play Faturamento está ativado no pacote do seu app.
  • o app pode usar o tipo de item para fins de faturamento.

Tabela 2. Parâmetros isBillingSupported().

Chave Tipo Descrição
apiVersion int O número da versão da AIDL do Google Play Faturamento que seu app está usando.
packageName String O nome do pacote do app que está chamando esse método.
type String O valor precisa ser inapp para um produto no aplicativo ou subs para assinaturas.

Este método está disponível na versão 3 e mais recentes da AIDL do Google Play Faturamento.

Método isBillingSupportedExtraParams()

Esse método é idêntico a isBillingSupported(), exceto pelo fato de que é possível transmitir um quarto argumento, um Bundle, que pode conter parâmetros extras.

Tabela 3. Parâmetros isBillingSupportedExtraParams().

Chave Tipo Descrição
apiVersion int O número da versão da AIDL do Google Play Faturamento que seu app está usando.
packageName String O nome do pacote do app que está chamando esse método.
type String O valor precisa ser inapp para um produto no aplicativo ou subs para assinaturas.
extraParams Bundle

Um conjunto de parâmetros extras que especifica ainda mais o tipo do Google Play Faturamento compatível com o app.

Esse pacote pode conter uma chave opcional chamada vr, que tem um valor booleano. Essa sinalização especifica se o app é compatível com um fluxo de compra de realidade virtual (RV).

Esse método está disponível na versão 7 e mais recentes da AIDL do Google Play Faturamento.

Detalhes da referência de AIDL do Google Play Faturamento

A AIDL do Google Play Faturamento está definida no arquivo IInAppBillingService.aidl, que está incluído na versão 3 do aplicativo de amostra.

Método getSkuDetails()

Use o método getSkuDetails() para receber detalhes do produto para uma lista correspondente de IDs de produto.

Tabela 4. Parâmetros GetSkuDetails().

Chave Tipo Descrição
apiVersion int O número da versão da AIDL do Google Play Faturamento que seu app está usando.
packageName String O nome do pacote do app que está chamando esse método.
type String Tipo de itens no aplicativo ("inapp" para compras únicas e "subs" para assinaturas).
skusBundle Bundle Pacote contendo uma StringArrayList de SKUs com a chave ITEM_ID_LIST.

Se o método getSkuDetails() for bem-sucedido, o Google Play enviará uma resposta Bundle. Os resultados da consulta são armazenados no Bundle em uma string ArrayList mapeada para a chave DETAILS_LIST. Cada string na lista de detalhes contém detalhes de um único produto no formato JSON. Os campos da string JSON com os detalhes do produto se encontram resumidos na tabela 5.

Tabela 5. Descrição dos campos JSON com detalhes do item do produto retornados de uma solicitação getSkuDetails().

Chave Descrição
productId O ID do produto.
type O valor precisa ser inapp para um produto no aplicativo ou subs para assinaturas.
price Preço formatado do item, incluindo o símbolo da moeda. O preço não inclui impostos.
price_amount_micros Preço em microunidades, em que um milhão de microunidades equivale a uma unidade da moeda. Por exemplo, se price for "€7.99", price_amount_micros será "7990000". Esse valor representa o preço arredondado e localizado de determinada moeda.
price_currency_code Código de moeda ISO 4217 para price. Por exemplo, se price for especificado em libras esterlinas britânicas, price_currency_code será "GBP".
title Título do produto.
description Descrição do produto.
subscriptionPeriod Período de assinatura, especificado no formato ISO 8601. Por exemplo, P1W equivale a uma semana, P1M equivale a um mês, P3M, a três meses, P6M, a seis meses e P1Y, a um ano.

Observação: retornado apenas para assinaturas.

freeTrialPeriod Período de avaliação configurado no Google Play Console, especificado no formato ISO 8601. Por exemplo, P7D equivale a sete dias. Para saber mais sobre a qualificação para avaliação gratuita, consulte Assinaturas no aplicativo.

Observação: retornado apenas para assinaturas que têm um período de avaliação configurado.

introductoryPrice Preço introdutório formatado de uma assinatura, incluindo o símbolo da moeda, como €3.99. O preço não inclui tributos.

Observação: retornado apenas para assinaturas que possuem um período introdutório configurado.

introductoryPriceAmountMicros Preço introdutório em microunidades. A moeda é igual a price_currency_code.

Observação: retornado apenas para assinaturas que possuem um período introdutório configurado.

introductoryPricePeriod O período de faturamento do preço introdutório, especificado no formato ISO 8601.

Observação: retornado apenas para assinaturas que possuem um período introdutório configurado.

introductoryPriceCycles O número de períodos de faturamento da assinatura para os quais o usuário receberá o preço introdutório, como 3.

Observação: retornado apenas para assinaturas que possuem um período introdutório configurado.

Método getBuyIntent()

Esse método retorna um número inteiro de código de resposta mapeado para chave RESPONSE_CODE e um PendingIntent para iniciar o fluxo de compra para o item no aplicativo mapeado para a chave BUY_INTENT, como descrito em Implementar o Google Play Faturamento. Quando receber o PendingIntent, o Google Play enviará uma resposta Intent com os dados da ordem de compra. Os dados retornados na resposta Intent estão resumidos na Tabela 9.

Observação: em vez desse método, recomendamos o uso de getBuyIntentExtraParams(), que fornece outros recursos.

Tabela 6. Dados de resposta de uma solicitação de compra do Google Play Faturamento.

Chave Descrição
RESPONSE_CODE O valor será 0 se a compra for bem-sucedida. Caso contrário, ocorrerá um erro.
INAPP_PURCHASE_DATA Uma string no formato JSON que contém detalhes sobre a ordem de compra. Consulte a tabela 7 para ver uma descrição dos campos JSON.
INAPP_DATA_SIGNATURE String que contém a assinatura dos dados de compra que foram assinados com a chave privada do desenvolvedor. A assinatura de dados usa o esquema RSASSA-PKCS1-v1_5.

A tabela 7 descreve os campos JSON retornados nos dados de resposta de uma ordem de compra.

Tabela 7. Descrições dos campos JSON para INAPP_PURCHASE_DATA.

Campo Descrição
autoRenewing Indica se a assinatura é renovada automaticamente. Se true, a assinatura estará ativa e será renovada automaticamente na próxima data de faturamento. Se false, o usuário cancelou a assinatura. O usuário tem acesso ao conteúdo da assinatura até a próxima data de faturamento e só manterá o acesso a partir desse momento se reativar a renovação automática (ou renovar manualmente, conforme descrito em Renovação manual). Se você oferecer um período de carência, esse valor permanecerá definido como true para todas as assinaturas, desde que o período de carência não tenha expirado. A próxima data de faturamento é estendida dinamicamente todos os dias até o final do período de carência ou até que o usuário determine a forma de pagamento.
orderId Um identificador de pedido exclusivo para a transação. Esse identificador corresponde ao código do pedido de pagamentos feitos com serviços do Google.
packageName O pacote de aplicativo do qual a compra foi originada.
productId O identificador de produto do item. Todo item tem um ID do produto, que você precisa especificar na lista de produtos do aplicativo no Google Play Console.
purchaseTime A hora em que o produto foi comprado, em milissegundos desde a época (1° de janeiro de 1970).
purchaseState O estado de compra do pedido. Sempre retorna 0 (comprado).
developerPayload Uma string especificada pelo desenvolvedor que contém informações complementares sobre um pedido. É possível especificar um valor para esse campo quando você faz uma solicitação getBuyIntent.
purchaseToken Um token que identifica exclusivamente uma compra para determinado par de item e usuário.

Método consumePurchase()

Compra de consumo correspondente ao token de compra. Isso fará com que esse item seja removido de todas as respostas subsequentes para getPurchases() e permitirá a recompra de itens do mesmo SKU.

Tabela 8. Parâmetros consumePurchase().

Chave Tipo Descrição
apiVersion int O número da versão da AIDL do Google Play Faturamento que seu app está usando.
packageName String O nome do pacote do app que está chamando esse método.
purchaseToken String Token no JSON de informações de compra que identifica a compra a ser consumida.

Esse método retorna um RESULT_OK(0) de consumo bem-sucedido e códigos de resposta apropriados em caso de falhas.

Método getBuyIntentToReplaceSkus()

Esse método é usado para fazer upgrade ou downgrade de uma compra de assinatura. O método é semelhante a getBuyIntent(), mas ele adquire uma lista com exatamente um SKU já comprado para ser substituído pelo SKU que está sendo comprado. Quando o usuário conclui a compra, o Google Play substitui o SKU antigo e credita ao usuário o valor não utilizado do tempo de assinatura de maneira proporcional. O Google Play aplica esse crédito à nova assinatura e não começa a cobrar o usuário por ela até que todo o crédito seja usado.

Observação: em vez desse método, recomendamos o uso de getBuyIntentExtraParams(), que fornece outros recursos.

Esse método foi adicionado à versão 5 da AIDL do Google Play Faturamento. Para verificar se o método foi relatado, envie uma solicitação de AIDL isBillingSupported.

Observação: esse método só pode ser usado para compras de assinatura. Se o parâmetro type transmitido for diferente de "subs", o método retornará BILLING_RESPONSE_RESULT_DEVELOPER_ERROR. Além disso, os SKUs transmitidos não podem incluir SKUs para assinaturas temporárias.

Esse método retorna um número inteiro de código de resposta mapeado para a chave RESPONSE_CODE e um PendingIntent para iniciar o fluxo de compra para a inscrição no aplicativo mapeada para a chave BUY_INTENT, conforme descrito em Implementar o Google Play Faturamento. Quando receber o PendingIntent, o Google Play enviará uma resposta Intent com os dados da ordem de compra. Os dados retornados na resposta Intent estão resumidos na Tabela 9.

Tabela 9. Dados de resposta de uma solicitação de compra da AIDL do Google Play Faturamento versão 5.

Chave Descrição
RESPONSE_CODE O valor será 0 se a compra for bem-sucedida. Se a compra falhar, haverá um código de erro.
INAPP_PURCHASE_DATA Uma string no formato JSON que contém detalhes sobre a ordem de compra. Consulte a tabela 6 para ver uma descrição dos campos JSON.
INAPP_DATA_SIGNATURE String que contém a assinatura dos dados de compra que o desenvolvedor assinou com a chave privada. A assinatura de dados usa o esquema RSASSA-PKCS1-v1_5.

Método getBuyIntentExtraParams()

Esse método inicia uma solicitação de compra. O método é uma variante do getBuyIntent() e recebe mais um parâmetro extraParams. Esse parâmetro é um Bundle de chaves e valores opcionais que afetam a operação do método, como mostrado na Tabela 10.

Tabela 10. Parâmetros getBuyIntentExtraParams() extras.

Chave Tipo Descrição
skusToReplace List<String> Uma lista opcional com exatamente um SKU que está passando por upgrade ou downgrade. Transmita esse campo se a compra estiver fazendo o upgrade ou downgrade da assinatura existente. O SKU especificado é substituído pelo SKU que o usuário está comprando. O Google Play substitui o SKU especificado no início do próximo ciclo de faturamento.
replaceSkusProration boolean

Especifica se o usuário será creditado por qualquer tempo de assinatura não utilizado nos SKUs de que ele está fazendo upgrade ou downgrade. Se você definir esse campo como "true", o Google Play substituirá os SKUs antigos e creditará ao usuário o valor não utilizado do tempo de assinatura de maneira proporcional. O Google Play aplica esse crédito à nova assinatura e não começa a cobrar o usuário por ela até que todo o crédito seja usado.

Se você definir esse campo como "false", o usuário não receberá crédito por nenhum tempo de assinatura não utilizado, e a data de recorrência não será alterada.

O valor padrão é true. Ignorado se você não transmitir skusToReplace.

accountId String

String opcional ofuscada que é exclusivamente associada à conta do usuário no seu app. Se você transmitir esse valor, o Google Play poderá usá-lo para detectar atividades irregulares, como vários dispositivos fazendo compras na mesma conta em um curto período.

Esse campo é semelhante a developerId, porque representa um único usuário. No entanto, se você tiver vários apps, o mesmo usuário poderá ter um accountId diferente para cada app, enquanto developerId identificará exclusivamente um único usuário em todos os seus apps.

Não use o ID de desenvolvedor do Google Play Console nem o ID do Google do usuário para esse campo. Além disso, esse campo não pode conter o ID do usuário em texto não criptografado. Recomendamos usar um hash unidirecional para gerar uma string do ID do usuário e armazenar a string com hash nesse campo.

developerId String

String ofuscada opcional que é exclusivamente associada à conta do usuário em todos os seus apps. Esse campo é semelhante a accountId porque representa um único usuário. No entanto, é necessário que esse campo seja comum em todos os seus apps para o mesmo usuário, enquanto accountId pode ser exclusivo por aplicativo, ainda que seja para o mesmo usuário.

Não use o ID de desenvolvedor do Google Play Console nem o ID do Google do usuário para esse campo. Além disso, esse campo não pode conter o ID do usuário em texto não criptografado. Recomendamos usar um hash unidirecional para gerar uma string do ID do usuário e armazenar a string com hash nesse campo.

vr boolean

Especifica se o intent representa o início de um fluxo de compra de realidade virtual (RV).

Observação: para que esse parâmetro extra tenha efeito no seu app, use a AIDL do Google Play Faturamento versão 7 ou uma API mais recente.

Esse método está disponível na versão 6 e mais recentes da AIDL do Google Play Faturamento.

Método getPurchases()

Esse método retorna os produtos não consumidos atuais de posse do usuário, inclusive itens comprados e os adquiridos por resgate de código promocional. A Tabela 11 lista os dados de resposta retornados no Bundle.

Tabela 11. Dados de resposta de uma solicitação getPurchases.

Chave Descrição
RESPONSE_CODE O valor será 0 se a solicitação for bem-sucedida. Caso contrário, ocorrerá um erro.
INAPP_PURCHASE_ITEM_LIST StringArrayList contendo a lista de productIds de compras do app.
INAPP_PURCHASE_DATA_LIST StringArrayList contendo os detalhes das compras feitas no app. Consulte a Tabela 13 para ver informações detalhadas armazenadas em cada item da lista.
INAPP_DATA_SIGNATURE_LIST StringArrayList contendo as assinaturas de compras do app.
INAPP_CONTINUATION_TOKEN String que contém um token de continuação para recuperar o próximo conjunto de produtos no aplicativo que o usuário possui. Isso só será ativado pelo serviço do Google Play se o número de produtos do usuário for muito grande. Quando um token de continuação está presente na resposta, é necessário fazer outra chamada para getPurchases e transmitir o token de continuação recebido. A chamada seguinte do getPurchases retorna mais compras e, possivelmente, outro token de continuação.

Método getPurchaseHistory()

Esse método retorna a compra mais recente feita pelo usuário para cada SKU, mesmo que essa compra tenha expirado, tenha sido cancelada ou consumida. A Tabela 12 lista os dados de resposta retornados no Bundle:

Tabela 12. Dados de resposta de uma solicitação getPurchaseHistory.

Chave Descrição
RESPONSE_CODE O valor será 0 se a solicitação foi bem-sucedida. Caso contrário, ocorrerá um erro.
INAPP_PURCHASE_ITEM_LIST StringArrayList contendo a lista de productIds de compras do app.
INAPP_PURCHASE_DATA_LIST StringArrayList contendo os detalhes das compras recentes do app. Consulte a Tabela 6 para ver informações detalhadas armazenadas em cada item INAPP_PURCHASE_DATA na lista.
INAPP_DATA_SIGNATURE_LIST StringArrayList contendo as assinaturas de compras do app.
INAPP_CONTINUATION_TOKEN String que contém um token de continuação para recuperar o próximo conjunto de produtos no aplicativo que o usuário possui. Isso só será ativado pelo serviço do Google Play se o número de produtos do usuário for muito grande. Quando um token de continuação está presente na resposta, é necessário fazer outra chamada para getPurchases e transmitir o token de continuação recebido. A chamada seguinte do getPurchases retorna mais compras e, possivelmente, outro token de continuação.

Tabela 13. Descrições dos campos JSON para o histórico de compras retornado por getPurchaseHistory().

Campo Descrição
productId O identificador de produto do item. Todo item tem um ID do produto, que você precisa especificar na lista de produtos do aplicativo no Google Play Console.
purchaseTime A hora em que o produto foi comprado, em milissegundos desde a época (1° de janeiro de 1970).
developerPayload Uma string especificada pelo desenvolvedor que contém informações complementares sobre um pedido. É possível especificar um valor para esse campo quando você faz uma solicitação getBuyIntent.
purchaseToken Um token que identifica exclusivamente uma compra para determinado par de item e usuário.

Observação: o método getPurchaseHistory() tem mais sobrecarga do que getPurchases(), porque requer uma chamada para o servidor do Google Play. Use getPurchases() se não precisar do histórico de compras do usuário.

Esse método está disponível na versão 6 e mais recentes da AIDL do Google Play Faturamento.