Reminder: By Aug 31, 2024, all new apps and updates to existing apps must use Billing Library version 6 or newer. If you need more time to update your app, you will be able to request an extension until Nov 1, 2024. Learn more.

Esta página foi traduzida pela API Cloud Translation.

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 com o sistema de faturamento do Google Play, é necessário configurar um catálogo com todos os produtos que você quer disponibilizar para compra aos usuários. Isso pode ser feito pelo Play Console ou é possível automatizar o gerenciamento do catálogo usando a API Google Play Developer. A automação pode ajudar a garantir que seu catálogo esteja sempre atualizado e fazer escalonamento para grandes catálogos, 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 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 Entender os tipos de produtos no app e as considerações de catálogo. O Google oferece dois conjuntos principais de APIs para o gerenciamento do catálogo no Google Play, correspondentes às duas principais categorias de produtos:

Produtos de aquisição única
Produtos por assinatura

Produtos de aquisição única

O endpoint inappproducts permite gerenciar produtos únicos do seu back-end. Isso inclui criar, atualizar e excluir produtos, além de gerenciar preços e disponibilidade. Dependendo de como você lida com as compras de produtos únicos, é possível modelar produtos de consumo (que podem ser comprados quantas vezes você quiser) ou direitos permanentes (não podem ser feitos duas vezes pelo mesmo usuário). Você pode decidir quais produtos de aquisição única devem ser consumíveis ou não.

Produtos por assinatura

O endpoint monetization.subscriptions ajuda você 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. Além do endpoint monetization.subscriptions, também fornecemos monetization.subscriptions.basePlans e monetization.subscriptions.basePlans.offers para gerenciar planos básicos e ofertas de assinaturas, respectivamente.

Métodos em lote

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

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

Atualize a latência de propagação em comparação com a capacidade de processamento

Após a conclusão de uma solicitação de criação ou modificação de produto, as mudanças podem não ficar imediatamente visíveis para os usuários finais nos dispositivos devido a atrasos no processamento da rede ou do 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 uma propagação rápida por sistemas de back-end, geralmente refletindo nos dispositivos do usuário final em minutos. No entanto, há um limite por hora para o número dessas solicitações de modificação. Nos casos em que é preciso criar ou atualizar muitos produtos (por exemplo, durante a criação inicial de um grande catálogo), é possível usar métodos em lote com o campo latencyTolerance definido como PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Isso vai aumentar significativamente a capacidade de processamento das atualizações. As atualizações tolerantes à latência vão levar até 24 horas para serem propagadas para os 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:

As APIs Google Play Developer têm um limite padrão de 200 mil consultas por dia. Esse limite de cota se aplica à agregação de uso em todos os endpoints, incluindo as APIs de gerenciamento de catálogo.
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 e para todas as solicitações de modificação, incluindo criação, atualização, ativação e exclusão. As chamadas do método de modificação em lote contam como uma consulta para essa cota, independentemente do número de solicitações individuais incluídas ou da sensibilidade de latência.
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 essa 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 ela.

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

Uma única solicitação get para buscar um item vai consumir um token da cota 1 e nenhum token das cotas 2 e 3, já que elas dizem respeito apenas a endpoints de modificação.
Uma solicitação get em lote para buscar até 100 itens também consumirá um token da cota 1 e nenhum token das cotas 2 e 3.
Uma única solicitação modification para um item 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 que a cota 2, ela não tem implicações práticas para usuários que usam apenas métodos de modificação únicas.
Uma solicitação modification em lote para 100 itens tolerantes à latência consumirá 1 token da cota 1, 1 token da cota 2. Essa configuração de cota precisa permitir uma margem ampla para manter o catálogo atualizado. No entanto, se o algoritmo não souber essa cota e ultrapassar essa taxa, você poderá receber um erro por chamada adicional.
Uma solicitação modification em lote para 100 itens sensíveis à latência 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.

Monitore seu uso

Você deve estar ciente dos processos de uso intenso. Por exemplo, no início da integração, os endpoints de gerenciamento do catálogo têm maior probabilidade de consumir 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 de uso geral. Monitore seu consumo de cota para não exceder 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 de sua escolha.

Otimizar o uso da cota da API

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

Escolher a estratégia certa de gerenciamento de catálogo. Depois de entender a cota da API, você precisa escolher a estratégia certa para seu aplicativo a fim de atingir as metas de gerenciamento do catálogo com eficiência.
Faça apenas a quantidade mínima de chamadas necessária para refletir suas alterações.
Não envie chamadas de modificação redundantes ou desnecessárias às APIs. Isso pode exigir que você mantenha um registro de alterações no catálogo de back-end.
Mantenha-se abaixo do limite por hora de modificação do produto de 7.200 consultas. É possível criar processos de sincronização que exijam que você faça um grande número de modificações de produtos em um curto período (por exemplo, uma criação inicial de catálogo). Se você espera que esses processos excedam o limite por hora, implemente esperas conforme necessário para reduzir a velocidade do uso a um nível seguro. Considere usar métodos em lote com atualizações tolerantes à latência para alcançar uma capacidade maior.
Preparar-se de modo proativo para escalonar. À medida que seu aplicativo cresce, pode ser necessário escalonar o uso da API e dos vários endpoints. Leia a documentação de cotas da API Google Play Developer para detalhes sobre como aumentar sua cota quando estiver perto do uso máximo.
Programe processos pesados de maneira estratégica. Tente programar seus processos pesados de catálogo em torno de picos de uso críticos. Por exemplo, evite executar uma sincronização completa no catálogo durante os horários de pico de vendas da semana.

Adicionar lógica de tratamento de erros de cota

Independentemente da eficiência da criação da lógica de gerenciamento de 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 processamento de erros e implemente as esperas adequadas. Cada chamada feita para as APIs Google Play Developer vai gerar uma resposta. No caso de uma falha na chamada, você 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 seu 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 do 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. Garantir que o catálogo do Google Play esteja sempre atualizado com as informações mais recentes do catálogo do back-end tem vantagens para criar uma melhor experiência do usuário. Por exemplo:

É possível consultar toda a lista de ofertas disponíveis e gerenciar as tags de oferta e de plano básico para influenciar sua qualificação e a lógica de exibição da oferta.
Você pode verificar as diferentes faixas de preços e detalhes do produto que os usuários estão vendo em todas as plataformas e garantir que elas sejam consistentes.
Os detalhes do produto estarão disponíveis no back-end ao processar novas compras, sem a necessidade de aumentar a latência e o risco de falha ao fazer chamadas adicionais para a API Google Play Developer durante fluxos essenciais para o usuário.

Há certos 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 sobre sua estratégia de sincronização.

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

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 adotar uma abordagem de atualizações periódicas, em que você envia uma bateria de mudanças no mesmo processo. Cada abordagem requer diferentes escolhas de design. Cada estratégia de sincronização se adapta melhor a alguns casos de uso do que outros, e você pode ter um conjunto de necessidades que chama ambos, dependendo da situação. Às vezes, você pode querer fazer uma atualização de um produto assim que estiver ciente de uma nova mudança, por exemplo, para processar uma atualização urgente de produto (ou seja, um preço errado precisa ser corrigido o mais rápido possível). Outras vezes, é possível usar uma sincronização periódica em segundo plano para garantir que seus catálogos de back-end e do Google Play sejam sempre consistentes. Leia alguns casos de uso comuns em que talvez você queira 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 qualquer alteração no catálogo de produtos do back-end, para minimizar as discrepâncias.

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

Seus produtos precisam estar 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 menor discrepância.

Quando usar atualizações periódicas

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

Você não precisa 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 de catálogo para lidar com seus produtos digitais, e que atualiza seu catálogo constantemente

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

Observação: embora você possa enviar atualizações ao seu catálogo de produtos do Google Play imediatamente após qualquer mudança, isso não significa necessariamente que as mudanças vão ficar disponíveis imediatamente para os usuários no app. Ainda pode haver latência no processo devido a atrasos no processamento de rede ou back-end. Da mesma forma, mesmo que as atualizações periódicas sejam realizadas com algum atraso, elas ainda podem ser projetadas para atualizar seu catálogo com frequência, se necessário, disponibilizando as mudanças aos usuários com latência semelhante às atualizações sob demanda. Além disso, o campo latencyTolerance em métodos em lote permite escolher entre otimizar para uma propagação de atualização rápida ou maior capacidade. Em última análise, a escolha entre essas duas opções deve ser baseada nos seus requisitos e limitações específicos.

Criar seu catálogo de produtos

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

Criar produtos de aquisição única

Para a criação inicial de um grande catálogo de produtos únicos, 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 minimizará o tempo necessário para criar o catálogo dentro dos limites da cota.

Para catálogos menores, use o método inapp_products.insert. Como alternativa, você pode usar o método inappproducts.update com o parâmetro allowMissing, conforme descrito na seção "Atualizações de produtos". Essa abordagem remove a necessidade de o script ser com estado e pode ser reiniciado do zero caso algo dê errado.

Criar produtos por assinatura

Para criar um catálogo grande de assinatura inicial, 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 minimizará o tempo necessário para criar o catálogo dentro dos limites da cota.

Para catálogos de assinaturas menores, a API Play Developer oferece o método monetization.subscriptions.create. Como alternativa, você pode criar assinaturas usando o método monetization.subscriptions.update 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 básicos estã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 de produtos

Os métodos a seguir permitem modificar com eficiência os produtos atuais, 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.

inappproducts.patch: o endpoint do patch é usado para atualizar um recurso parcialmente. Isso significa que é possível atualizar campos específicos especificados no corpo da solicitação. O endpoint do patch é normalmente usado quando você só precisa atualizar alguns campos de um recurso.
inappproducts.update: o endpoint de atualização é usado para atualizar um recurso inteiro. Isso significa que você precisará enviar todo o objeto de recurso no corpo da solicitação. Normalmente, o endpoint de atualização é usado quando é preciso 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 : essa é uma versão em lote do endpoint de atualização, que permite modificar vários produtos com uma única consulta. Use com o campo latencyTolerance definido como PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT para ter uma capacidade maior.

Atualizar produtos por assinatura

Para atualizar assinaturas já existentes, 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 de região.

A menos que você esteja criando uma nova assinatura usando o parâmetro allowMissing, forneça o parâmetro updateMask. Esse parâmetro é uma lista separada por vírgulas dos 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.

Você pode usar o monetization.subscriptions.batchUpdate para atualizar várias assinaturas ao mesmo tempo. Use com o campo latencyTolerance definido como PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT para alcançar uma capacidade maior.

Para ativar, desativar ou excluir planos básicos ou migrar assinantes para as versões mais recentes de preço 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, se você 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 ficará dessincronizado com o catálogo na configuração de apps no Google Play. Isso pode ocorrer devido a alterações manuais emergenciais no Console, uma interrupção no sistema de gerenciamento de catálogo ou talvez você tenha perdido os dados mais recentes.

Crie um processo de reconciliação de catálogo para evitar uma janela de discrepâncias prolongada.

Consideração do sistema diferente

Recomendamos a criação de um sistema de diferenças para detectar inconsistências e reconciliar os dois sistemas. Confira o que você precisa considerar ao criar um sistema de diferenças para manter seus catálogos sincronizados:

Entender 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.
Definir as regras de diferença:depois de entender os modelos de dados, você precisa definir as regras de diferença. Essas regras vão determinar como os dados nos dois sistemas serão comparados. Por exemplo, você pode querer corresponder IDs de produto e comparar os principais atributos da assinatura e os planos básicos e ofertas associados.
Implemente um algoritmo de diferenças:depois de definir as regras, implemente o algoritmo de diferenças. Esse algoritmo usa os dados dos dois sistemas e os compara de acordo com as regras que você definiu. Para acessar 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ças:o algoritmo de diferenças gera um relatório de diferenças. Esse relatório mostra 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 da atualização dos dados do Google Play usando os endpoints de gerenciamento do catálogo da API Developer, dependendo de como você normalmente atualiza seu catálogo. Para reconciliar produtos fora de sincronia, use os endpoints de atualização conforme descrito na seção "Atualizações do produto".

Descontinuação do produto

A API Google Play Developer oferece vários métodos para ajudar os desenvolvedores a descontinuar 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.
Descontinuação de 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.

Suspender produtos por assinatura

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