KappS Base de conhecimento · Perguntas frequentes

Gestão do código de versão e compatibilidade de atualizações no Google Play

Perguntas frequentes Revisão do app e publicação

1. Dois campos, duas funções completamente diferentes. O guia de versionamento do Google os define separadamente: versionCode é "um número inteiro positivo usado como número de versão interno. Esse número ajuda a determinar se uma versão é mais recente que outra, com números maiores indicando versões mais recentes. Este não é o número de versão mostrado aos usuários; esse número é definido pela configuração versionName. O sistema Android usa o valor de versionCode para proteger contra downgrades, impedindo que os usuários instalem um APK com versionCode menor que o da versão atualmente instalada no dispositivo." versionName é "uma string usada como número de versão mostrado aos usuários... O versionName é o único valor exibido aos usuários." A ajuda do Play Console acrescenta o detalhe de operação com que os desenvolvedores tropeçam primeiro: versionCode é "um número inteiro de 32 bits que aumenta de forma consistente a cada nova versão" enquanto versionName é "uma string que representa o número de versão voltado ao usuário, por exemplo, '1.0.0', '1.1 Beta', '2.0'." O marketing pode renomear 4.9 para 5.0 livremente; no momento em que o número inteiro deixa de aumentar, o upload falha. (§https://developer.android.com/studio/publish/versioning / §https://support.google.com/googleplay/android-developer/answer/17367361)

2. O gate de upload do Play é uma única comparação, e é estritamente maior que. A lista oficial de requisitos de atualização traz três condições rígidas, nesta ordem: "O nome do pacote do Android App Bundle atualizado deve ser o mesmo da versão atual. O código de versão deve ser maior que o da versão atual... O app bundle atualizado deve ser assinado com a mesma assinatura da versão atual." Não existe caminho do tipo "igual está ok se o binário for diferente", e não há argumento a apresentar na revisão: a checagem é mecânica e acontece antes de qualquer pessoa ou bot de políticas ver o lançamento. (§https://support.google.com/googleplay/android-developer/answer/9859350)

3. Um versionCode nunca é reutilizável, e o conjunto pertence ao app, não à faixa. O guia de versionamento é direto: "You can't upload an APK to the Play Store with a versionCode you have already used for a previous version." No console, isso aparece como a rejeição conhecida "Version code X has already been used." Como o contador está vinculado à aplicação (o nome do pacote), teste interno, teste fechado, teste aberto e produção usam todos a mesma sequência; para colocar a mesma compilação em uma segunda faixa, você a adiciona "da biblioteca" em vez de enviá-la de novo. Um nome de pacote distinto — um app de staging, uma versão white-label com seu próprio applicationId — tem sua própria sequência, e é exatamente por isso que um app de staging é o lugar certo para queimar códigos durante o debug. (§https://developer.android.com/studio/publish/versioning)

4. O teto é 2.100.000.000, e atingi-lo não é um ticket de suporte, é um estado final. Os dois documentos trazem o mesmo número: "O maior valor que o Google Play permite para versionCode é 2100000000". A página do console detalha a consequência: "Se o versionCode do seu app atingir ou ultrapassar o limite máximo, você não poderá mais enviar novos APKs ou bundles do app ao Google Play para essa aplicação. Isso significa que não haverá mais correções de bugs, novos recursos ou atualizações de compatibilidade para seus usuários". O único remédio indicado pelo Google é que "o Google Play pode conseguir oferecer suporte" — um talvez, não um botão de reiniciar. Para um negócio que lucra com apps no ar, o número é, portanto, um ativo com prazo de validade, e precisa ser gasto como tal. (§https://support.google.com/googleplay/android-developer/answer/17367361)

5. Três hábitos de numeração consomem a faixa mais rápido do que os desenvolvedores esperam. Timestamps Unix em segundos já passaram de 1,79 bilhão e sobem a cada build; um contador global de CI compartilhado entre branches, flavours e apps irmãos avança aos saltos a cada pipeline com falha; e "número da compilação = contagem de commits" explode no momento em que o histórico de um monorepo é reescrito. A própria lista de mitigação do Play é: "Adote uma estratégia sustentável de versionCode: implemente uma estratégia de geração de versionCode que garanta um aumento gradual e consistente e evite o consumo rápido da faixa disponível. Monitore o uso do versionCode: acompanhe regularmente a progressão do versionCode do seu app para antecipar quando ele pode se aproximar do limite. Implemente verificações automatizadas: integre verificações aos seus processos de build e lançamento para alertar ou impedir o uso de valores de versionCode excessivamente altos." (§https://support.google.com/googleplay/android-developer/answer/17367361)

6. Os códigos são consumidos pelo upload, não pela publicação. Enviar para teste interno, deixar um bundle parado na biblioteca ou criar um lançamento em rascunho que depois é descartado — tudo isso deixa o número gasto — "Adicionar da biblioteca" existe justamente porque o mesmo binário pode ser reanexado a um lançamento posterior, mas nunca recriado. Quem "envia uma build para o console só para ver se passa" paga um número de versão por tentativa; em um app de longa vida com um pipeline rápido, é assim que uma folga confortável vira crise anos depois.

7. Interromper não é reverter, porque o Android recusa downgrades. A regra de nível de sistema citada no ponto 1 (um dispositivo não instalará um versionCode inferior ao já instalado) é o motivo pelo qual não existe um botão no console que devolva os usuários à build da semana passada. A orientação de lançamento gradual do Google diz o mesmo em termos operacionais: "Se você encontrar um problema no seu app bundle existente, crie e lance uma nova versão com um app bundle corrigido." Portanto, a única recuperação real de uma build de produção ruim é um novo bundle, com um versionCode superior ao da build ruim, enviado o mais rápido que a revisão permitir — e é exatamente por isso que o slot de emergência no seu esquema de numeração precisa existir antes de você precisar dele. (§https://support.google.com/googleplay/android-developer/answer/6346149)

8. O lançamento gradual é uma ferramenta exclusiva para atualizações e nunca avança sozinho. "Você pode liberar uma atualização do app para produção e para as faixas de teste usando um lançamento gradual. Com um lançamento gradual, sua atualização chega apenas a uma porcentagem dos usuários, que você pode aumentar com o tempo. Lançamentos graduais só podem ser usados para atualizações de apps, não na primeira publicação de um app." E a armadilha que deixa versões travadas em 5% por uma semana: "o percentual de lançamento gradual do seu app não aumenta automaticamente." Quem é responsável pela versão precisa voltar e aumentar o percentual; nada do lado do Google fará isso. Os usuários também não são avisados de que receberam uma atualização gradual - "os usuários não serão notificados se receberem uma versão do seu app em um lançamento gradual" -, então o feedback de uma versão gradual precisa vir dos sinais vitais e do suporte, não das avaliações. (§https://support.google.com/googleplay/android-developer/answer/6346149)

9. O que interromper um lançamento gradual realmente muda. "Se você descobrir um problema, pode interromper um lançamento gradual para ajudar a minimizar o número de usuários que enfrentam o problema com o seu app. Quando você interrompe um lançamento gradual, nenhum usuário adicional receberá a versão do app no seu lançamento gradual existente. Os usuários que já receberam a versão do app no seu lançamento gradual permanecerão nessa versão." Duas consequências decorrem disso e as pessoas não percebem: retomar não reorganiza o público — "Quando você interrompe e depois retoma o lançamento da sua versão, você estará afetando o mesmo conjunto de usuários" — e iniciar uma nova versão antes de a anterior terminar reutiliza essa mesma coorte: "Quando você faz um lançamento gradual de uma nova versão antes de concluir o lançamento da versão anterior, a nova versão usará o mesmo grupo de usuários da versão anterior (dependendo do percentual do lançamento)." Sua correção é validada pelos mesmos 5% azarados, não por uma amostra nova. (§https://support.google.com/googleplay/android-developer/answer/6346149)

10. Interromper uma versão totalmente distribuída: o que isso faz e o que não faz. "Se você descobrir um problema crítico no seu app, o recurso de interromper o lançamento minimiza a interrupção para os usuários ao impedir que usuários novos e existentes instalem ou atualizem para a versão afetada do seu app. Quando você interrompe um lançamento completo, a versão anterior do seu app volta a ficar disponível para novos usuários, e qualquer pessoa que não esteja usando a versão interrompida do seu app também." Isso é uma mudança de distribuição, não uma desinstalação: "A versão interrompida deixa de ser distribuída aos usuários", mas os dispositivos que já a receberam continuam com ela, novamente por causa da proteção contra downgrade. Três limites estão escritos na mesma página: funciona "em qualquer faixa, exceto as faixas de teste interno"; "Você não pode interromper sua primeira versão em uma faixa"; e "Se a sua versão anterior tiver uma violação de política, ela não pode ser usada no lugar da versão interrompida." Uma retomada posterior pode ir para qualquer percentual, que é a forma correta de reintroduzir gradualmente uma build corrigida. (§https://support.google.com/googleplay/android-developer/answer/16285429)

11. Uma versão pendente por faixa — e é isso que bloqueia um hotfix no pior momento. "Você não pode criar uma nova versão quando há versões pendentes. Implemente 100% das versões em lançamento gradual ou remova as alterações na página Visão geral da publicação e descarte as versões não publicadas primeiro." Um lançamento gradual de 20% abandonado, uma submissão de revisão pela metade ou uma retenção de publicação gerenciada parada na faixa de produção vão ficar entre você e o build de emergência. O hábito que evita isso: após cada versão, feche o ciclo — implemente 100% ou remova e descarte — e registre o estado no log de versões para que a próxima pessoa (ou o próximo você) não fique depurando um console que se recusa a abrir uma nova versão. (§https://support.google.com/googleplay/android-developer/answer/9859348)

12. Um esquema de numeração que sobrevive a dez anos de versões. Reserve faixas de largura fixa para que a aritmética continue legível e o teto fique bem distante: versionCode = major * 100000 + minor * 1000 + patch * 10 + hotfix, o que permite majors de 1 a 20999, mil minors e dez slots de patch/hotfix cada. Mantenha a faixa de trabalho visivelmente abaixo de 2,1 bilhões no seu script de build e faça o build falhar (não o upload) quando o valor calculado cruzar um limite flexível que você definir, digamos, em 1,5 bilhão. Dê ao CI autoridade para incrementar apenas no upload, nunca a cada commit; rode todo build exploratório sob o applicationId de staging para que seus códigos sejam gastos em outra sequência; e registre o versionCode enviado nas notas da versão, para que o número seja auditável em vez de conhecimento tribal.

13. Checklist de pré-upload que detecta tudo isso de uma só vez: (a) o versionCode é estritamente maior que qualquer código já enviado para este app, em todas as faixas — não apenas na faixa de destino; (b) o versionName é apenas texto de exibição e pode se repetir ou saltar livremente; (c) o nome do pacote não mudou e o bundle está assinado com a chave de assinatura ativa — trocar a chave de assinatura do app significa que "usuários das faixas interna e fechada que já instalaram seu app não receberão mais atualizações. Esses usuários precisam desinstalar e reinstalar o app para receber atualizações"; (d) o caminho de atualização é testado em um dispositivo que já tem a versão anterior instalada, porque uma instalação limpa não prova nada sobre uma atualização; (e) o número é verificado em relação ao teto de 2.100.000.000 e ao seu próprio limite flexível; (f) nenhuma outra versão fica pendente na faixa de destino; e (g) ainda há um espaço de código de emergência livre na faixa atual. Cada um desses itens é um campo ou um estado, não uma avaliação subjetiva — por isso a lista inteira pode viver no CI e no checklist de lançamento, em vez de na memória de alguém. (§https://support.google.com/googleplay/android-developer/answer/9859348)