Gerenciar seu catálogo de produtos

Este guia explica como usar a API Google Play Developer para criar e gerenciar um catálogo de produtos para seu app do Google Play.

Para vender produtos no app usando o sistema de faturamento do Google Play, você precisa configurar um catálogo com todos os produtos que quer disponibilizar para compra pelos usuários. Isso pode ser feito no Play Console ou automatizado com a API Google Play Developer. A automação ajuda a garantir que seu catálogo esteja sempre atualizado e a dimensionar catálogos grandes em que a coordenação manual é inviável. Neste guia, você vai aprender a usar a API Play Developer para criar e gerenciar um catálogo de produtos para seu app do Google Play. Consulte nosso guia de preparação para instruções sobre como configurar a API Google Play Developer para sua integração de back-end.

APIs de gerenciamento de catálogo

Para saber mais sobre os diferentes tipos de produtos que você pode vender com o sistema de faturamento do Google Play, leia Noções básicas sobre os tipos de produtos no app e considerações sobre o catálogo. O Google oferece dois conjuntos principais de APIs para gerenciamento de catálogo no Play, correspondentes às duas principais categorias de produtos:

  • Produtos únicos
  • Produtos por assinatura

Produtos únicos

Os produtos únicos (antes chamados de produtos no app) usam o modelo de objeto de produto único que permite configurar várias opções de compra e ofertas para seus produtos únicos. O modelo de objeto de produto único oferece mais flexibilidade na forma de vender produtos e reduz a complexidade do gerenciamento deles. Seus produtos no app atuais serão migrados para o modelo de objeto de produto único. Para mais informações, consulte Migração de produtos no app.

Os endpoints monetization.onetimeproducts e inappproducts permitem gerenciar produtos únicos no seu back-end. Isso inclui criar, atualizar e excluir produtos, além de gerenciar preços e disponibilidade. Dependendo de como você lida com compras de produtos únicos, você modela produtos de consumo (podem ser comprados quantas vezes quiser) ou direitos permanentes (não podem ser feitos duas vezes pelo mesmo usuário). Você pode decidir quais produtos únicos serão de consumo ou não.

Produtos por assinatura

O endpoint monetization.subscriptions ajuda a gerenciar produtos por assinatura no back-end do desenvolvedor. É possível criar, atualizar e excluir assinaturas, ou controlar a disponibilidade e os preços regionais delas. Além do endpoint monetization.subscriptions, também oferecemos monetization.subscriptions.basePlans e monetization.subscriptions.basePlans.offers para gerenciar planos básicos e ofertas de assinaturas, respectivamente.

Métodos de lote

Os endpoints onetimeproducts, inappproducts e monetization.subscriptions fornecem vários métodos em lote que permitem recuperar ou gerenciar até 100 entidades no mesmo app ao mesmo tempo.

Os métodos em lote, quando usados com a tolerância à latência ativada, oferecem suporte a maior capacidade de transferência e são especialmente úteis para desenvolvedores de catálogos grandes na criação inicial ou na conciliação de catálogos.

Latência de propagação da atualização x capacidade de processamento

Depois que uma solicitação de criação ou modificação de produto é concluída, as mudanças podem não ficar imediatamente visíveis para os usuários finais nos dispositivos deles devido a atrasos no processamento de rede ou de back-end. Por padrão, todas as solicitações de modificação de produtos são sensíveis à latência. Isso significa que eles são otimizados para propagação rápida em sistemas de back-end, geralmente refletindo em dispositivos do usuário final em minutos. No entanto, há um limite por hora no número de solicitações de modificação. Para casos em que você precisa criar ou atualizar muitos produtos (por exemplo, durante a criação inicial de um catálogo grande), use métodos em lote com o campo latencyTolerance definido como PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Isso vai aumentar significativamente a capacidade de atualização. As atualizações tolerantes à latência levam até 24 horas para serem propagadas aos dispositivos dos usuários finais.

Configuração de cota

Há vários limites de cota que você precisa conhecer ao usar a API Play Developer para gerenciar seu catálogo de produtos:

  1. As APIs Google Play Developer são organizadas em categorias chamadas buckets, onde cada bucket tem o próprio limite de cota por minuto. Para mais informações, consulte Cotas.
  2. Os endpoints de modificação de produtos também impõem um limite de 7.200 consultas por hora. Esse é um limite único para produtos únicos e assinaturas, além de todas as solicitações de modificação, incluindo criação, atualização, ativação e exclusão. As chamadas de método de modificação em lote contam como uma consulta para essa cota, independente do número de solicitações individuais incluídas ou da sensibilidade à latência.
  3. Modificações sensíveis à latência também têm um limite de 7.200 por hora. Para métodos em lote, cada solicitação de modificação aninhada é contada separadamente para fins dessa cota. Essa cota tem implicações práticas apenas para os usuários da API em lote que realizam atualizações sensíveis à latência. Em outros casos, a cota 2 será esgotada antes ou ao mesmo tempo que essa cota.

Confira alguns exemplos ilustrativos para entender o uso da cota de diferentes solicitações:

  • Uma única solicitação get para buscar um item consome um token da cota 1 e nenhum token das cotas 2 e 3, já que elas se referem apenas a endpoints de modificação.
  • Uma solicitação get em lote para buscar até 100 itens também consome um token da cota 1 e nenhum token das cotas 2 e 3.
  • Uma única solicitação modification para um item vai consumir um token da cota 1 e um token da cota 2. Se a solicitação for sensível à latência, ela também consumirá um token da cota 3. Como a cota C tem o mesmo limite da cota 2, ela não tem implicações práticas para usuários que usam apenas métodos de modificação única.
  • Uma solicitação modification em lote para 100 itens tolerantes à latência vai consumir um token da cota 1 e um token da cota 2. Essa configuração de cota deve permitir uma margem ampla para manter seu catálogo atualizado, mas se o algoritmo não estiver ciente dessa cota e exceder essa taxa, você poderá receber um erro por chamada adicional.
  • Uma solicitação modification em lote para 100 itens sensíveis à latência vai consumir 1 token da cota 1, 1 token da cota 2 e 100 tokens da cota 3.

Recomendações de uso da API Catalog Management

Ao seguir essas diretrizes, você otimiza suas interações com a API, garantindo uma experiência de gerenciamento de catálogo tranquila e eficiente.

Monitorar o uso

Você precisa estar ciente dos processos de uso intenso. Por exemplo, no início da integração, é mais provável que os endpoints de gerenciamento de catálogo consumam mais cota para criar o catálogo inicial completo. Isso pode afetar o uso de produção de outros endpoints, como a API de status de compra, se você estiver perto do limite geral de uso. Monitore o consumo de cota para não exceder as cotas de API. Há várias maneiras de monitorar o uso. Por exemplo, você pode usar o painel de cotas das APIs do Google Cloud ou qualquer outra ferramenta de monitoramento de API interna ou de terceiros.

Otimizar o uso de cotas da API

Recomendamos otimizar o consumo de taxa para minimizar a probabilidade de erros de API. Para implementar isso de forma eficaz, recomendamos que você:

  • Escolha a estratégia de gerenciamento de catálogo certa. Depois de entender a cota da API, escolha a estratégia certa para que seu aplicativo alcance as metas de gerenciamento de catálogo de maneira eficiente.
  • Faça apenas o número mínimo de chamadas necessárias para refletir suas mudanças.
  • Não envie chamadas de modificação redundantes ou desnecessárias para as APIs. Isso pode exigir que você mantenha um changelog no catálogo de back-end.
  • Fique abaixo do limite de 7.200 consultas por hora para modificação de produtos. Talvez você queira criar processos de sincronização que exijam um grande número de modificações de produtos em um curto período (por exemplo, a criação inicial de um catálogo). Se você espera que esses processos ultrapassem o limite por hora, implemente esperas conforme necessário para reduzir o uso a um nível seguro. Considere usar métodos em lote com atualizações tolerantes à latência para alcançar maior capacidade de processamento.
  • Prepare-se proativamente para o escalonamento. À medida que seu aplicativo cresce, talvez seja necessário aumentar o uso da API e dos vários endpoints. Leia a documentação sobre cotas da API Google Play Developer para saber como aumentar sua cota quando estiver se aproximando do uso máximo.
  • Agende processos pesados de forma estratégica. Tente programar seus processos de catálogo pesados em torno de picos de uso críticos. Por exemplo, evite executar uma sincronização completa do catálogo durante os horários de pico de vendas da semana.

Adicionar lógica de tratamento de erros de cota

Não importa o quão eficiente seja a lógica de gerenciamento do catálogo, ela precisa ser resiliente a limites de cota inesperados, já que a cota diária é compartilhada pelos endpoints usados em módulos independentes da integração. Inclua erros de limitação de cota no tratamento de erros e implemente as esperas adequadas. Cada chamada feita para as APIs Google Play Developer gera uma resposta. Em caso de falha na chamada, você vai receber uma resposta de falha que inclui um código de status de resposta HTTP e um objeto errors, fornecendo mais detalhes sobre o domínio do erro e uma mensagem de depuração. Por exemplo, se você ultrapassar o limite diário, poderá encontrar um erro semelhante a este:

{
  "code" : 403,
  "errors" : [ {
    "domain" : "usageLimits",
    "message" : "Daily Limit Exceeded. The quota will be reset at midnight Pacific Time (PT). You may monitor your quota usage and adjust limits in the API
  Console: https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/quotas?project=xxxxxxx",
  "reason" : "dailyLimitExceeded",
  "extendedHelp" : "https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/quotas?project=xxxxxx"
  } ],
}

Implementação do gerenciamento de catálogos

Os desenvolvedores usam os endpoints de publicação de produtos da API Google Play Developer para manter o catálogo sincronizado entre o back-end e o Google Play. Manter seu catálogo do Google Play sempre atualizado com as informações mais recentes do catálogo do back-end tem vantagens para criar uma experiência do usuário melhor. Por exemplo:

  • Você poderá consultar a lista completa de ofertas disponíveis e gerenciar as tags de ofertas e planos básicos para influenciar sua própria qualificação e a lógica de exibição de ofertas.
  • Você pode verificar os diferentes preços e detalhes dos produtos que os usuários estão vendo em todas as plataformas e garantir que eles sejam consistentes.
  • Você terá os detalhes do produto em mãos no back-end ao processar novas compras, sem precisar aumentar a latência e o risco de falha ao fazer chamadas adicionais para a API Google Play Developer durante fluxos críticos do usuário.

Há alguns limites e considerações que você precisa ter em mente ao criar seu catálogo de produtos no Google Play. Depois de entender esses limites e saber como você quer estruturar seu catálogo, é hora de decidir sua estratégia de sincronização.

Estratégias de sincronização de catálogo

Os endpoints de publicação da API Google Play Developer permitem que você faça atualizações no catálogo à medida que as mudanças ocorrem. Às vezes, pode ser necessário adotar uma abordagem de atualizações periódicas, em que você envia uma série de mudanças no mesmo processo. Cada abordagem exige escolhas de design diferentes. Cada estratégia de sincronização se adapta melhor a alguns casos de uso do que a outros, e você pode ter um conjunto de necessidades que exigem ambas, dependendo da situação. Às vezes, você quer atualizar um produto no momento em que fica sabendo de uma nova mudança, por exemplo, para processar uma atualização urgente (ou seja, um preço errado precisa ser corrigido o mais rápido possível). Em outros momentos, você pode usar uma sincronização periódica em segundo plano para garantir que os catálogos do back-end e do Google Play estejam sempre consistentes. Leia alguns casos de uso comuns em que você pode implementar essas diferentes estratégias de gerenciamento de catálogo.

Quando enviar atualizações conforme o catálogo local muda

O ideal é que as atualizações aconteçam assim que houver uma mudança no catálogo de produtos do back-end para minimizar discrepâncias.

Esse tipo de atualização é uma boa opção quando:

  • Verifique se os produtos estão sempre atualizados.
  • Você precisa fazer algumas mudanças nos produtos todos os dias.
  • É necessário atualizar os produtos que já estão em produção e sendo vendidos.

Essa abordagem é mais simples de implementar e permite manter o catálogo sincronizado com a menor janela de discrepância.

Quando usar atualizações periódicas

As atualizações periódicas são executadas de forma assíncrona na edição do produto no seu back-end e são uma boa opção quando:

  • Não é necessário garantir que seus produtos sejam atualizados em um curto período.
  • Você precisa planejar atualizações em massa ou processos de conciliação.
  • Você já tem um sistema de gerenciamento de conteúdo ou catálogo para lidar com seus produtos digitais, e ele atualiza seu catálogo constantemente.

No caso de catálogos grandes, use métodos em lote com atualizações tolerantes à latência para alcançar a capacidade máxima.

Criar seu catálogo de produtos

Se você tiver um catálogo grande para fazer upload no Google Play, talvez queira automatizar o carregamento inicial. Esse tipo de processo pesado funciona melhor se uma estratégia periódica combinada com métodos em lote tolerantes à latência for seguida.

Criar produtos únicos

Para a criação inicial e única do catálogo de produtos, recomendamos usar o método monetization.onetimeproducts.batchUpdate ou inapp_products.insert com o campo allowMissing definido como true e o campo latencyTolerance definido como PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Isso vai minimizar o tempo necessário para criar o catálogo dentro dos limites de cota.

Criar produtos por assinatura

Para a criação inicial de um catálogo grande de assinaturas, recomendamos usar o método monetization.subscriptions.batchUpdate com o campo allowMissing definido como true e o campo latencyTolerance definido como PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Isso vai minimizar o tempo necessário para criar o catálogo dentro dos limites de cota.

Para catálogos de assinaturas menores, a API Play Developer oferece o método monetization.subscriptions.create. Como alternativa, é possível criar assinaturas usando o método monetization.subscriptions.patch com o parâmetro allowMissing, conforme descrito na seção "Atualizações de produtos".

Todos os métodos anteriores criam assinaturas com os planos básicos (fornecidos no objeto "Subscription"). Esses planos básicos ficam inativos inicialmente. Para gerenciar o status dos planos básicos, use o endpoint monetization.subscriptions.basePlans, incluindo a ativação de um plano básico para disponibilizá-lo para compra. Além disso, o endpoint monetization.subscriptions.basePlans.offers permite criar e gerenciar ofertas.

Atualizações do produto

Com os métodos a seguir, é possível modificar seus produtos atuais de maneira eficiente e garantir que suas ofertas estejam alinhadas aos ajustes mais recentes.

Atualizar produtos únicos

Os métodos a seguir estão disponíveis para ajudar a atualizar produtos únicos.

  • monetization.onetimeproducts.batchUpdate
  • inappproducts.patch : o endpoint de patch é usado para atualizar um recurso parcialmente. Isso significa que você pode atualizar campos específicos que especificar no corpo da solicitação. O endpoint de patch é usado normalmente quando você só precisa atualizar alguns campos de um recurso.
  • inappproducts.update : o endpoint de atualização é usado para atualizar um recurso por completo. Isso significa que você precisa enviar todo o objeto de recurso no corpo da solicitação. O endpoint de atualização geralmente é usado quando você precisa atualizar todos os campos em um recurso. Quando o parâmetro allowMissing é definido como true e o ID do produto fornecido ainda não existe, o endpoint insere o produto em vez de falhar.
  • inappproducts.batchUpdate : é uma versão em lote do endpoint de atualização, que permite modificar vários produtos com uma única consulta. Use junto com o campo latencyTolerance definido como PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT para aumentar a taxa de transferência.

Atualizar produtos de assinatura

Para atualizar as assinaturas atuais, use o método monetization.subscriptions.patch. Esse método usa os seguintes parâmetros obrigatórios:

  • packageName: o nome do pacote do app a que a assinatura pertence.
    • productId: o ID exclusivo do produto da assinatura.
  • regionsVersion: a versão da configuração regional.

A menos que você esteja criando uma assinatura usando o parâmetro allowMissing, é necessário informar o parâmetro updateMask. Esse parâmetro é uma lista separada por vírgulas de campos que você quer atualizar.

Por exemplo, se você quiser atualizar apenas uma lista de um produto por assinatura, especifique o campo listings para o parâmetro updateMask.

Você pode usar monetization.subscriptions.batchUpdate para atualizar várias assinaturas ao mesmo tempo. Use-o com o campo latencyTolerance definido como PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT para aumentar a taxa de transferência.

Para ativar, desativar, excluir planos básicos ou migrar assinantes para as versões de preço mais recentes do plano básico, use o endpoint monetization.subscriptions.basePlans.

Além disso, é possível atualizar as ofertas dos planos básicos com o método monetization.subscriptions.basePlans.offers.patch.

Reconciliação de catálogo

Se você optar por atualizar o catálogo do Google Play sempre que o catálogo do back-end mudar ou periodicamente, e tiver um sistema de gerenciamento de catálogo ou um banco de dados fora do catálogo do Google Play, poderá haver situações em que ele fique dessincronizado com o catálogo na configuração dos apps no Google Play. Isso pode acontecer devido a mudanças manuais de emergência no catálogo no console, uma interrupção no sistema de gerenciamento de catálogo ou se você perdeu os dados mais recentes.

Você pode criar um processo de conciliação de catálogo para evitar uma janela de discrepância prolongada.

Consideração sobre o sistema de diff

Recomendamos criar um sistema de diff para detectar inconsistências e conciliar os dois sistemas. Confira algumas coisas a considerar ao criar um sistema de diff para manter seus catálogos sincronizados:

  • Entenda os modelos de dados:a primeira etapa é entender os modelos de dados do CMS do desenvolvedor e da API Google Play Developer. Isso inclui conhecer os diferentes tipos de dados armazenados em cada sistema e como os diferentes elementos de dados se relacionam.
  • Defina as regras de diff:depois de entender os modelos de dados, você precisa definir as regras de diff. Essas regras determinam como os dados nos dois sistemas são comparados. Por exemplo, você pode querer corresponder IDs de produtos e comparar atributos principais da assinatura e dos planos básicos e ofertas associados.
  • Implemente um algoritmo de diff:depois de definir as regras de diff, você precisa implementar o algoritmo de diff. Esse algoritmo vai usar os dados dos dois sistemas e compará-los de acordo com as regras definidas. Para receber os dados do catálogo do Google Play, use os métodos monetization.onetimeproducts.list, monetization.onetimeproducts.batchGet, inappproducts.list, inappproducts.batchGet, monetization.subscriptions.list e monetization.subscriptions.batchGet.
  • Gerar relatórios de diff:o algoritmo de diff vai gerar um relatório de diff. Esse relatório vai mostrar as diferenças entre os dois sistemas.
  • Reconciliar diferenças:depois de gerar o relatório de diferenças, você precisa resolver as diferenças. Isso pode envolver a atualização dos dados no seu CMS ou no Google Play usando os endpoints de gerenciamento do catálogo da API Developer, dependendo de como você costuma atualizar seu catálogo. Para conciliar produtos dessincronizados, use os endpoints de atualização conforme descrito na seção "Atualizações de produtos".

Descontinuação de produtos

A API Google Play Developer oferece os seguintes métodos para ajudar você a descontinuar seus produtos:

Para produtos únicos:

Para produtos por assinatura:

A descontinuação de um produto pode ser necessária em vários cenários, como:

  • Criação por engano.
  • Descontinuação de um recurso ou serviço.

Recomendamos incorporar a descontinuação de produtos à sua estratégia de gerenciamento de catálogo.