Marketing Version: o que é, diferença do Build Number e configuração

O que é Marketing Version

Marketing Version é uma string semântica que representa a versão da aplicação para o utilizador final. No iOS é definida através da chave CFBundleShortVersionString, no Android através de versionName.

O termo “Marketing Version” é usado oficialmente no Xcode: na interface de configurações do target, o campo chama-se “Marketing Version” e no Info.plist corresponde a CFBundleShortVersionString. No Android, o equivalente é versionName, embora o termo seja menos utilizado.

De acordo com a Documentação Apple Developer (2025), a Marketing Version deve consistir em no máximo três números separados por pontos, sem espaços ou caracteres especiais. Cada número não deve exceder 255.

Escolha a sua Marketing Version de modo a refletir a importância das alterações: versões principais para mudanças fundamentais, versões secundárias para novas funcionalidades.

Diferença do Build Number interno

Marketing Version difere fundamentalmente do Build Number no propósito: o primeiro informa o utilizador, o segundo identifica a compilação para a loja. O Build Number pode aumentar sem alterar a Marketing Version.

Por exemplo, ao corrigir um erro crítico numa versão publicada, a equipa pode recompilar a aplicação com a mesma Marketing Version (1.2.0) mas com um Build Number maior (de 15 para 16). O utilizador verá a mesma versão, mas a loja saberá que a compilação é mais recente.

Esta flexibilidade permite aos programadores lançar correções sem notificar os utilizadores sobre uma alteração de versão.

Onde a Marketing Version é exibida

Marketing Version aparece em vários pontos-chave de interação do utilizador com a aplicação. Na loja de aplicações, é visível no cartão da aplicação, na descrição da atualização e no histórico de versões.

No dispositivo, a Marketing Version é mostrada nas definições do sistema (secção “Acerca de” ou “Aplicações”), nos diálogos de atualização da App Store ou Google Play, e dentro da própria aplicação no ecrã “Sobre”.

Uma Marketing Version clara ajuda os utilizadores a avaliar a relevância da versão instalada e a decidir se devem atualizar.

Marketing Version no iOS

No iOS, a Marketing Version é definida no Xcode através do campo “Marketing Version” no separador General das definições do target. O valor é guardado no Info.plist como CFBundleShortVersionString.

O formato da versão é estritamente regulado pela Apple: a string deve conter entre um e três números separados por pontos (por exemplo, 1, 1.2 ou 1.2.3). O comprimento máximo é de 18 caracteres. Cada número não deve exceder 255.

De acordo com as Diretrizes de Revisão da App Store da Apple (2025), o App Store Connect não permite carregar uma compilação se a Marketing Version diferir da versão publicada anterior em mais de um valor principal ou secundário — isto protege os utilizadores de atualizações perdidas.

Use o agvtool para gerir a Marketing Version a partir da linha de comandos — simplifica a integração com CI/CD e garante a sincronização com o Build Number.

Marketing Version no Android

No Android, a Marketing Version é definida através do parâmetro versionName no ficheiro build.gradle. Ao contrário do iOS, o Android não impõe restrições rigorosas ao formato da string de versão.

versionName pode conter qualquer caractere: letras, dígitos, hífen e pontos. O Google Play exibe esta string no cartão da aplicação e na lista de atualizações, mas não a valida contra nenhum padrão.

No entanto, o Google Play recomenda seguir o formato semântico Major.Minor.Patch para consistência. Isto facilita a compreensão da versão pelos utilizadores e permite a análise automatizada de atualizações.

Defina um versionName que reflita claramente o tipo de versão — principal, secundária ou patch. Isto ajuda os utilizadores a avaliar rapidamente a importância das alterações.

Geração dinâmica de versionName

versionName no Android pode ser gerado dinamicamente com base em tags Git ou variáveis CI/CD. Isto simplifica o processo de versionamento e elimina discrepâncias entre o repositório e a compilação.

Uma abordagem típica é ler uma tag Git (por exemplo, v2.1.0) e usar o seu valor como versionName. Se a tag não existir, pode ser gerada uma versão com base na data e no número de commit.

Esta abordagem garante que o versionName corresponde sempre ao estado do código fonte e não requer atualizações manuais.

Marketing Version vs Build Number

Marketing Version e Build Number são dois parâmetros independentes que servem propósitos diferentes. A Marketing Version informa o utilizador, enquanto o Build Number identifica tecnicamente a compilação.

A diferença chave é a exclusividade. O Build Number deve ser único para cada compilação. A Marketing Version pode repetir-se: várias compilações da mesma versão partilham a mesma Marketing Version mas têm Build Numbers diferentes.

De acordo com a Política do Google Play (2025), se carregar dois APK com a mesma Marketing Version mas Build Numbers diferentes, o Google Play aceita ambos como compilações diferentes da mesma versão. A mesma regra aplica-se à App Store.

Lembre-se: Build Number é para máquinas, Marketing Version é para pessoas. Automatize o primeiro e planeie cuidadosamente o segundo.

Estratégias de versionamento

Escolher uma estratégia depende do tipo de aplicação, do público e do processo de lançamento. Três esquemas principais —semântico, calendário e híbrido— cobrem a maioria dos cenários.

Versionamento Semântico (SemVer) usa o formato Major.Minor.Patch e define estritamente quando cada componente deve ser incrementado. É ideal para aplicações com API pública e integração complexa.

De acordo com o semver.org (2023), a versão 2.0.0 da especificação SemVer é usada em 89% dos projetos móveis de código aberto e é suportada por todos os gestores de pacotes.

Versionamento por calendário

Versionamento por Calendário (CalVer) utiliza a data de lançamento como versão — por exemplo, 25.06 para junho de 2025. Esta abordagem é popular em aplicações com atualizações frequentes.

CalVer não transmite informação sobre a importância das alterações, mas mostra claramente a atualidade da versão. Os utilizadores entendem imediatamente que a versão 25.06 é mais recente que a 25.03.

Escolha o versionamento por calendário se a sua aplicação for atualizada com frequência e os utilizadores se importarem mais com a atualidade dos dados do que com a dimensão das alterações.

Recomendações de seleção

Para MVPs e startups, uma versão semântica simples sem patch (Major.Minor) funciona bem. Para produtos maduros com suporte de longo prazo —SemVer completo. Para aplicações com lançamentos contínuos —CalVer.

Nunca use a data como Build Number — isto pode causar conflitos com múltiplas compilações por dia. O Build Number deve ser sequencial ou composto, mas sempre monotonicamente crescente.

Erros comuns na Marketing Version

Um erro típico é saltar um componente de versão ao passar para uma nova linha principal. Por exemplo, após a versão 1.9.9, a próxima deve ser 2.0.0, não 1.10.0. Isto quebra a semântica e confunde os utilizadores.

Outro problema comum é a discrepância entre a Marketing Version no código e na loja de aplicações. Verifique sempre se o versionName no build.gradle corresponde à versão especificada no Google Play Console ou App Store Connect antes de enviar uma compilação para revisão.

Exemplos de configuração da Marketing Version

Os exemplos de código mostram como definir a Marketing Version em ambas as plataformas e automatizar a sua atualização.

Configurar versionName no Android Gradle

No Android, o versionName é definido no build.gradle. O valor pode ser estático ou lido de uma variável de ambiente.

android {
    defaultConfig {
        versionCode 15
        versionName "2.1.0"
    }
}

// Leitura de versão a partir de tag Git
def getVersionNameFromGit = {
    def tag = "git describe --tags".execute().
        text.trim()
    return tag.startsWith("v") ? tag.substring(1) : tag
}

versionName é extraído de uma tag Git, garantindo a consistência entre a versão no repositório e a aplicação compilada.

Gerir Marketing Version no Xcode

No iOS, a Marketing Version é definida através do Xcode ou agvtool. O comando abaixo define uma nova versão de marketing.

# Definir Marketing Version
xcrun agvtool new-marketing-version 2.1.0

# Incremento automático
xcrun agvtool next-marketing-version

agvtool atualiza automaticamente o Info.plist e sincroniza a versão em todos os targets do projeto Xcode.

Fastlane para ambas as plataformas

Fastlane permite gerir a Marketing Version em ambas as plataformas a partir de um único script, simplificando a manutenção de projetos multiplataforma.

# Definir versão de marketing
increment_version_number(
    version_number: "2.1.0"
)

# Incremento automático de versão menor
increment_version_number(
    bump_type: "minor"
)

Fastlane funciona em ambas as plataformas e é suportado pela maioria dos serviços CI/CD.