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 à Biblioteca Play Faturamento (PBL, na sigla em inglês) e na análise dos motivos de desistência de compra.

Observação: para concluir este codelab, você precisa ter acesso ao recurso Várias opções de compra e ofertas para produtos únicos. Esse recurso está no Programa de acesso antecipado (PAA). Os produtos e recursos no PAA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para acessá-los pelo PAA, envie um pedido usando o formulário de interesse em produtos únicos no PAA (em inglês). No entanto, se você só quiser entender como analisar as desistências de compra usando os códigos de resposta do Play Faturamento, acesse diretamente a seção Analisar as desistências de compra deste codelab.

Público

Este codelab é destinado a desenvolvedores de apps Android que usam a Biblioteca Play Faturamento (PBL) ou querem usar a PBL para monetizar produtos únicos.

O que você vai aprender…

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

O que é necessário…

2. Criar o app de exemplo

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

  • Integração do app com a PBL
  • Buscar produtos únicos
  • Iniciar fluxos de compra para os 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 a aparência e o comportamento do app de exemplo 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 pacote de apps Android assinado do app de exemplo.

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

  1. Fazer 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, a execução do app não busca produtos e preços porque os produtos não foram configurados no Play Console, o que você fará mais adiante neste codelab.
  3. Gere um pacote de apps Android 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 Play Console. Crie um app no Play Console e faça upload do pacote de apps 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 apps assinado do app de exemplo.

Fazer upload do pacote de apps assinado

  1. Faça upload do pacote de apps assinado para a faixa de teste interno do console do Google Play. Somente depois de fazer o upload, você poderá configurar os recursos relacionados à monetização no Play Console.
  2. Clique em Teste e lançamento > 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 único

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 do produto. Insira one_time_product_01.
    • (Opcional) Tags:adicione tags relevantes.
    • Nome:insira um nome do produto. Por exemplo, Product name.
    • Descrição:insira uma descrição do produto. Por exemplo, Product description.
    • (Opcional) Adicionar 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 Impostos, conformidade e programas.
  4. Clique em Próxima.
  5. Adicione uma opção de compra e configure a disponibilidade regional. 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 a essa opção de compra.
    • (Opcional) Clique em Opções avançadas para configurar as opções avançadas. Para fins deste codelab, você pode pular a configuração de 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. Isso abre uma caixa de diálogo para inserir um preço. Insira US$ 10 e clique em Aplicar.
  9. Clique em Salvar e em Ativar. Isso cria e ativa a opção de compra.

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

  • 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, será necessário modificar o app de exemplo para usar o ID do 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 de criação de produtos únicos

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

4. Integrar com a PBL

Agora, vamos mostrar 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 das etapas. Você pode usar esses snippets como orientação para implementar sua integração real.

Para integrar seu app à PBL, siga estas etapas:

  1. Adicione a dependência da Biblioteca 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 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 se conectar ao Google Play.
    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. Busque os detalhes do produto único.Depois de integrar seu app à PBL, você precisa buscar os detalhes do produto único no app. O snippet de código a seguir mostra como buscar os detalhes do produto único no app.
    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);
      }
    });
}
    A busca de ProductDetails oferece 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. Detecte e processe compras. Como parte desta etapa, você precisa:
    1. Verificar a compra
    2. Conceder o direito de acesso ao usuário
    3. Notificar o usuário
    4. Notificar o Google sobre o processo de compra
    Destas, as etapas a, b e c precisam ser feitas no 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 as desistências de compra

Até agora no codelab, as respostas do Play Faturamento se concentraram em cenários limitados, como respostas 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 a preços.
  • A compra está pendente ou o pagamento foi recusado.

Código de erro de resposta BILLING_UNAVAILABLE

Esse código de resposta significa que a compra não pôde ser concluída 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 o usuário está em um país não aceito. Esse código não indica um erro no próprio sistema do Play Faturamento.

Causas prováveis

Quais ações você pode realizar?

  • O app Google Play Store no dispositivo do usuário está desatualizado.
  • O usuário está em um país em que o Google Play não é aceito.
  • 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, já que ela oferece suporte ao 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 projetado para novas tentativas, permitindo que você implemente estratégias adequadas de nova tentativa.
    É 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 Google 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 nova tentativa para códigos de erro de resposta

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

Para erros encontrados quando o usuário está em sessão, é recomendável 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 o reconhecimento 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 no 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.