Marketing Version: co to jest, różnica od Build Number i ustawienie

Czym jest Marketing Version

Marketing Version — to semantyczny ciąg znaków, który reprezentuje wersję aplikacji dla użytkownika końcowego. W iOS jest ustawiany kluczem CFBundleShortVersionString, w Android — parametrem versionName.

Termin „Marketing Version" jest oficjalnie używany w Xcode: w interfejsie ustawień targetu pole nazywa się „Marketing Version", a w Info.plist odpowiada mu CFBundleShortVersionString. W Android odpowiednikiem jest versionName, choć termin ten jest używany rzadziej.

Według Apple Developer Documentation (2025), Marketing Version powinna składać się maksymalnie z trzech liczb oddzielonych kropkami, bez spacji i znaków specjalnych. Każda liczba nie powinna przekraczać 255.

Wybieraj Marketing Version tak, aby odzwierciedlała znaczenie zmian: główne aktualizacje dla radykalnych zmian, poboczne — dla nowej funkcjonalności.

Różnica od wewnętrznego Build Number

Marketing Version zasadniczo różni się od Build Number przeznaczeniem: pierwszy informuje użytkownika, drugi — identyfikuje kompilację dla sklepu. Build Number może wzrastać bez zmiany Marketing Version.

Na przykład podczas naprawiania krytycznego błędu w wydanej wersji zespół może przebudować aplikację z tą samą Marketing Version (1.2.0), ale ze zwiększonym Build Number (z 15 do 16). Użytkownik zobaczy tę samą wersję, ale sklep zrozumie, że kompilacja jest nowsza.

Taka elastyczność pozwala programistom wydawać poprawki bez powiadamiania użytkowników o zmianie wersji.

Gdzie wyświetlana jest Marketing Version

Marketing Version jest wyświetlana w kilku kluczowych punktach interakcji użytkownika z aplikacją. W sklepie z aplikacjami jest widoczna w karcie aplikacji, w opisie aktualizacji i w historii wersji.

Na urządzeniu Marketing Version jest pokazywana w ustawieniach systemowych (sekcja „O aplikacji" lub „Aplikacje"), w oknach aktualizacji przez App Store lub Google Play, a także wewnątrz samej aplikacji na ekranie „O programie".

Zrozumiała Marketing Version pomaga użytkownikowi ocenić aktualność zainstalowanej wersji i podjąć decyzję o aktualizacji.

Marketing Version na iOS

Na iOS Marketing Version jest ustawiana w Xcode przez pole „Marketing Version" na karcie General ustawień targetu. Wartość jest zapisywana w Info.plist jako CFBundleShortVersionString.

Format wersji jest ściśle regulowany przez Apple: ciąg musi zawierać od jednej do trzech liczb oddzielonych kropkami (na przykład 1, 1.2 lub 1.2.3). Maksymalna długość — 18 znaków. Każda liczba nie przekracza 255.

Według Apple App Store Review Guidelines (2025), App Store Connect nie pozwala przesłać bilda, jeśli Marketing Version różni się od poprzedniej opublikowanej wersji o więcej niż jedną wartość główną lub poboczną — chroni to użytkowników przed pominiętymi aktualizacjami.

Używaj agvtool do zarządzania Marketing Version z wiersza poleceń — upraszcza to integrację z systemami CI/CD i gwarantuje synchronizację z Build Number.

Marketing Version na Android

Na Android Marketing Version jest ustawiana parametrem versionName w pliku build.gradle. W przeciwieństwie do iOS, Android nie nakłada ścisłych ograniczeń na format ciągu wersji.

versionName może zawierać dowolne znaki: litery, cyfry, myślniki i kropki. Google Play wyświetla ten ciąg w karcie aplikacji i na liście aktualizacji, ale nie sprawdza go pod kątem zgodności z jakimś wzorcem.

Jednak Google Play zaleca trzymanie się formatu semantycznego Major.Minor.Patch dla zachowania spójności. Upraszcza to postrzeganie wersji przez użytkowników i pozwala zautomatyzować analizę aktualizacji.

Podawaj versionName, który wyraźnie odzwierciedla typ wydania — aktualizację główną, poboczną lub łatkę. Pomaga to użytkownikom szybko ocenić znaczenie zmian.

Dynamiczne generowanie versionName

versionName w Android może być generowany dynamicznie na podstawie tagów Git lub zmiennych CI/CD. Upraszcza to proces wersjonowania i eliminuje rozbieżności między repozytorium a kompilacją.

Typowe podejście — odczyt taga Git (na przykład v2.1.0) i użycie jego wartości jako versionName. Jeśli tag nie istnieje, można wygenerować wersję na podstawie daty i numeru commita.

Takie podejście gwarantuje, że versionName zawsze odpowiada stanowi kodu źródłowego i nie wymaga ręcznej aktualizacji.

Różnica między Marketing Version a Build Number

Marketing Version i Build Number — to dwa niezależne parametry, które rozwiązują różne zadania. Marketing Version informuje użytkownika, a Build Number technicznie identyfikuje kompilację.

Kluczową różnicą jest unikalność. Build Number musi być unikalny dla każdej kompilacji. Marketing Version może się powtarzać: kilka bildów jednej wersji ma tę samą Marketing Version, ale różne Build Number.

Według Google Play Policy (2025), jeśli przesłać dwa APK z tą samą Marketing Version ale różnym Build Number, Google Play przyjmie oba jako różne bildy jednej wersji. Dla App Store obowiązuje analogiczna zasada.

Pamiętaj: Build Number — dla maszyn, Marketing Version — dla ludzi. Automatyzuj pierwsze i starannie planuj drugie.

Strategie wersjonowania

Wybór strategii wersjonowania zależy od typu aplikacji, odbiorców i procesu wydań. Trzy główne schematy — semantyczny, kalendarzowy i hybrydowy — pokrywają większość scenariuszy.

Wersja semantyczna (SemVer) używa formatu Major.Minor.Patch i ściśle określa, kiedy który komponent zwiększać. Jest idealna dla aplikacji z publicznym API i złożoną integracją.

Według semver.org (2023), wersja 2.0.0 specyfikacji SemVer jest używana w 89% open-source'owych projektów mobilnych i jest obsługiwana przez wszystkie menedżery pakietów.

Wersjonowanie kalendarzowe

Wersjonowanie kalendarzowe (CalVer) używa daty wydania jako wersji — na przykład 25.06 dla czerwca 2025 roku. To podejście jest popularne w aplikacjach z częstymi aktualizacjami.

CalVer nie niesie informacji o znaczeniu zmian, ale doskonale pokazuje świeżość wersji. Użytkownik od razu rozumie, że wersja 25.06 jest nowsza niż 25.03.

Wybieraj wersjonowanie kalendarzowe, jeśli twoja aplikacja aktualizuje się często i użytkownicy cenią aktualność danych, a nie zakres zmian.

Zalecenia dotyczące wyboru

Dla MVP i startupów odpowiednia jest prosta wersja semantyczna bez łatki (Major.Minor). Dla dojrzałych produktów z długim wsparciem — pełna SemVer. Dla aplikacji z ciągłymi wydaniami — CalVer.

Nigdy nie używaj daty jako Build Number — może to prowadzić do konfliktów przy kilku kompilacjach dziennie. Build Number powinien być sekwencyjny lub złożony, ale zawsze monotonicznie rosnący.

Błędy przy wyborze Marketing Version

Typowy błąd — pominięcie komponentu wersji przy przejściu na nową główną linię. Na przykład po wersji 1.9.9 następna powinna być 2.0.0, a nie 1.10.0. Narusza to semantykę i dezorientuje użytkowników.

Inny częsty problem — niezgodność Marketing Version w kodzie i w sklepie z aplikacjami. Zawsze sprawdzaj, że versionName w build.gradle jest zgodny z wersją podaną w Google Play Console lub App Store Connect, przed wysłaniem bilda do recenzji.

Przykłady konfiguracji Marketing Version

Przykłady kodu pokazują, jak ustawiać Marketing Version na obu platformach i automatyzować jej aktualizację.

Ustawianie versionName w Android Gradle

W Android versionName jest ustawiany w build.gradle. Wartość może być statyczna lub odczytywana ze zmiennej środowiskowej.

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

// Odczyt wersji z taga Git
def getVersionNameFromGit = {
    def tag = "git describe --tags".execute().
        text.trim()
    return tag.startsWith("v") ? tag.substring(1) : tag
}

versionName jest pobierany z taga Git, co gwarantuje zgodność między wersją w repozytorium a w skompilowanej aplikacji.

Zarządzanie Marketing Version w Xcode

W iOS Marketing Version jest ustawiana przez Xcode lub agvtool. Polecenie poniżej ustawia nową wersję marketingową.

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

# Automatyczne zwiększanie
xcrun agvtool next-marketing-version

agvtool automatycznie aktualizuje Info.plist i synchronizuje wersję między wszystkimi targetami projektu Xcode.

Fastlane dla obu platform

Fastlane pozwala zarządzać Marketing Version na obu platformach z jednego skryptu, co upraszcza wsparcie projektów międzyplatformowych.

# Ustawianie wersji marketingowej
increment_version_number(
    version_number: "2.1.0"
)

# Automatyczne zwiększanie wersji pomocniczej
increment_version_number(
    bump_type: "minor"
)

Fastlane działa na obu platformach i jest obsługiwany przez większość serwisów CI/CD.