API de relatórios para desenvolvedores da Google Play em 2026
O Google Play já mostra números de falhas e ANR no console. Essa visão foi feita para um app, uma pessoa, uma tarde. A Play Developer Reporting API existe para a outra tarefa: extrair esses mesmos dados de qualidade de forma programada, em todos os apps que você opera, para o seu próprio data warehouse ou pipeline de alertas. Não é um segundo console. É uma forma normalizada de fazer as mesmas perguntas sobre quarenta apps sem abrir quarenta abas.
Este tutorial traz a sequência que realmente funciona em 2026, na ordem em que os erros aparecem se você fizer errado: projeto, conta de serviço, permissão no Play Console, descoberta do app, atualidade dos dados, consulta, dimensões, anomalias. Cada etapa é uma chamada documentada, e os dois pontos em que a maioria das equipes trava são o convite no Play Console na etapa 3 e a suposição de fuso horário na etapa 7.
1. Saiba o que a API retorna antes de escrever código
O serviço expõe conjuntos de métricas: grupos lógicos de métricas relacionadas que compartilham uma granularidade e podem ser consultadas juntas. Os conjuntos documentados cobrem taxa de ANR, taxa de falhas, taxa de despertar excessivo, taxa de wakelock em segundo plano travado, taxa de inicialização lenta, taxa de renderização lenta, taxa de LMK (encerramento por falta de memória), uso de memória RSS anônima e swap, uso de memória de bitmap e contagem de erros. Cada conjunto traz métricas normalizadas como crashRate, userPerceivedCrashRate e as médias ponderadas por usuário de 7 e 28 dias ao lado delas.
Duas constatações práticas decorrem desse design. Primeiro, esses dados são agregados — percentuais de usuários distintos, percentis para memória —, então a API é segura para rodar em um servidor sem lidar com dados no nível do usuário. Segundo, alguns recursos são mais restritos do que o número da versão sugere: o conjunto de contagens de erros só está disponível na versão v1alpha1 da API, enquanto v1beta1 e v1alpha1 expõem os mesmos recursos com os mesmos formatos de método. Decida sua versão por recurso, não por projeto.
2. Crie o projeto no Cloud e ative a API
Você ainda precisa de um projeto no Google Cloud com a API ativada, mas uma mudança de 2026 elimina uma etapa com a qual muita gente ainda conta: não é mais necessário vincular sua conta de desenvolvedor do Play ao Cloud Console para usar a Reporting API. Os quatro passos documentados são: criar (ou reutilizar) um projeto no Cloud, ativar a Google Play Developer Reporting API nele, criar uma conta de serviço e conceder a essa conta de serviço acesso dentro do Play Console.
Ativar a API é uma ação de um clique na página da API no Cloud Console. Faça isso no projeto que já contém seu faturamento e IAM, não em um projeto descartável — as chaves de conta de serviço sobrevivem à pessoa que as criou, e projetos órfãos são o motivo pelo qual o monitoramento morre silenciosamente um ano depois.
3. Dê à conta de serviço exatamente um escopo e, depois, um papel no Play Console
Contas de serviço são a escolha documentada para tarefas não assistidas, e se autenticam com uma chave JSON que nunca deve sair do servidor. Cada chamada nesta API é autorizada por um único escopo OAuth:
https://www.googleapis.com/auth/playdeveloperreporting
Depois vêm as permissões que realmente barram seu primeiro 403. Ativar a API não é o mesmo que ter permissão para ler os dados. Vá para Usuários e permissões no Play Console, convide o endereço da própria conta de serviço (your-name@your-project.iam.gserviceaccount.com) e conceda os direitos mínimos necessários para os conjuntos de métricas que você consulta — a orientação do próprio Google é conceder o conjunto mínimo de permissões por ação de API, e conjuntos de métricas diferentes exigem permissões diferentes. Um job de relatórios nunca precisa de acesso de administrador, de gerenciamento de versões ou financeiro.
Guarde o arquivo da chave fora do repositório e mantenha uma conta de serviço por portfólio, em vez de uma por app. Rotacionar uma única credencial é uma tarefa de cinco minutos; rotacionar trinta é um fim de semana inteiro.
4. Descubra os IDs de app que a conta consegue ver
Before any metric call, resolve which apps the credential can reach. The service endpoint is https://playdeveloperreporting.googleapis.com, and the app list comes from:
GET /v1beta1/apps:search
Rode isso uma vez por portfólio e guarde o resultado em cache. É a forma mais barata de provar que o convite do passo 3 funcionou: uma lista vazia com um token válido quase sempre significa que a conta de serviço foi convidada para a conta errada, ou foi convidada mas nunca recebeu uma permissão que inclua visibilidade de apps.
5. Verifique a atualidade antes de confiar em um número
Cada conjunto de métricas responde a um GET simples que retorna o timestamp do datapoint mais recente disponível — sua atualidade —, um valor por granularidade suportada (diária e horária). Comece toda execução agendada por aí em vez de presumir que ontem existe. Use o valor de atualidade retornado diretamente como fim do seu intervalo de consulta, e o job passa a se alinhar sozinho: sem atraso fixo no código, sem resposta vazia na manhã seguinte a um lançamento tranquilo.
Um dado ausente não é um zero. Se o seu data warehouse grava 0,0% porque o intervalo não retornou linhas, seu dashboard vai mostrar um app perfeito até o dia em que alguém conferir o console.
6. Consulte um conjunto com o método POST :query
Os dados vêm de um método :query personalizado no recurso de conjunto de métricas, não de uma chamada de listagem. Cada consulta define uma granularidade, um intervalo de tempo, as métricas e as dimensões para detalhamento:
POST https://playdeveloperreporting.googleapis.com/v1beta1/apps/<package>/crashRateMetricSet:query // body { "timelineSpec": { "aggregationPeriod": "DAILY", "startTime": { "year": 2026, "month": 10, "day": 14 }, "endTime": { "year": 2026, "month": 10, "day": 20 } }, "dimensions": ["versionCode", "countryCode"], "metrics": ["crashRate", "userPerceivedCrashRate", "distinctUsers"], "pageSize": 1000 }
A resposta é uma lista de linhas indexadas pelas dimensões que você solicitou, mais um pageToken quando há mais para ler. O filter restringe as linhas por igualdade de dimensão; a paginação tem o mesmo formato em todos os conjuntos de métricas, então um paginador genérico cobre taxa de falhas, taxa de ANR e memória da mesma forma.
7. Escolha as dimensões de propósito — e fique atento às duas armadilhas de prazo
As dimensões são onde a API supera o console. versionCode transforma uma taxa de falhas de toda a frota em uma verificação de regressão por versão. countryCode isola um mercado onde um novo SDK se comporta mal. As dimensões de dispositivo — deviceModel, deviceType, apiLevel, deviceRamBucket e os campos de SoC, CPU, GPU e tela — separam "nosso código quebrou" de "este chipset quebrou".
Duas armadilhas de fuso horário pegam toda equipe uma vez. A agregação diária é documentada como usando um fuso horário fixo America/Los_Angeles, enquanto a agregação por hora é fixada em UTC. Se o seu dia útil é em CST, um bloco diário não começa quando você pensa, e um lançamento implantado às 09:00 no horário local cai em dois blocos. Segunda armadilha: um dia vazio muitas vezes é apenas atraso de atualização, e é por isso que a etapa 5 vem primeiro.
Há também um limite de desempenho rígido na documentação que vale considerar no design: o tamanho do intervalo solicitado deve ser inversamente proporcional ao tamanho do app e ao número de detalhamentos. Um app grande consultado por trinta dias em seis dimensões vai dar timeout. Faça um loop por janelas curtas para apps grandes em vez de uma única consulta heroica.
8. Deixe o Google detectar as anomalias
Você não precisa montar cálculos de limite sobre essas métricas para ter alertas. A API expõe uma coleção de anomalias que lista as anomalias que o Google já detectou em qualquer um dos conjuntos de dados, filtradas por quando estavam ativas:
GET /v1beta1/apps/<package>/anomalies ?filter=activeBetween("2026-10-19T00:00:00Z","2026-10-21T00:00:00Z") &pageSize=50
Ambos os limites são strings RFC-3339 com deslocamentos UTC permitidos, e qualquer um dos limites aceita o valor especial UNBOUNDED para janelas unilaterais. pageSize tem padrão 10 e limite máximo de 100. Cada anomalia traz seu tipo, gravidade, as dimensões afetadas e as métricas envolvidas, de modo que uma consulta agendada se converte facilmente em uma mensagem sobre a qual uma pessoa pode agir.
Para stack traces em vez de taxas, a mesma API expõe problemas de erro e relatórios de erro — as camadas agrupada e individual — em ambas as versões. É a diferença entre "a taxa de falhas dobrou na v1.4.2" e "aqui está o frame que mudou".
9. Conecte ao ciclo de vida da conta, não apenas ao cronograma
A permissão que você concedeu na etapa 3 fica na conta de desenvolvedor, o que significa que ela acompanha a conta. Quando uma conta do Play muda de mãos — uma transferência, a venda de um portfólio, uma reconstrução após uma suspensão —, o Play Console do novo proprietário precisa reconvidar sua conta de serviço, ou toda chamada retorna 403 enquanto seu dashboard mantém os últimos valores conhecidos. Esse é o modo de falha que vale a pena monitorar explicitamente: alerte sobre 403 e sobre uma lista de apps vazia, não apenas sobre 5xx, porque a API responde tranquilamente "sem dados" para uma credencial que foi silenciosamente desconectada.
Mantenha o monitoramento sem graça: uma conta de serviço por portfólio, uma execução agendada que lê a atualidade e depois consulta os conjuntos que importam, verificação de anomalias como segunda passada e uma única mensagem por dia que fica em silêncio quando nada mudou. Tudo além disso — limites, linhas de base de tendências, painéis por país — é análise que você pode adicionar sem mexer na infraestrutura de novo.
Gerencia contas de desenvolvedor em escala? Cuidamos do lado operacional.
Recebemos sua mensagem e responderemos em até 24 horas.
← Voltar para editar