Analisar desistências de compra de produtos no Play Faturamento

1. Introdução

Neste codelab, você vai se concentrar na criação de um produto único, na integração do app com a Biblioteca Play Faturamento (PBL) e na análise dos motivos para a queda nas compras.

Público

Este codelab é destinado a desenvolvedores de apps Android que usam a Biblioteca Play Faturamento (PBL, na sigla em inglês) ou querem usá-la para monetizar produtos únicos.

O que você vai aprender…

  • Como criar produtos únicos no Google Play Console.
  • Como integrar seu app com a PBL.
  • Como processar compras de produtos únicos consumíveis e não consumíveis na PBL.
  • Como analisar desistências de compra.

O que é necessário…

2. Criar o app de amostra

O app de exemplo foi projetado para ser um app Android totalmente funcional com o código-fonte completo que mostra os seguintes aspectos:

  • Integrar o app com o PBL
  • Buscar produtos únicos
  • Iniciar fluxos de compra para produtos únicos
  • Cenários de compra que levam às seguintes respostas de faturamento:
    • BILLING_UNAVAILABLE
    • USER_CANCELLED
    • OK
    • ITEM_ALREADY_OWNED

O vídeo de demonstração a seguir mostra como o app de exemplo vai aparecer e se comportar depois de implantado e executado.

Pré-requisitos

Antes de criar e implantar o app de exemplo, faça o seguinte:

Criar

O objetivo desta etapa de build é gerar um arquivo de Android App Bundle assinado do app de exemplo.

Para gerar o pacote de apps Android, siga estas etapas:

  1. Faça o download do app de exemplo no GitHub.
  2. Crie o app de exemplo. Antes de criar, mude o nome do pacote do app de exemplo e crie. Se você tiver pacotes de outros apps no Play Console, verifique se o nome do pacote fornecido para o app de exemplo é exclusivo.

    Observação: a criação do app de exemplo gera apenas um arquivo APK que pode ser usado para testes locais. No entanto, executar o app não busca produtos e preços porque eles não foram configurados no Play Console, o que você fará mais adiante neste codelab.
  3. Gere um Android App Bundle assinado.
    1. Gerar uma chave de upload e um keystore
    2. Assinar seu app com a chave de upload
    3. Configurar a Assinatura de apps do Google Play

A próxima etapa é fazer upload do pacote de apps Android para o Google Play Console.

3. Criar um produto único no Play Console

Para criar produtos únicos no Google Play Console, você precisa ter um app no console. Crie um app no Play Console e faça upload do pacote de app assinado criado anteriormente.

Criar um app

Para criar um app:

  1. Faça login no Google Play Console usando sua conta de desenvolvedor.
  2. Clique em Criar app. A página Criar app será aberta.
  3. Insira um nome de app, selecione o idioma padrão e outros detalhes relacionados ao app.
  4. Clique em Criar app. Isso cria um app no Google Play Console.

Agora você pode fazer upload do pacote de app assinado do app de exemplo.

Fazer upload do pacote de apps assinado

  1. Faça upload do pacote de app assinado para a faixa de teste interno do Google Play Console. Só depois do upload é possível configurar os recursos relacionados à monetização no Play Console.
  2. Clique em Testar e lançar > Teste > Versão interna > Criar versão.
  3. Insira um nome de versão e faça upload do arquivo do pacote de apps assinado.
  4. Clique em Próxima e em Salvar e publicar.

Agora você pode criar seus produtos únicos.

Criar um produto de aquisição única

Para criar um produto único:

  1. No Google Play Console, no menu de navegação à esquerda, acesse Monetizar com o Google Play > Produtos > Produtos únicos.
  2. Clique em Criar um produto único.
  3. Insira os seguintes detalhes do produto:
    • ID do produto:insira um ID exclusivo. Insira one_time_product_01.
    • (Opcional) Tags:adicione tags relevantes.
    • Nome:insira um nome para o produto. Por exemplo, Product name.
    • Descrição:insira uma descrição do produto. Por exemplo, Product description.
    • (Opcional) Adicione uma imagem de ícone:faça upload de um ícone que represente seu produto.
    Observação: para fins deste codelab, você pode pular a configuração da seção Tributos, compliance e programas.
  4. Clique em Próxima.
  5. Adicione uma opção de compra e configure a disponibilidade regional dela. Um produto único precisa de pelo menos uma opção de compra, que define como o direito de acesso é concedido, o preço e a disponibilidade regional. Para este codelab, vamos adicionar a opção padrão Comprar para o produto.Na seção Opção de compra, insira os seguintes detalhes:
    • ID da opção de compra:insira um ID de opção de compra. Por exemplo, buy.
    • Tipo de compra:selecione Comprar.
    • (Opcional) Tags:adicione tags específicas para essa opção de compra.
    • (Opcional) Clique em Opções avançadas para configurar as opções avançadas. Para os fins deste codelab, ignore a configuração das opções avançadas.
  6. Na seção Disponibilidade e preços, clique em Definir preços > Editar preços em massa.
  7. Selecione a opção País / região. Isso seleciona todas as regiões.
  8. Clique em Continuar. Uma caixa de diálogo será aberta para inserir um preço. Digite 10 USD e clique em Aplicar.
  9. Clique em Salvar e depois em Ativar. Isso cria e ativa a opção de compra.

Para os fins deste codelab, crie mais três produtos únicos com os seguintes IDs:

  • consumable_product_01
  • consumable_product_02
  • consumable_product_03

O app de exemplo está configurado para usar esses IDs de produto. Você pode fornecer IDs de produtos diferentes. Nesse caso, é necessário modificar o app de exemplo para usar o ID de produto fornecido.

Abra o app de exemplo no Google Play Console e acesse Monetizar com o Google Play > Produtos > Produtos únicos. Em seguida, clique em Criar um produto único e repita as etapas de 3 a 9.

Vídeo sobre a criação de produtos únicos

O vídeo de exemplo a seguir mostra as etapas de criação única de produtos descritas anteriormente.

4. Integrar com o PBL

Agora, vamos ver como integrar seu app à Biblioteca Play Faturamento (PBL). Esta seção descreve as etapas de alto nível para integração e fornece um snippet de código para cada uma delas. Use esses snippets como orientação para implementar sua integração real.

Para integrar seu app ao PBL, siga estas etapas:

  1. Adicione a dependência da Biblioteca Google Play Faturamento ao app de exemplo.
    dependencies {
val billing_version = "8.0.0"

implementation("com.android.billingclient:billing-ktx:$billing_version")
}
  2. Inicialize o BillingClient. O BillingClient é o SDK do cliente que reside no seu app e se comunica com a Biblioteca Google Play Faturamento. O snippet de código a seguir mostra como inicializar o cliente de faturamento.
    protected BillingClient createBillingClient() {
return BillingClient.newBuilder(activity)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build())
    .enableAutoServiceReconnection()
    .build();
}
  3. Conecte-se ao Google Play.O snippet de código a seguir mostra como fazer isso.
    public void startBillingConnection(ImmutableList<Product> productList) {
Log.i(TAG, "Product list sent: " + productList);
Log.i(TAG, "Starting connection");
billingClient.startConnection(
    new BillingClientStateListener() {
      @Override
      public void onBillingSetupFinished(BillingResult billingResult) {
        if (billingResult.getResponseCode() == BillingResponseCode.OK) {
          // Query product details to get the product details list.
          queryProductDetails(productList);
        } else {
          // BillingClient.enableAutoServiceReconnection() will retry the connection on
          // transient errors automatically.
          // We don't need to retry on terminal errors (e.g., BILLING_UNAVAILABLE,
          // DEVELOPER_ERROR).
          Log.e(TAG, "Billing connection failed: " + billingResult.getDebugMessage());
          Log.e(TAG, "Billing response code: " + billingResult.getResponseCode());
        }
      }

      @Override
      public void onBillingServiceDisconnected() {
        Log.e(TAG, "Billing Service connection lost.");
      }
    });
}
  4. Extraia os detalhes do produto único.Depois de integrar o app ao PBL, você precisa extrair os detalhes do produto único para o app. O snippet de código a seguir mostra como fazer isso.
    private void queryProductDetails(ImmutableList<Product> productList) {
Log.i(TAG, "Querying products for: " + productList);
QueryProductDetailsParams queryProductDetailsParams =
    QueryProductDetailsParams.newBuilder().setProductList(productList).build();
billingClient.queryProductDetailsAsync(
    queryProductDetailsParams,
    new ProductDetailsResponseListener() {
      @Override
      public void onProductDetailsResponse(
          BillingResult billingResult, QueryProductDetailsResult productDetailsResponse) {
        // check billingResult
        Log.i(TAG, "Billing result after querying: " + billingResult.getResponseCode());
        // process returned productDetailsList
        Log.i(
            TAG,
            "Print unfetched products: " + productDetailsResponse.getUnfetchedProductList());
        setupProductDetailsMap(productDetailsResponse.getProductDetailsList());
        billingServiceClientListener.onProductDetailsFetched(productDetailsMap);
      }
    });
}
    Ao buscar ProductDetails, você recebe uma resposta semelhante a esta:
    {
    "productId": "consumable_product_01",
    "type": "inapp",
    "title": "Shadow Coat (Yolo's Realm | Play Samples)",
    "name": "Shadow Coat",
    "description": "A sleek, obsidian coat for stealth and ambushes",
    "skuDetailsToken": "<---skuDetailsToken--->",
    "oneTimePurchaseOfferDetails": {},
    "oneTimePurchaseOfferDetailsList": [
        {
            "priceAmountMicros": 1990000,
            "priceCurrencyCode": "USD",
            "formattedPrice": "$1.99",
            "offerIdToken": "<--offerIdToken-->",
            "purchaseOptionId": "buy",
            "offerTags": []
        }
    ]
},
{
    "productId": "consumable_product_02",
    "type": "inapp",
    "title": "Emperor Den (Yolo's Realm | Play Samples)",
    "name": "Emperor Den",
    "description": "A fair lair glowing with molten rock and embers",
    "skuDetailsToken": "<---skuDetailsToken--->",
    "oneTimePurchaseOfferDetails": {},
    "oneTimePurchaseOfferDetailsList": [
        {
            "priceAmountMicros": 2990000,
            "priceCurrencyCode": "USD",
            "formattedPrice": "$2.99",
            "offerIdToken": "<--offerIdToken-->",
            "purchaseOptionId": "buy",
            "offerTags": []
        }
    ]
}
  5. Inicie o fluxo de faturamento.
    public void launchBillingFlow(String productId) {
ProductDetails productDetails = productDetailsMap.get(productId);
if (productDetails == null) {
  Log.e(
      TAG, "Cannot launch billing flow: ProductDetails not found for productId: " + productId);
  billingServiceClientListener.onBillingResponse(
      BillingResponseCode.ITEM_UNAVAILABLE,
      BillingResult.newBuilder().setResponseCode(BillingResponseCode.ITEM_UNAVAILABLE).build());
  return;
}
ImmutableList<ProductDetailsParams> productDetailsParamsList =
    ImmutableList.of(
        ProductDetailsParams.newBuilder().setProductDetails(productDetails).build());

BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        .build();

billingClient.launchBillingFlow(activity, billingFlowParams);
}
  6. Detectar e processar compras. Nesta etapa, você precisa:
    1. Verificar a compra
    2. Conceder direito ao usuário
    3. Notificar o usuário
    4. Notificar o Google sobre o processo de compra
    As etapas a, b e c precisam ser feitas no seu back-end e, portanto, estão fora do escopo deste codelab.O snippet a seguir mostra como notificar o Google sobre um produto único consumível:
    private void handlePurchase(Purchase purchase) {
// Step 1: Send the purchase to your secure backend to verify the purchase following
// https://developer.android.com/google/play/billing/security#verify

// Step 2: Update your entitlement storage with the purchase. If purchase is
// in PENDING state then ensure the entitlement is marked as pending and the
// user does not receive benefits yet. It is recommended that this step is
// done on your secure backend and can combine in the API call to your
// backend in step 1.

// Step 3: Notify the user using appropriate messaging.
if (purchase.getPurchaseState() == PurchaseState.PURCHASED) {
  for (String product : purchase.getProducts()) {
    Log.d(TAG, product + " purchased successfully! ");
  }
}

// Step 4: Notify Google the purchase was processed.
// For one-time products, acknowledge the purchase.
// This sample app (client-only) uses billingClient.acknowledgePurchase().
// For consumable one-time products, consume the purchase
// This sample app (client-only) uses billingClient.consumeAsync()
// If you have a secure backend, you must acknowledge purchases on your server using the
// server-side API.
// See https://developer.android.com/google/play/billing/security#acknowledge
if (purchase.getPurchaseState() == PurchaseState.PURCHASED && !purchase.isAcknowledged()) {

  if (shouldConsume(purchase)) {
    ConsumeParams consumeParams =
        ConsumeParams.newBuilder().setPurchaseToken(purchase.getPurchaseToken()).build();
    billingClient.consumeAsync(consumeParams, consumeResponseListener);

  } else {
    AcknowledgePurchaseParams acknowledgePurchaseParams =
        AcknowledgePurchaseParams.newBuilder()
            .setPurchaseToken(purchase.getPurchaseToken())
            .build();
    billingClient.acknowledgePurchase(
        acknowledgePurchaseParams, acknowledgePurchaseResponseListener);
  }
 }
}

5. Analisar desistências de compra

Até agora, no codelab, as respostas do Play Faturamento se concentraram em cenários limitados, como USER_CANCELLED, BILLING_UNAVAILABLE, OK e ITEM_ALREADY_OWNED. No entanto, o Play Faturamento pode retornar 13 códigos de resposta diferentes, que podem ser acionados por vários fatores do mundo real.

Esta seção detalha as causas das respostas de erro USER_CANCELLED e BILLING_UNAVAILABLE e sugere possíveis ações corretivas que podem ser implementadas.

Código de erro de resposta USER_CANCELED

Esse código de resposta indica que o usuário abandonou a interface do fluxo de compra antes de concluir a compra.

Causas prováveis

Quais ações você pode realizar?

  • Pode indicar usuários com baixa intenção que são sensíveis aos preços.
  • A compra está pendente ou o pagamento foi recusado.

Código de erro da resposta BILLING_UNAVAILABLE

Esse código de resposta significa que não foi possível concluir a compra devido a um problema com o provedor de pagamento do usuário ou a forma de pagamento escolhida. Por exemplo, o cartão de crédito do usuário expirou ou ele está em um país sem suporte. Esse código não indica um erro com o próprio sistema de faturamento do Google Play.

Causas prováveis

Quais ações você pode realizar?

  • O app Play Store no dispositivo do usuário está desatualizado.
  • O usuário está em um país onde o Google Play não está disponível.
  • Esse é um usuário corporativo, e o administrador dele desativou a possibilidade de usuários fazerem compras.
  • O Google Play não consegue fazer a cobrança na forma de pagamento do usuário. Por exemplo, o cartão de crédito do usuário pode ter expirado.
  • Monitore as tendências de problemas do sistema e em regiões específicas
  • Considere migrar para a PBL 8, que aceita o código de subresposta PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS mais granular. Se você receber esse código de resposta, considere notificar os usuários sobre a falha ou sugerir formas de pagamento alternativas.
  • Esse código de resposta foi criado para novas tentativas, permitindo que você implemente estratégias adequadas.
    É improvável que novas tentativas automáticas ajudem neste caso. No entanto, uma nova tentativa manual pode ajudar se o usuário resolver a condição que causou o problema. Por exemplo, se o usuário atualizar a Play Store para uma versão com suporte, uma nova tentativa manual da operação inicial poderá funcionar.

    Se você receber esse código de resposta quando o usuário não estiver em sessão, é possível que a nova tentativa não faça sentido. Quando você recebe uma resposta "BILLING_UNAVAILABLE" como resultado do fluxo de compra, é muito provável que o usuário tenha recebido feedback do Google Play durante o processo de compra e esteja ciente do que deu errado. Nesse caso, você pode mostrar uma mensagem de erro especificando que algo deu errado e incluir um botão "Tente de novo" para dar ao usuário a opção de uma nova tentativa manual depois de resolver o problema.

Estratégias de repetição para códigos de erro de resposta

As estratégias de nova tentativa eficazes para erros recuperáveis da Biblioteca Play Faturamento (PBL) variam de acordo com o contexto, como interações do usuário na sessão (durante uma compra) em vez de operações em segundo plano (como consultas de compras na retomada do app). É importante implementar essas estratégias porque alguns valores de BillingResponseCode significam problemas temporários que podem ser resolvidos com novas tentativas, enquanto outros são permanentes e não exigem novas tentativas.

Para erros encontrados quando o usuário está em sessão, é recomendável usar uma estratégia de nova tentativa simples com um número máximo de tentativas definido para minimizar a interrupção da experiência do usuário. Por outro lado, para operações em segundo plano, como confirmação de novas compras, que não exigem execução imediata, a espera exponencial é a abordagem recomendada.

Para informações detalhadas sobre códigos de resposta específicos e as estratégias de nova tentativa recomendadas correspondentes, consulte Processar códigos de resposta de BillingResult.

6. Próximas etapas

Documentos de referência

7. Parabéns!

Parabéns! Você navegou com sucesso pelo Google Play Console para criar um novo produto único, testar códigos de resposta de faturamento e analisar as desistências de compra.

Pesquisa

Seu feedback sobre este codelab é muito importante. Reserve alguns minutos para responder à nossa pesquisa.