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 seu 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 pelo Play Console ou automatizar o gerenciamento de catálogo usando a API Google Play Developer. A automação pode ajudar a garantir que seu catálogo esteja sempre atualizado e escalar para catálogos grandes em que a coordenação manual é impraticá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 Como se preparar para ver 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 Google Play, correspondentes às duas principais categorias de produtos:

  • Produtos únicos
  • Produtos por assinatura

Produtos únicos

O endpoint inappproducts permite gerenciar produtos únicos no back-end. Isso inclui a criação, atualização e exclusão de produtos, além do gerenciamento de preços e disponibilidade. Dependendo de como você lida com compras únicas de produtos, você vai modelar produtos consumíveis (que podem ser comprados quantas vezes quiser) ou direitos permanentes (que não podem ser feitos duas vezes pelo mesmo usuário). Você pode decidir quais produtos únicos devem ser de consumo ou não.

Produtos por assinatura

O endpoint monetization.subscriptions ajuda a gerenciar produtos de assinatura no back-end do desenvolvedor. Você pode criar, atualizar e excluir assinaturas ou controlar a disponibilidade regional e os preços delas. Além do endpoint monetization.subscriptions, também oferecemos monetization.subscriptions.basePlans e monetization.subscriptions.basePlans.offers para gerenciar os planos básicos e as ofertas das assinaturas.

Métodos de lote

Os endpoints inappproducts e monetization.subscriptions oferecem vários métodos de 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 de latência ativada, oferecem suporte a um maior throughput e são particularmente úteis para desenvolvedores de catálogos grandes para a criação inicial ou reconciliação de catálogos.

Atualizar a latência de propagação em relação à taxa de transferência

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 devido a atrasos no processamento de rede ou de back-end. Por padrão, todas as solicitações de modificação de produto são sensíveis à latência. Isso significa que elas são otimizadas para propagação rápida por sistemas de back-end, normalmente refletidas nos 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 taxa de atualização. As atualizações tolerantes a latência levam até 24 horas para serem propagadas aos dispositivos do usuário final.

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 têm um limite padrão de 200.000 consultas por dia. Esse limite de cota se aplica à agregação de uso em todos os endpoints, incluindo APIs de gerenciamento de catálogo.
  2. Os endpoints de modificação de produtos também aplicam um limite de 7.200 consultas por hora. Esse é um limite único para produtos únicos e assinaturas e para 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 são contabilizadas como uma consulta para essa cota, independente do número de solicitações individuais incluídas ou da sensibilidade de latência.
  3. As modificações sensíveis à latência também têm um limite de 7.200 modificações por hora. Para métodos em lote, cada solicitação de modificação aninhada é contabilizada separadamente para fins desta cota. Essa cota tem implicações práticas apenas para os usuários da API de lote que executam atualizações sensíveis à latência, já que, em outros casos, a cota 2 será esgotada antes ou ao mesmo tempo que essa cota.

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

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

Monitorar o uso

Você precisa estar ciente dos processos de uso intenso. Por exemplo, no início da integração, os endpoints de gerenciamento de catálogos têm mais probabilidade de consumir mais cota para criar o catálogo inicial completo, o que pode afetar o uso de produção de outros endpoints, como a API de status de compra, se você estiver próximo do limite de uso geral. Você precisa monitorar o consumo de cota para garantir que não esteja excedendo as cotas da API. Há várias maneiras de monitorar o uso. Por exemplo, é possível 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 cota da API

É altamente recomendável otimizar o consumo de taxa para minimizar a probabilidade de erros de API. Para implementar isso de maneira eficaz, recomendamos que você:

  • Escolha a estratégia de gerenciamento de catálogo certa. Depois de entender a cota da API, você precisa escolher a estratégia certa para que seu aplicativo alcance as metas de gerenciamento de catálogo de forma eficiente.
  • Faça apenas o número mínimo de chamadas necessárias para refletir as mudanças.
  • Não envie chamadas de modificação redundantes ou desnecessárias para as APIs. Isso pode exigir que você mantenha um registro de alterações no catálogo de back-end.
  • Não ultrapasse o limite de 7.200 consultas por hora de 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, como 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 diminuir o uso a um nível seguro. Considere usar métodos de lote com atualizações tolerantes a latência para alcançar um maior throughput.
  • Prepare-se proativamente para a expansão. À 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 a cota quando você estiver chegando ao uso máximo.
  • Programe estrategicamente processos pesados. Tente programar seus processos de catálogo pesados em 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 a lógica de tratamento de erros de cota

Não importa o quanto você cria sua lógica de gerenciamento de catálogo com eficiência, ela precisa ser resiliente a limites de cota inesperados, já que a cota diária é compartilhada por endpoints usados em módulos independentes da sua 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 de 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 de erro e uma mensagem de depuração. Por exemplo, se você ultrapassar o limite diário, poderá encontrar um erro semelhante ao seguinte:

{
  "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álogo

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 o catálogo do Google Play sempre atualizado com as informações mais recentes do back-end tem vantagens para criar uma melhor experiência do usuário. Exemplo:

  • Você poderá consultar a lista completa de ofertas disponíveis e gerenciar as tags de oferta e de plano básico para influenciar sua própria qualificação e a lógica de oferta.
  • Você pode conferir os diferentes preços e detalhes do produto que os usuários veem nas 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 outras chamadas 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 estruturar seu catálogo, é hora de decidir a estratégia de sincronização.

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

Os endpoints de publicação da API Google Play Developer permitem que você faça atualizações no seu catálogo conforme as mudanças ocorrem. Às vezes, pode ser necessário fazer 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 as duas, dependendo da situação. Às vezes, você pode querer fazer uma atualização em um produto assim que souber de uma nova mudança, por exemplo, para processar uma atualização urgente de produto (ou seja, um preço incorreto precisa ser corrigido assim que possível). Em outros momentos, você pode usar uma sincronização em segundo plano periódica para garantir que o back-end e os catálogos do Google Play estejam sempre consistentes. Leia alguns casos de uso comuns em que você pode querer implementar essas diferentes estratégias de gerenciamento de catálogo.

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

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

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

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

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

Quando usar atualizações periódicas

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

  • Não é necessário garantir que seus produtos sejam atualizados em pouco tempo.
  • 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 que atualiza o catálogo constantemente

No caso de catálogos grandes, use métodos de lote com atualizações tolerantes a 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, automatize a carga inicial. Esse tipo de processo pesado funciona melhor se uma estratégia periódica for combinada com métodos de lote tolerantes a latência.

Criar produtos únicos

Para a criação inicial de um catálogo grande de produtos, recomendamos usar o método inappproducts.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 menores, use o método inapp_products.insert. Como alternativa, use o método inappproducts.update com o parâmetro allowMissing, conforme descrito na seção "Atualizações do produto". Essa abordagem tem a vantagem de eliminar a necessidade de que o script tenha estado e possa ser reiniciado do zero se algo der errado.

Criar produtos de assinatura

Para a criação inicial de catálogos grandes 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 do produto".

Todos os métodos anteriores criam assinaturas com os planos básicos (fornecidos no objeto Subscription). Esses planos de base são inicialmente inativos. 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

Os métodos a seguir permitem modificar os produtos atuais de maneira eficiente, garantindo que as ofertas estejam alinhadas aos ajustes mais recentes.

Atualizar produtos únicos

Há três métodos disponíveis para ajudar a atualizar os produtos únicos atuais.

  • inappproducts.patch: o endpoint de patch é usado para atualizar um recurso parcialmente. Isso significa que você pode atualizar campos específicos especificados 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ê vai precisar enviar todo o objeto de recurso no corpo da solicitação. O endpoint de atualização normalmente é 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-o com o campo latencyTolerance definido como PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT para aumentar a capacidade.

Atualizar produtos de assinatura

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

A menos que você esteja criando uma nova 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 listagem de um produto por assinatura, especifique o campo listings para o parâmetro updateMask.

É possível 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 mais recentes de preços de planos básicos, 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ê atualizar o catálogo do Google Play sempre que o catálogo do back-end mudar ou periodicamente, se tiver um sistema de gerenciamento de catálogo ou um banco de dados fora do catálogo do Google Play, pode haver situações em que ele não será sincronizado com o catálogo na configuração do app no Google Play. Isso pode ser devido a mudanças manuais de emergência no catálogo no console, a uma falha no sistema de gerenciamento de catálogo ou à perda dos dados mais recentes.

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

Consideração do sistema de diferenciação

Recomendamos criar um sistema de comparação para detectar inconsistências e reconciliar os dois sistemas. Confira alguns pontos a serem considerados ao criar um sistema de diferenças para ajudar a 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 são mapeados entre si.
  • Definir as regras de diferença:depois de entender os modelos de dados, é necessário definir as regras de diferença. Essas regras vão determinar como os dados nos dois sistemas são comparados. Por exemplo, você pode corresponder IDs de produtos e comparar os principais atributos da assinatura e os planos e ofertas básicas associados.
  • Implementar um algoritmo de comparação:depois de definir as regras de comparação, é necessário implementar o algoritmo de comparação. Esse algoritmo vai usar os dados dos dois sistemas e compará-los de acordo com as regras que você definiu. Para receber os dados do catálogo do Google Play, use os métodos inappproducts.list, inappproducts.batchGet, monetization.subscriptions.list e monetization.subscriptions.batchGet.
  • Gerar relatórios de diferença:o algoritmo de diferença vai gerar um relatório de diferença. Esse relatório mostra as diferenças entre os dois sistemas.
  • Reconciliar diferenças:depois de gerar o relatório de diferenças, é necessário resolver as diferenças. Isso pode envolver a atualização dos dados no seu CMS ou no Google Play usando os endpoints de gerenciamento de catálogo da API para desenvolvedores, dependendo de como você normalmente atualiza o catálogo. Para reconciliar produtos fora de sincronização, use os endpoints de atualização, conforme descrito na seção "Atualizações de produtos".

Descontinuação do produto

A API Google Play Developer oferece vários métodos para ajudar os desenvolvedores a descontinuar os produtos: inappproducts.delete e inappproducts.batchDelete para produtos únicos e monetization.subscriptions.delete para assinaturas. A descontinuação de um produto pode ser necessária em vários cenários, como:

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

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

Descontinuar produtos únicos

Para excluir produtos únicos com a API Google Play Developer, use o método inappproducts.delete ou inappproducts.batchDelete.

Descontinuar produtos por assinatura

É possível excluir assinaturas usando o método monetization.subscriptions.delete. Não é possível remover uma assinatura quando pelo menos um plano básico foi ativado.