Aviso: a AIDL agora está suspensa e será removida em uma versão futura. Para implementar os recursos de faturamento do Google Play, use a biblioteca do Google Play Faturamento.
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 a seguir 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 gerenciar 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 | Sucesso |
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 à API. Esse erro também pode indicar que o aplicativo não foi assinado corretamente ou configurado de maneira adequada para 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 foi adquirido |
Referência de AIDL do Google Play Faturamento: compatibilidade
Esta seção descreve métodos para conseguir informações sobre os tipos de compatibilidade de 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 sistema de faturamento do Google Play está ativado no pacote do 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.
|
Esse 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 sistema de faturamento do Google Play compatível com o app. Esse pacote pode conter uma chave opcional chamada |
Esse método está disponível na versão 7 e mais recentes da AIDL do Google Play Faturamento.
Referência de AIDL do Google Play Faturamento: detalhes
A AIDL do Google Play Faturamento está definida no
arquivo IInAppBillingService.aidl,
que está incluído na versão 3 do
app de exemplo.
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
estão 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 equivalem 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 equivale a três meses, P6M equivale a seis meses e P1Y equivale a um ano.
Observação: retornado apenas para assinaturas. |
freeTrialPeriod |
Período de teste 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 teste gratuito, consulte Assinaturas no aplicativo.
Observação: retornado apenas para assinaturas que têm um período de teste configurado. |
introductoryPrice |
Preço inicial 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 têm um período inicial configurado. |
introductoryPriceAmountMicros |
Preço inicial em microunidades. A moeda é igual a price_currency_code.
Observação: retornado apenas para assinaturas que têm um período inicial 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 inicial configurado. |
introductoryPriceCycles |
O número de períodos de faturamento da assinatura para os quais o usuário receberá o preço inicial, como 3.
Observação: retornado apenas para assinaturas que têm um período inicial configurado. |
Método getBuyIntent()
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 o item no
aplicativo mapeado para a chave BUY_INTENT, conforme descrito em Como 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 6.
Observação: em vez desse método, recomendamos o uso
de getBuyIntentExtraParams(), que
oferece outras funcionalidades.
Tabela 6. Dados de resposta de uma solicitação de compra do Google Play.
| 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
oferece outras funcionalidades.
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 uma
PendingIntent para iniciar o fluxo de compra para a assinatura no aplicativo
mapeada para a chave BUY_INTENT. Quando receber a
PendingIntent, o Google Play
enviará uma Intent de resposta com os dados da ordem de compra.
Os dados retornados na Intent de resposta 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 proporcionando o upgrade ou downgrade da assinatura já 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 deve 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 verdadeiro, o Google Play substituirá os SKUs antigos e creditará ao usuário o valor não utilizado do tempo de assinatura de maneira rateada. O Google Play aplica esse crédito à nova assinatura e não começa a cobrar o usuário pela nova assinatura 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 |
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 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 código do usuário em texto não criptografado. Recomendamos usar um hash unidirecional para gerar uma string a partir do código 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 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 código do usuário em texto não criptografado. Recomendamos usar um hash unidirecional para gerar uma string a partir do código 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 versões 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 foi bem-sucedida. Caso contrário, ocorrerá um erro. |
INAPP_PURCHASE_ITEM_LIST |
StringArrayList contendo a lista de productIds de compras deste app. |
INAPP_PURCHASE_DATA_LIST |
StringArrayList contendo os detalhes das compras feitas a partir deste 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 deste app. |
INAPP_CONTINUATION_TOKEN |
String que contém um token de continuação para recuperar o próximo conjunto de produtos no aplicativo de posse do usuário. 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 sido cancelada, consumida ou estiver expirada. 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 tiver sido bem-sucedida. Caso contrário, ocorrerá um erro.
|
INAPP_PURCHASE_ITEM_LIST |
StringArrayList contendo a lista de productIds de compras deste app. |
INAPP_PURCHASE_DATA_LIST |
StringArrayList contendo os detalhes das compras recentes deste 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 deste app. |
INAPP_CONTINUATION_TOKEN |
String que contém um token de continuação para recuperar o próximo conjunto de produtos no aplicativo de posse do usuário. 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 versões mais recentes da AIDL do Google Play Faturamento.