Atualizando sua ficha da Play Store com a Google Play Developer API

A Google Play Developer API (cujo nome oficial é Android Publisher API) permite alterar uma ficha da loja — título, descrições, capturas de tela, gráfico de destaque — sem abrir o Play Console. É isso que você quer se estiver enviando textos localizados a partir de um CMS, sincronizando capturas de tela de um pipeline de build ou atualizando dezenas de fichas de idiomas de uma só vez. Este é o fluxo completo para fazer isso corretamente, incluindo as partes que a documentação de referência esconde.

Um edit é uma transação, não um conjunto de gravações ao vivo

O modelo mental que evita mais dor de cabeça: você nunca edita a ficha ao vivo diretamente. Você abre um edit, que é uma cópia privada de preparação do estado implantado atual do app — fichas, imagens, faixas, tudo é copiado. Você faz todas as suas alterações nessa cópia. Depois você confirma tudo de uma vez, ou abandona e nada aconteceu.

A própria documentação do Google é direta: "Changes made within an edit are not live until the edit is committed." No commit, se não houver erros de validação, todas as alterações do edit vão ao ar juntas, substituindo o estado atual. Se a validação falhar, a API lança um erro e a ficha ao vivo permanece intocada. Então o ciclo de vida é exatamente quatro movimentos:

• edits.insert — cria o edit e retorna um editId.
• modificar — edits.listings.update para o texto por idioma, edits.images.upload / deleteall para capturas de tela e imagens gráficas.
• edits.commit — valida tudo e depois publica tudo de forma atômica.
• edits.abandon — descarta o rascunho, a ficha ao vivo continua inalterada.

Uma restrição rígida para projetar em torno dela: uma conta pode ter apenas um edit aberto por vez, e se alguém confirmar um edit ou editar o app pela interface do Play Console, todos os outros edits abertos para aquele app são invalidados. Trate um edit como algo de vida curta — abra, escreva, confirme. Não deixe um aberto por horas enquanto uma pessoa clica pelo console.

Autenticação: uma conta de serviço, mais o convite que todo mundo esquece

Para um atualizador automatizado, você quer uma conta de serviço, não OAuth de usuário. Dois sistemas estão envolvidos, e eles são realmente separados:

1. Google Cloud. Crie uma conta de serviço, habilite a Google Play Android Developer API no projeto e baixe uma chave JSON. O único escopo necessário é https://www.googleapis.com/auth/androidpublisher.
2. Play Console. Vá em Usuários e permissões, clique em Convidar novos usuários, cole o e-mail da conta de serviço (o endereço ...@...iam.gserviceaccount.com) e conceda acesso ao app. Só então essa chave poderá alterar sua ficha.

Mais uma pré-condição: o app já precisa existir e ter tido pelo menos um lançamento (pelo menos um APK/AAB enviado pelo console). Você não consegue inicializar um app totalmente novo apenas pela API.

As quatro chamadas, em REST

Atualizando o texto da ficha

edits.listings.update é um PUT — uma substituição completa da ficha daquele idioma. Tudo o que você enviar se torna a ficha; campos que você deixar de fora são apagados, não preservados. Então, se você quiser mudar só a descrição curta, ainda precisa enviar o título e a descrição completa junto, ou vai apagá-los. Quando você realmente quer uma mudança parcial, existe um edits.listings.patch separado que mescla apenas os campos fornecidos. Para a maioria dos pipelines, o PUT completo é mais limpo — você já está renderizando a ficha completa a partir da sua fonte de verdade, então substituí-la por inteiro é exatamente o certo.

Os três campos de texto e seus limites: title até 30 caracteres, shortDescription até 80, fullDescription até 4000. Um recurso de ficha por idioma, identificado pela tag de idioma BCP-47 na URL (en-US, de-DE, ja-JP, e assim por diante). Para atualizar dez idiomas, você faz dez chamadas listings.update dentro do mesmo edit — depois um único commit publica todas juntas.

Enviando capturas de tela e a gráfico de destaque

As imagens são anexadas por idioma e por tipo de imagem. O tipo de imagem é um enum, e cada espaço de recurso na ficha mapeia para um destes valores:

• phoneScreenshots, sevenInchScreenshots, tenInchScreenshots — os conjuntos de capturas de tela de telefone e tablet.
• tvScreenshots, wearScreenshots — Android TV e Wear OS.
• featureGraphic — o banner de 1024×500 exibido no topo da ficha.
• icon, tvBanner — o ícone do app e o banner para TV.

edits.images.upload adiciona uma imagem de um determinado idioma e tipo ao edit. Não existe uma chamada para "definir o array inteiro", então o padrão confiável para substituir capturas de tela é usar edits.images.deleteall para aquele idioma e tipo de imagem primeiro, depois enviar o novo conjunto na ordem em que quer que apareçam. edits.images.list lê o que está atualmente no edit, e edits.images.delete remove uma única imagem pelo id, se você precisar de mudanças cirúrgicas. Tudo isso permanece dentro do edit até você confirmar.

Confirmando — e o que "ao vivo" realmente significa

Algumas coisas que vale a pena esclarecer, porque costumam surpreender as pessoas:

• Não é preciso um novo build. Confirmar um edit que só altera a ficha não exige um APK/AAB novo. Texto e imagens são metadados; você pode atualizá-los quantas vezes quiser sobre o release existente. (O app só precisa ter aquele release anterior.)
• O commit valida e depois publica. Se uma captura de tela tiver a dimensão errada ou um campo for longo demais, o commit falha e a ficha ao vivo nunca muda — você corrige e confirma de novo.
• Não é instantâneo. Após um commit bem-sucedido, as mudanças podem levar até várias horas para aparecer, assim como edições feitas manualmente no Play Console. Não trate um 200 no commit como "já visível para os usuários".
• Abandonar não custa nada. Se um teste ficou errado, edits.abandon descarta o rascunho sem nenhum efeito na ficha ao vivo. Útil para validar um pipeline sem risco.

O caminho sem código: projetar, traduzir, publicar

A API acima é a ferramenta certa se você tem tempo de engenharia para investir e uma fonte de verdade para sincronizar. O que ela não faz é criar os recursos. Você ainda precisa projetar as capturas de tela, escrever o título e as duas descrições, e produzir tudo isso por idioma — a API só envia o que você entregar a ela.

É essa a parte que o Mokbi resolve. Você projeta as capturas de tela no navegador, rascunha o título, a descrição curta e a descrição completa junto com elas, e traduz a ficha inteira para 50 idiomas em uma única passagem — assim as dez chamadas listings.update mencionadas acima têm texto real e localizado para enviar, em vez de texto de exemplo.

E a própria publicação? O Mokbi também faz isso. Para o Google Play, ele executa exatamente este fluxo por trás dos panos (edits.insert → listings.update → upload de imagens → commit), então sua ficha e recursos localizados vão ao ar sem que você escreva uma linha do código acima. Para a App Store, ele prepara a versão no App Store Connect, preenchida e pronta para envio, já que a Apple exige que você mesmo pressione o Submit final e passe pela revisão. Projetar as capturas de tela e a gráfico de destaque, escrever a ficha, traduzi-la para 50 idiomas e publicá-la são uma única passagem contínua.

O que ler a seguir

• Atualizar uma ficha da Play sem lançar um novo build
• Requisitos da ficha da Play e checklist de recursos
• O equivalente da App Store Connect API, para iOS

Abrir o editor →