Usar o sistema de faturamento do Google Play com AIDL

Aviso: a AIDL foi descontinuada e será removida em uma versão futura. Para implementar recursos relacionados ao faturamento, use a Biblioteca Google Play Faturamento.

Você pode usar uma interface de Linguagem de definição de interface do Android (AIDL) para implementar alguns recursos do sistema de faturamento do Google Play.

Comprar produtos

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

Um fluxo de compra típico com a API Google Play Billing AIDL é o seguinte:

1. Seu aplicativo envia uma solicitação isBillingSupported ao Google Play para determinar se há suporte para a versão desejada da API Google Play Billing AIDL que você está usando. A solicitação também verifica se o Google Play tem suporte ao faturamento no país do usuário.
2. Quando o aplicativo é iniciado ou o usuário faz login, é recomendável verificar com o Google Play para determinar quais itens são de propriedade do usuário. Para consultar as compras do usuário, envie uma solicitação 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, é recomendável informar o usuário sobre os produtos que estão disponíveis para compra. Para consultar os detalhes dos produtos no aplicativo que você definiu no Google Play, seu aplicativo pode enviar uma solicitação getSkuDetails. É necessário 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, incluindo preço, título, descrição e tipo de compra.
4. Se o usuário não possuir determinado produto no aplicativo, você poderá iniciar uma compra para ele. Para iniciar uma solicitação de compra, o aplicativo envia uma solicitação getBuyIntent, especificando o ID de produto do item a ser comprado, assim como outros parâmetros. É necessário registrar o ID do produto ao criar um novo produto no aplicativo no Google Play Console.
   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á a intent pendente chamando o método startIntentSenderForResult.
   3. Quando o fluxo de finalização da compra for concluído (ou seja, o usuário comprar com sucesso o item ou cancelar a compra), o Google Play enviará uma resposta Intent ao método onActivityResult. O código de resultado do onActivityResult indica se a compra foi realizada com sucesso ou cancelada. A resposta Intent contém informações sobre o item comprado, incluindo uma string purchaseToken gerada pelo Google Play para identificar de maneira exclusiva essa transação de compra. A Intent também contém a assinatura da compra feita com sua chave de desenvolvedor particular.

Para saber mais sobre as chamadas da API Google Play Billing AIDL e as respostas do servidor, consulte a Referência da API Google Play Billing AIDL.

Consumir produtos no app

É possível usar o mecanismo de consumo para rastrear os produtos gerenciados que o usuário possui.

Todos os produtos gerenciados são administrados na API Google Play Billing AIDL. Isso significa que a propriedade do usuário de todas as compras de produtos gerenciados é mantida pelo Google Play, e seu aplicativo pode consultar as informações de compra do usuário quando necessário. Quando o usuário adquire um produto gerenciado, essa compra é registrada no Google Play. Depois que um produto gerenciado é comprado, ele é considerado “detido”. Os produtos gerenciados no estado "detido" não podem ser comprados no Google Play. É necessário enviar uma solicitação de consumo para o produto gerenciado "detido" antes que o Google Play o disponibilize novamente para compra. O consumo do produto gerenciado o reverte para o estado "não detido" e descarta os dados de compra anteriores.

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

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

Produtos gerenciados que são de consumo ou não

Cabe a você decidir se quer processar seus produtos gerenciados como itens de consumo ou que não são de consumo.

Produtos não consumíveis

Normalmente, o consumo não é implementado para produtos gerenciados que só podem ser comprados uma vez no aplicativo e fornecem um benefício permanente. Depois de comprados, esses produtos são permanentemente associados à Conta do Google do usuário. Um exemplo de produto gerenciado não consumível é um upgrade premium ou um pacote de nível.

Produtos de consumo

Por outro lado, é possível implementar o consumo de produtos que podem ser disponibilizados para compra várias vezes. Normalmente, esses produtos fornecem determinados efeitos temporários. Por exemplo, o personagem no jogo do usuário pode ganhar pontos de vida ou moedas de ouro extras no inventário. O fornecimento dos benefícios ou efeitos do produto adquirido no aplicativo é chamado de provisionamento do produto gerenciado. Você é responsável por controlar e acompanhar o modo como os produtos gerenciados são provisionados para os usuários.

Importante: antes de provisionar o produto gerenciado de consumo no aplicativo, é preciso enviar uma solicitação de consumo ao Google Play e receber uma resposta indicando que o consumo foi registrado.

Gerenciar compras de produtos de consumo no aplicativo

Veja o fluxo básico para comprar um produto gerenciado consumível:

1. Chame o método getBuyIntent para iniciar um fluxo de compra.
2. Inspecione o Bundle retornado no Google Play para determinar se a compra foi concluída.
3. Se a compra tiver sido realizada com sucesso, consuma a compra chamando o método consumePurchase.
4. Inspecione o código de resposta do Google Play para determinar se o consumo foi concluído.
5. Se for o caso, provisione o produto no aplicativo.

Em seguida, quando o usuário inicializar ou fizer login no aplicativo, será preciso verificar se ele possui produtos de consumo internos pendentes. Nesse caso, consuma e provisione esses itens. Veja o fluxo recomendado de inicialização do aplicativo ao implementar produtos de consumo internos:

1. Envie uma solicitação getPurchases para consultar os produtos no aplicativo detidos pelo usuário.
2. Se houver algum produto de consumo no aplicativo, consuma os itens chamando consumePurchase. Essa etapa é necessária porque o aplicativo pode ter concluído a ordem de compra do produto de consumo, mas foi interrompido ou se desconectou antes de conseguir enviar uma solicitação de consumo.
3. Inspecione o código de resposta do Google Play para determinar se o consumo foi concluído.
4. Se for o caso, provisione o produto no aplicativo.

Configurar compras concedidas como prêmios

Alerta: os produtos concedidos como prêmio não são mais compatíveis. Para mais informações, consulte Criar um produto concedido como prêmio.

Ao trabalhar com produtos concedidos como prêmios usando a AIDL, armazene em cache "Intent" de compra antes que um usuário precise coletar o prêmio. Você pode chamar o intent de compra em uma linha de execução em segundo plano e salvar a resposta "Intent" bem-sucedida até que o usuário realize uma ação para coletar a recompensa.

Listar e carregar SKUs

Antes de oferecer um produto concedido como prêmio a um usuário, consiga os detalhes do produto chamando getSkuDetails(). Um novo campo JSON, "rewardToken", é preenchido para cada produto concedido como prêmio na lista de SKUs.

val rewardToken = skuDetailsJson.optString("rewardToken")
val extraParams = Bundle().putString("rewardToken", rewardToken)

// This call blocks the current thread, so do this in the background.
val buyIntentBundle : Bundle = mService.getBuyIntentExtraParams(9, packageName,
        sku, "inapp", "", extraParams)

val response = buyIntentBundle.getInt("RESPONSE_CODE")
if (response == BILLING_RESPONSE_RESULT_OK) {
    // Enable rewarded product.

    // Save this object for use later.
    val pendingIntentToSave = bundle.getParcelable(RESPONSE_BUY_INTENT)
} else {
    // Don't offer rewarded product.
}

String rewardToken = skuDetailsJson.optString("rewardToken");
Bundle extraParams = new Bundle();
extraParams.putString("rewardToken", rewardToken);

// This call blocks the current thread, so do this in the background.
Bundle buyIntentBundle = mService.getBuyIntentExtraParams(9, getPackageName(),
        sku, "inapp", "", extraParams);

int response = buyIntentBundle.getInt("RESPONSE_CODE");
if (response == BILLING_RESPONSE_RESULT_OK) {
    // Enable rewarded product.

    // Save this object for use later.
    PendingIntent pendingIntentToSave = bundle.getParcelable(RESPONSE_BUY_INTENT);
} else {
    // Don't offer rewarded product.
}

Declarar anúncios adequados à idade

Para ajudar a facilitar o cumprimento das obrigações legais relacionadas a crianças e a usuários menores de idade, incluindo a Lei de Proteção da Privacidade On-line das Crianças (COPPA, na sigla em inglês) e o Regulamento geral de proteção de dados (GDPR) (links em inglês), é necessário que seu app declare quais anúncios podem ser tratados como direcionados a crianças nos Estados Unidos e quais são direcionados a usuários que estão abaixo da idade de consentimento aplicável nos respectivos países. A Central de Ajuda da AdMob explica quando é preciso marcar as solicitações de anúncios como tratamento para direcionamento a crianças e quando é preciso serem marcadas como tratamento para usuários abaixo da idade de consentimento, além das consequências de fazer isso.

Para indicar que uma solicitação de recompensa é direcionada a crianças ou usuários abaixo da idade de consentimento, inclua childDirected e underAgeOfConsent como parâmetros extras, conforme mostrado no snippet de código a seguir:

val rewardToken = skuDetailsJson.optString("rewardToken")
val extraParams = Bundle().putString("rewardToken", rewardToken)
        .putInt("childDirected", ChildDirected.CHILD_DIRECTED)
        .putInt("underAgeOfConsent", UnderAgeOfConsent.UNDER_AGE_OF_CONSENT)

// This call blocks the current thread, so do this in the background.
val buyIntentBundle : Bundle = mService.getBuyIntentExtraParams(9, packageName,
        sku, "inapp", "", extraParams)

Bundle extraParams = new Bundle();
extraParams.putString("rewardToken", rewardToken);
extraParams.putInt("childDirected", ChildDirected.CHILD_DIRECTED);
extraParams.putInt("underAgeOfConsent", UnderAgeOfConsent.UNDER_AGE_OF_CONSENT);

// This call blocks the current thread, so do this in the background.
Bundle buyIntentBundle =
  mService.getBuyIntentExtraParams(
    9, getPackageName(), sku, "inapp", "", extraParams);

Mostrar anúncios antes de recompensar o usuário

startIntentSenderForResult(
    pendingIntentToSave,
    RC_BUY, Intent(),
    0,
    0,
    0
)

startIntentSenderForResult(pendingIntentToSave, RC_BUY, new Intent(),
        0, 0, 0);

Depois disso, processe os resultados do fluxo de trabalho de faturamento em onActivityResult(), conforme mostrado nos snippets de código a seguir. Ao gerenciar o processo de exibição de anúncios, o Google Play usa o mesmo conjunto de códigos de resposta do servidor que usa para outros fluxos de faturamento.

fun onActivityResult(requestCode : Int, resultCode : Int, data : Intent) {
    if (requestCode == RC_BUY) {
        int responseCode = data.getIntExtra(RESPONSE_CODE)
        String purchaseData = data.getStringExtra(RESPONSE_INAPP_PURCHASE_DATA)
        String signature = data.getStringExtra(RESPONSE_INAPP_SIGNATURE)

        // Handle reward purchase.
    }
}

public void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == RC_BUY) {
        int responseCode = data.getIntExtra(RESPONSE_CODE);
        String purchaseData = data.getStringExtra(RESPONSE_INAPP_PURCHASE_DATA);
        String signature = data.getStringExtra(RESPONSE_INAPP_SIGNATURE);

        // Handle reward purchase.
    }
}

Armazenamento em cache local

Como o cliente do Google Play agora armazena as informações de faturamento localmente no dispositivo, é possível usar a API Google Play Billing AIDL para consultar essas informações com mais frequência. As seguintes chamadas da API Google Play Billing AIDL são atendidas com pesquisas no cache em vez de exigir uma conexão de rede. Isso acelera significativamente o tempo de resposta da API:

• getBuyIntent
• getPurchases
• isBillingSupported