Esta página foi traduzida pela API Cloud Translation.

Adicionar ofertas de compra na pré-venda para produtos únicos

1. Introdução

Neste codelab, você vai se concentrar na criação de um produto único (OTP, na sigla em inglês) e adicionar uma oferta de pré-venda a ele.

Observação: antes de iniciar este codelab, preencha o formulário de interesse em produtos únicos no PAA para solicitar acesso ao recurso de pré-venda.

Público

Este codelab é destinado a desenvolvedores de apps Android que conhecem os produtos únicos e querem entender como adicionar ofertas de pré-venda a eles.

Pré-requisito

Se você não conhece os produtos únicos, recomendamos que conclua o codelab Desbloquear novos mercados com preços regionais de produtos.

O que você vai aprender…

Como usar o Google Play Console para criar ofertas de pré-venda dos seus produtos únicos.
Como usar as APIs da Biblioteca do Google Play Faturamento para consultar produtos únicos e os detalhes da oferta de pré-venda correspondente.

O que é necessário…

Acesso ao Google Play Console com uma conta de desenvolvedor. Se você não tiver uma conta de desenvolvedor, crie uma.
Um app de exemplo para este codelab, que pode ser baixado do GitHub.
Android Studio.

2. Criar o app de amostra

Este codelab usa um app Android de exemplo para ensinar a gerenciar produtos únicos. O app de exemplo foi projetado para ser um app Android totalmente funcional com o código-fonte completo que mostra os seguintes aspectos:

Integre o app com a PBL.
Busca de produtos únicos e das ofertas de pré-venda relacionadas.
Executar fluxos de compra para preços regionais.

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

Se você já conhece os produtos únicos e a Biblioteca Play Faturamento (PBL), faça o download do app de exemplo e teste.

Pré-requisitos

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

Crie uma conta de desenvolvedor do Google Play Console. Se você já tiver uma conta de desenvolvedor, pule esta etapa.
Crie um app no Play Console. Ao criar um app, você pode especificar qualquer nome para o app de exemplo.
Instale o Android Studio.

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:

Faça o download do app de exemplo no GitHub.
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 eles não foram configurados no Play Console.
Gere um Android App Bundle assinado.

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

3. Criar uma OTP com pré-venda no Play Console

Para criar produtos únicos (OTP) 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:

Faça login no Google Play Console usando sua conta de desenvolvedor.
Clique em Criar app. Isso abre a página Criar app.
Insira um nome de app, selecione o idioma padrão e outros detalhes relacionados ao app.
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

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

Agora, você pode criar os produtos únicos.

Criar um produto de aquisição única

Agora, crie o produto único que você quer que os usuários comprem.

Abra o app de exemplo no Google Play Console e acesse Monetizar com o Google Play > Produtos > Produtos únicos.
Clique em Criar um produto único.
Insira os seguintes detalhes do produto:
- ID do produto:insira um ID exclusivo. Por exemplo, upcoming_movie_1.
- (Opcional) Tags:adicione tags relevantes.
- Nome:insira um nome para o produto. Por exemplo, Product Movie.
- 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 os fins deste codelab, você pode pular a configuração da seção Tributos, compliance e programas.
Clique em Próxima.
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 exclusivo. Por exemplo, buy-movie.
- 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.
Em seguida, configure a disponibilidade e o preço regional para a opção de compra. Na disponibilidade regional, especifique as regiões em que seu produto está disponível, incluindo aquelas em que o app ainda não foi publicado. Por padrão, uma opção de compra fica disponível em todas as regiões.Na seção Disponibilidade e preços, clique em Editar disponibilidade e acesso.
1. Selecione Definir como indisponível.
Todas as regiões são selecionadas automaticamente e definidas como Disponível.
1. Desmarque apenas o país United States e clique em Definir como indisponível. Agora, o produto único vai estar disponível apenas no United States.
2. No menu suspenso Todas as regiões, selecione Países e regiões disponíveis. Você verá apenas United States.
3. Clique no ícone Preço. Uma caixa de diálogo para definir o preço vai aparecer.
4. Insira 10 USD e clique em Salvar.
Clique em Salvar como rascunho.

Observação: não ative a opção de compra ainda. Vamos ativar depois de configurar a oferta de compra na pré-venda. Isso acontece porque não é possível adicionar uma oferta de pré-venda a uma opção de compra ativa com disponibilidade regional definida.

Adicionar uma oferta de compra na pré-venda

Agora, adicione uma oferta de pré-venda à opção de compra que você criou anteriormente. Com uma oferta de pré-venda, os usuários podem comprar seu item antes do lançamento oficial. As ofertas de pré-venda são compatíveis apenas com a opção de compra Comprar e só podem ser configuradas para produtos novos em uma região.

Adicionar uma oferta de compra na pré-venda envolve as seguintes duas etapas:

Prepare a opção de compra Comprar para a oferta de pré-venda.
Adicione a oferta de compra na pré-venda à opção de compra.

Prepare a opção de compra "Comprar" para a oferta de pré-venda

Abra o app de exemplo no Google Play Console e acesse Monetizar com o Google Play > Produtos > Produtos únicos.
Na página Produtos únicos, clique na seta para a direita do produto (upcoming_movie_1). A página Editar produto único será aberta.
Clique na seta para a direita da opção de compra buy-movie que você criou anteriormente. A página Editar opção de compra será aberta.
Clique em Editar disponibilidade e acesso e selecione Definir como disponível e permitir que os usuários comprem na pré-venda.
No menu suspenso Todas as regiões, selecione Países e regiões disponíveis. Isso deve mostrar apenas United States que você configurou anteriormente.
Selecione o país e clique em Definir como disponível apenas para pré-venda.
Clique em Salvar.

Você ainda não adicionou uma oferta de pré-venda à opção de compra. A próxima etapa é adicionar a oferta de compra na pré-venda.

Adicionar uma oferta de compra na pré-venda

Abra o app de exemplo no Google Play Console e acesse Monetizar com o Google Play > Produtos > Produtos únicos.
Na página Produtos únicos, clique em Adicionar oferta > Pré-venda no seu produto (upcoming_movie_1). A página Adicionar pré-venda será aberta.
Insira os detalhes da pré-venda:
- ID da pré-venda:insira preorder-offer-1.
- (Opcional) Adicione um desconto:você pode selecionar Nenhum, Porcentagem ou Absoluto. Para este codelab, selecione Nenhum.
- (Opcional) Tags:adicione tags relevantes.
- Data e hora de início:defina uma data daqui a pelo menos três dias.
- Data e hora de término:defina uma data pelo menos 24 horas após a data de início.
- Disponibilidade após a pré-venda:escolha se o produto vai ficar disponível imediatamente após o período de pré-venda ou em uma data/hora específica posterior.
- (Opcional) Garantia de menor preço:selecione essa opção se quiser que os usuários paguem o menor preço entre o valor da pré-venda e o preço no lançamento. Isso pode ser um incentivo forte para os compradores antecipados.
Clique em Salvar.
Abra a página Editar produto único para seu produto único (upcoming_movie_1).
Clique em Ativar na opção de compra (buy-movie).
Clique em Ativar na oferta de pré-venda (preorder-offer-1) na opção de compra. Isso ativa a oferta de pré-venda e a disponibiliza na data que você configurou nos detalhes da pré-venda.

Vídeo sobre como criar uma oferta de pré-venda

O vídeo a seguir mostra as etapas de criação de oferta de pré-venda descritas anteriormente.

4. Integrar com o PBL

Para integrar seu app à Biblioteca Play Faturamento (PBL), siga estas etapas:

Adicione a dependência da Biblioteca Google Play Faturamento ao app de exemplo.

dependencies {
val billing_version = "8.1.0"

implementation("com.android.billingclient:billing-ktx:$billing_version")
}

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.

private BillingClient createBillingClient() {
return BillingClient.newBuilder(activity)
    .enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build())
    // For one-time products, add a listener to process and acknowledge the purchases. This will notify
    // Google the purchase was processed.
    // For client-only apps, use billingClient.acknowledgePurchase().
    // 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
    // In this sample snippet purchases aren't processed. You must
    // implement your business logic to process and acknowledge the purchases.
    .setListener((billingResult, purchases) -> {})
    .enableAutoServiceReconnection()
    .build();
 }

Conecte-se ao Google Play.O snippet de código a seguir mostra como fazer isso.

/**
* Starts the billing connection with Google Play. This method should be called exactly once
* before any other methods in this class.
*
* @param productList The list of products to query for after the connection is established.
*/
public void startBillingConnection(List<Product> productList) {
    billingClient.startConnection(
        new BillingClientStateListener() {
        @Override
        public void onBillingSetupFinished(BillingResult billingResult) {
            if (billingResult.getResponseCode() == BillingResponseCode.OK) {
            Log.d(TAG, "Billing Client Connection Successful");
            queryProductDetails(productList);
            } else {
            Log.e(TAG, "Billing Client Connection Failed: " + billingResult.getDebugMessage());
            listener.onBillingSetupFailed(billingResult); // Propagate the error to the listener to show a message to the user.
            }
        }

        @Override
        public void onBillingServiceDisconnected() {
            Log.e(TAG, "Billing Client Connection Lost");
            listener.onBillingError("Billing Connection Lost");
        }
        });
}

Extraia os detalhes do produto único.Depois de integrar o app com a 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(List<Product> productList) {
    QueryProductDetailsParams queryProductDetailsParams =
        QueryProductDetailsParams.newBuilder().setProductList(productList).build();

    billingClient.queryProductDetailsAsync(
        queryProductDetailsParams,
        new ProductDetailsResponseListener() {
        @Override
        public void onProductDetailsResponse(
            BillingResult billingResult, QueryProductDetailsResult productDetailsResponse) {
            if (billingResult.getResponseCode() == BillingResponseCode.OK) {
            List<ProductDetails> productDetailsList =
                productDetailsResponse.getProductDetailsList();
                listener.onProductDetailsResponse(productDetailsList);
            } else {
            Log.e(TAG, "QueryProductDetailsAsync Failed: " + billingResult.getDebugMessage());
            listener.onBillingError("Query Products Failed: " + billingResult.getResponseCode());
            }
        }
        });
}

Ao buscar o produto único (upcoming_movie_1 neste exemplo) em ProductDetails, você recebe uma resposta semelhante a esta:

{
    "productId": "upcoming_movie_1",
    "type": "inapp",
    "title": "Purrfect Mayhem: The Final Playback (Movies All Day | Play Samples)",
    "name": "Purrfect Mayhem: The Final Playback",
    "description": "Yolo and Thorne must reach the original broadcasting site to initiate the \"Final Playback\" and save the timeline. Follow them through their race against the Clockinators.",
    "skuDetailsToken": "<---skuDetailsToken--->",
    "oneTimePurchaseOfferDetails": {},
    "oneTimePurchaseOfferDetailsList": [
        {
            "priceAmountMicros": 8500000,
            "priceCurrencyCode": "USD",
            "formattedPrice": "$8.50",
            "offerIdToken": "<---offerIdToken--->",
            "offerId": "preorder",
            "purchaseOptionId": "buy-option",
            "offerTags": [],
            "validTimeWindow": {
                "startTimeMillis": 1756771200000,
                "endTimeMillis": 1785542400000
            },
            "preorderDetails": {
                "preorderReleaseTimeMillis": 1785542400000,
                "preorderPresaleEndTimeMillis": 1785542400000
            }
        }
    ]
}

Os detalhes da oferta de compra na pré-venda estão disponíveis em oneTimePurchaseOfferDetailsList. Essa lista tem uma opção de compra (buy-option) para a qual a oferta de pré-venda foi configurada no Play Console. É possível identificar cada opção de compra de forma exclusiva pelo offerIdToken.

Extraia o token da oferta com os detalhes da oferta de compra na pré-venda. Você precisa do token da oferta para iniciar o fluxo de faturamento na etapa 6.

@Override
public void onProductDetailsResponse(List<ProductDetails> productDetailsList) {

if (productDetailsList != null && !productDetailsList.isEmpty()) {

// Process productDetailsList returned by QueryProductDetailsResult
for (ProductDetails productDetails : productDetailsResult.getProductDetailsList()) {
  for (OneTimePurchaseOfferDetails oneTimePurchaseOfferDetails :
      productDetails.getOneTimePurchaseOfferDetailsList()) {
    // Checks if the offer is a preorder offer.
    if (oneTimePurchaseOfferDetails.getPreorderDetails() != null) {
      // Process the returned PreorderDetails
      OneTimePurchaseOfferDetails.PreorderDetails preorderDetails =
          oneTimePurchaseOfferDetails.getPreorderDetails();
      // Get preorder release time in millis.
      long preorderReleaseTimeMillis = preorderDetails.getPreorderReleaseTimeMillis();
      // Get preorder presale end time in millis.
      long preorderPresaleEndTimeMillis = preorderDetails.getPreorderPresaleEndTimeMillis();
      // Get offer ID
        String offerId = oneTimePurchaseOfferDetails.getOfferId();
      // Get the associated purchase option ID
      if (oneTimePurchaseOfferDetails.getPurchaseOptionId() != null) {
        String purchaseOptionId = oneTimePurchaseOfferDetails.getPurchaseOptionId();
      }
    }
  }
  }
  } else {
        Log.e(TAG, "No product details found for " + productId);
    }
}

Inicie o fluxo de faturamento.

/**
 * Launches the billing flow for the product with the given offer token.
*
* @param activity The activity instance from which the billing flow will be launched.
* @param productDetails The product details of the product to purchase.
* @param offerToken The offer token of the product to purchase.
* @return The result of the billing flow.
*/
public void launchPurchase(Activity activity, ProductDetails productDetails, String offerToken) {
    ImmutableList<BillingFlowParams.ProductDetailsParams> productDetailsParamsList =
        ImmutableList.of(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                .setProductDetails(productDetails)
                .setOfferToken(offerToken)
                .build());
    BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        .build();
    billingClient.launchBillingFlow(activity, billingFlowParams);
}

5. Testar opções de compra

Antes de disponibilizar os produtos únicos no app ativo, teste a integração da PBL usando testadores de licença e o Play Billing Lab.

Para entender como testar suas opções de compra usando o Play Billing Lab, consulte o codelab Conquiste novos mercados com preços regionais de produtos.

6. Próximas etapas

Saiba como analisar as desistências de compra de produtos.
Saiba como entrar em novos mercados usando a precificação regional.
Saiba como maximizar a integração do Play Faturamento.
Não se esqueça de seguir as práticas recomendadas para verificar e processar compras no seu back-end seguro assim que os usuários começarem a comprar esses produtos.

Documentos de referência

7. Parabéns!

Parabéns! Você navegou com sucesso pelo Google Play Console para criar uma oferta de pré-venda de um produto único. Agora você tem um entendimento mais profundo do catálogo de produtos flexível do Google Play para compras únicas.

Pesquisa

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