O Google tem o compromisso de promover a igualdade racial para as comunidades negras. Saiba como.

Referência de AIDL de promoções no aplicativo

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

Esta documentação fornece informações técnicas de referência para a criação de promoções usando a API Google Play Billing AIDL.

Os códigos promocionais permitem dar conteúdo ou recursos a um número limitado de usuários sem gerar custos. Depois de criar um código promocional, você pode distribuí-lo de acordo com os Termos de Serviço. O usuário insere o código promocional no seu app ou no app Google Play Store e recebe o item gratuitamente. Você pode usar códigos promocionais de diversas maneiras para envolver os usuários de forma criativa, como nos exemplos a seguir:

  • Um jogo pode ter um item especial, como um personagem ou uma decoração, que só é disponibilizado a jogadores que participarem de um evento. O desenvolvedor pode distribuir cartões com códigos promocionais no evento, e os usuários só precisam inserir o código para desbloquear o item.
  • Um desenvolvedor de apps pode distribuir códigos promocionais em empresas locais para incentivar possíveis usuários a testar o app.
  • Um desenvolvedor de apps pode dar códigos de família e amigos para que os funcionários dele compartilhem.

Todo código promocional está associado a um determinado ID de produto, também conhecido como SKU. É possível criar códigos promocionais para os produtos internos do app. Você também pode manter um SKU fora da Play Store para que a única forma de conseguir o item seja inserindo o código promocional desse SKU. Quando um usuário insere o código promocional na Play Store ou em um app, ele recebe o item normalmente, como se tivesse pago por ele. Caso seu app já use a versão 3 ou uma versão mais recente da API In-app Billing para oferecer compatibilidade com compras no aplicativo, é fácil adicionar compatibilidade com códigos promocionais.

Como criar e resgatar códigos promocionais

É possível criar códigos promocionais por meio do Google Play Console. Cada código promocional está associado a um único produto registrado no Play Console.

Os usuários podem resgatar códigos promocionais de uma das seguintes maneiras:

  • Inserindo o código como parte do fluxo de compra comum do app, conforme descrito em Como implementar faturamento em apps. Para o app, isso funciona como uma compra comum, mas o usuário paga com um código promocional, e não com dinheiro.
  • O usuário pode resgatar o código no app da Google Play Store. Ele pode digitá-lo manualmente ou você pode gerar um URL para fornecer o código automaticamente na Google Play Store para ele. Para fornecer um código automaticamente, gere e abra um URL com a seguinte estrutura, substituindo <code> pelo código promocional:
    https://play.google.com/redeem?code=<code>
    Veja um exemplo:
    https://play.google.com/redeem?code=bvlkfdxkjghlkgdhlkj
    Para aprender a gerar links para o Google Play a partir de um app para Android, consulte Como vincular ao Google Play. Depois que o código é inserido, a Play Store solicita que o usuário abra o app (se ele tiver a versão mais recente instalada) ou que ele faça o download ou atualize-o.

Como oferecer compatibilidade com códigos promocionais no app

Para oferecer compatibilidade com códigos promocionais, o app precisa chamar o método getPurchases() sempre que for iniciado ou retomado. Esse método retorna um conjunto de todas as compras atuais e não consumidas, inclusive aquelas que o usuário fez resgatando um código promocional. A abordagem mais simples é chamar getPurchases() no método onResume() da sua atividade, já que esse callback é acionado quando a atividade é criada e quando ela é retomada. Chamar getPurchases() na inicialização e na retomada do app garante que ele encontre todas as compras e os resgates que o usuário pode ter feito enquanto o app não estava em execução. Além disso, se um usuário fizer uma compra com o app em execução e ela não for detectada por algum motivo, o app ainda encontrará essa compra na próxima vez que a atividade for retomada e chamar getPurchases().

Seu app precisa permitir que os usuários resgatem códigos promocionais internamente. Se o app é compatível com o fluxo de compra no aplicativo (descrito em Como fazer solicitações de faturamento no aplicativo), ele será automaticamente compatível com o resgate interno de códigos promocionais. Quando você inicia a IU de compra no aplicativo, o usuário tem a opção de pagar pela compra com o método onActivityResult(), que recebe uma intent de resposta informando ao app se a compra foi concluída. Porém, seu app ainda precisa chamar getPurchases() na inicialização e na retomada caso o fluxo de compra e consumo não tenha sido concluído. Por exemplo, se o usuário resgatar um código promocional com sucesso e o app falhar antes de o item ser consumido, ele ainda receberá informações sobre a compra quando chamar getPurchases() na próxima inicialização.

O app também precisa ser compatível com situações em que um usuário resgate um código promocional na Play Store com o app em execução. O aplicativo pode descobrir imediatamente quando o usuário resgata um código promocional, registrando um listener para a intent PURCHASES_UPDATED. A Play Store aciona essa intent sempre que um usuário resgata um código promocional.

Para detectar a intent PURCHASES_UPDATED, crie um objeto BroadcastReceiver dinamicamente e registre-o para detectar com.android.vending.billing.PURCHASES_UPDATED. Registre o receptor inserindo um código semelhante ao seguinte no método onResume() da atividade:

Kotlin

val filter = IntentFilter("com.android.vending.billing.PURCHASES_UPDATED")

Java

IntentFilter filter = new IntentFilter("com.android.vending.billing.PURCHASES_UPDATED");

Quando o usuário faz uma compra, o sistema invoca o método onReceive() do seu broadcast receiver. Esse método precisa chamar getPurchases() para ver as compras que o usuário fez.

Para reduzir a carga sobre o sistema quando o app não está em execução, o método onPause() da sua atividade precisa cancelar o registro do broadcast receiver:

Kotlin

unRegisterReceiver(myPromoReceiver);

Java

unRegisterReceiver(myPromoReceiver);

Observação: não registre esse broadcast receiver no manifesto do app. Declarar o receiver no manifesto pode fazer com que o sistema inicie o app para processar a intent caso o usuário faça uma compra sem que o app esteja em execução. Esse comportamento não é necessário e pode ser irritante para o usuário. Para ter conhecimento das compras que o usuário fez enquanto o app não estava em execução, chame getPurchases() quando o usuário iniciar o app.

Testar promoções no aplicativo

Se seu app for compatível com promoções internas, teste os casos de uso a seguir.

O usuário resgata um código promocional no app

Se o usuário resgatar um código promocional no fluxo de compra do app, conforme descrito em Como fazer solicitações de faturamento no aplicativo, o sistema invocará o método onActivityResult() da sua atividade para processar a compra. Confirme se onActivityResult() processa a compra de maneira adequada, seja o pagamento feito em dinheiro ou com um código promocional.

O usuário resgata um código promocional na Google Play Store

Se o usuário resgatar um código promocional na Play Store, haverá vários fluxos de trabalho possíveis. Verifique cada um desses fluxos.

O aplicativo não está instalado

Se o usuário resgatar o código promocional de um app que não está instalado no dispositivo, a Play Store solicitará a instalação do app. Se o app estiver instalado, mas não atualizado, a Play Store solicitará a atualização. Teste a sequência a seguir em um dispositivo que não tenha seu app instalado.

  1. O usuário resgata um código promocional do aplicativo na Play Store. A Play Store solicita que o usuário instale seu app.
  2. O usuário instala e abre seu app. Confirme se o app chama getPurchases() na inicialização e detecta corretamente a compra que o usuário fez com o código promocional.

O aplicativo está instalado, mas não está em execução

Se o usuário resgatar o código promocional de um app que está instalado no dispositivo, a Play Store solicitará a troca para o app. Teste a sequência a seguir em um dispositivo que tenha seu app instalado, mas não em execução.

  1. O usuário resgata um código promocional do aplicativo na Play Store. A Play Store solicita que o usuário abra seu app em primeiro plano.
  2. O usuário abre seu app. Confirme se o app chama getPurchases() na inicialização e detecta corretamente a compra que o usuário fez com o código promocional.

O aplicativo está instalado e em execução

Se o usuário resgatar um código promocional de um app em execução no dispositivo, a Play Store notificará o app por meio de uma intent PURCHASES_UPDATED. Teste a sequência a seguir:

  1. O usuário abre o app. Confirme se o app se registrou adequadamente para receber a intent PURCHASES_UPDATED.
  2. O usuário abre o app Play Store manualmente ou usando um URL gerado que inclui um código promocional e resgata o código para o app. A Play Store aciona uma intent PURCHASES_UPDATED. Verifique se o callback onReceive() do app é acionado para processar a intent.
  3. Seu método onReceive() precisa chamar getPurchases() para responder à intent. Confirme se o app chama esse método e se detecta corretamente a compra que o usuário fez com o código promocional.
  4. O usuário volta para seu app. Confirme se o usuário possui o item comprado.