Register now for Android Dev Summit 2019!

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 ao 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 manipular 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 posterior da AIDL do Google Play Faturamento.

Método isBillingSupportedExtraParams()

Este método é idêntico a isBillingSupported(), exceto que você pode 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. Esse sinalizador 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 posteriores da AIDL do Google Play Faturamento.

Detalhes da referência de AIDL do Google Play Faturamento

A AIDL do Google Play Faturamento é definida no arquivo IInAppBillingService.aidl, incluído no aplicativo de exemplo da versão 3.

Método getSkuDetails()

Use o método getSkuDetails() para obter 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 com 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 de 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 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 da moeda ISO 4217 para price. Por exemplo, se price for especificado em libras esterlinas, 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 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 impostos.

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 a chave RESPONSE_CODE, bem como um PendingIntent para iniciar o fluxo de compra para o item no aplicativo mapeado para a chave BUY_INTENT, conforme descrito em Implementar o Google Play Faturamento. Quando recebe o PendingIntent, o Google Play envia uma resposta Intent com os dados para a 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 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 for true, a assinatura está ativa e será renovada automaticamente na próxima data de faturamento. Se for false, indica que o usuário cancelou a assinatura. O usuário tem acesso ao conteúdo da assinatura até a próxima data de faturamento e perderá o acesso nesse momento, a menos que reative a renovação automática (ou renove 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. Você poderá especificar um valor para esse campo quando fizer 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 falha.

Método getBuyIntentToReplaceSkus()

Esse método é usado para fazer upgrade ou downgrade de uma compra de assinatura. O método é semelhante a getBuyIntent(), mas adquire uma lista com exatamente um SKU já comprado, a 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 rateada. 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 reportado, 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, bem como um PendingIntent para iniciar o fluxo de compra para o item no aplicativo mapeado para a chave BUY_INTENT, conforme descrito em Implementar o Google Play Faturamento. Quando recebe o PendingIntent, o Google Play envia uma resposta Intent com os dados para a 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. Ele é uma variante do método getBuyIntent() e recebe um parâmetro extraParams extra. Esse parâmetro é um Bundle de chaves e valores opcionais que afetam o funcionamento 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 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 skusToReplace.

accountId String

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

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

Não use o código de desenvolvedor do Google Play Console ou o código 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 accountId, porque representa um único usuário. No entanto, esse campo precisa ser comum em todos os seus apps para o mesmo usuário, enquanto o accountId pode ser exclusivo por app, mesmo para o mesmo usuário.

Não use o código de desenvolvedor do Google Play Console ou o código 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 posteriores 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 que são 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 que contém a lista de IDs de produto de compras nesse aplicativo.
INAPP_PURCHASE_DATA_LIST StringArrayList que contém os detalhes das compras nesse app. Consulte a tabela 13 para ver a lista de informações detalhadas armazenadas em cada item da lista.
INAPP_DATA_SIGNATURE_LIST StringArrayList que contém as assinaturas de compras nesse 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 estiver presente na resposta, faça outra chamada para getPurchases e transmita o token de continuação recebido. A chamada getPurchases subsequente 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 que são 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 que contém a lista de IDs de produto de compras nesse aplicativo.
INAPP_PURCHASE_DATA_LIST StringArrayList que contém os detalhes de compras recentes nesse aplicativo. Consulte a tabela 6 para ver a lista de informações detalhadas armazenadas em cada item INAPP_PURCHASE_DATA na lista.
INAPP_DATA_SIGNATURE_LIST StringArrayList que contém as assinaturas de compras nesse 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 estiver presente na resposta, faça outra chamada para getPurchases e transmita o token de continuação recebido. A chamada getPurchases subsequente 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. Você poderá especificar um valor para esse campo quando fizer 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 exige uma chamada para o servidor do Google Play. Use getPurchases() se você não precisa do histórico de compras do usuário.

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