Version Name: istota parametru i ustawienie

Czym jest Version Name

Version Name — to ciąg semantyczny, który identyfikuje wydanie aplikacji dla użytkownika. W przeciwieństwie do technicznych identyfikatorów kompilacji, ten parametr niesie znaczenie: na jego podstawie użytkownik ocenia, jak bardzo nowa aktualizacja różni się od poprzedniej.

Version Name wyświetla się w karcie aplikacji w Google Play i App Store, w sekcji „O aplikacji” na urządzeniu, a także w systemowych oknach dialogowych aktualizacji. Deweloperzy podają go w plikach konfiguracyjnych projektu przed kompilacją wersji wydaniowej.

Według Semantic Versioning 2.0 (2023), format Major.Minor.Patch jest używany w 78% aplikacji mobilnych. Wersja major zmienia się przy niekompatybilnych zmianach API, minor — przy dodawaniu funkcjonalności, patch — przy naprawianiu błędów.

Używaj Version Name do komunikacji z użytkownikiem: powinien od razu rozumieć, jak dużą aktualizację otrzymuje — major, minor czy korekcyjną.

Struktura wersji semantycznej

Wersja semantyczna składa się z trzech liczb oddzielonych kropkami: Major.Minor.Patch. Każdy z tych komponentów odpowiada za określony poziom zmian w aplikacji.

Wersja major (Major) zwiększa się przy wprowadzaniu radykalnych zmian, które łamią wsteczną kompatybilność. Wersja minor (Minor) dodaje nową funkcjonalność bez naruszania istniejącej. Patch zawiera tylko poprawki błędów.

Na przykład wersja 3.2.1 oznacza: trzecia wersja major, druga aktualizacja minor, pierwszy patch. Taki system jest zrozumiały zarówno dla deweloperów, jak i użytkowników.

Gdzie wyświetla się Version Name

Version Name jest widoczny dla użytkownika w kilku kluczowych miejscach. W sklepie z aplikacjami wyświetla się w nagłówku karty aplikacji i na liście aktualizacji. Na urządzeniu — w ustawieniach systemowych w sekcji „O aplikacji”.

W Google Play Version Name pokazuje się pod nazwą aplikacji i wpływa na decyzję użytkownika o aktualizacji. W App Store ciąg wersji wyświetla się w tym samym miejscu przy przeglądaniu strony aplikacji.

Według badań Apptentive (2024), 67% użytkowników sprawdza wersję aplikacji przed aktualizacją, a zrozumiała semantyka zwiększa konwersję na instalację o 23%.

Version Name na Android

Na Android Version Name ustawia się parametrem versionName w pliku build.gradle (poziomu modułu). Ten parametr jest ciągiem znaków i może zawierać dowolne symbole, w tym kropki, myślniki i litery.

Parametr deklaruje się wewnątrz bloku android.defaultConfig wraz z obowiązkowym parametrem versionCode. Android nie nakłada ograniczeń na format ciągu, ale Google Play zaleca używanie formatu semantycznego.

Według Android Developers (2025), Google Play używa versionName do wyświetlania w interfejsie sklepu, ale nie analizuje jego zawartości programowo — tylko versionCode wpływa na logikę aktualizacji.

Podawaj Version Name w formacie Major.Minor.Patch i synchronizuj go z tagiem w systemie kontroli wersji dla jednoznacznej identyfikacji wydania.

Cechy versionName w Gradle

Gradle umożliwia ustawianie versionName statycznie w build.gradle lub dynamicznie przez skrypty kompilacji. Dynamiczna generacja jest przydatna do automatycznych kompilacji nocnych i pipeline’ów CI/CD.

W build.gradle można używać zmiennych środowiskowych, parametrów wiersza poleceń lub wywołań skryptów shell do tworzenia versionName. Typowe podejście to odczyt wersji z pliku version.properties.

Taka elastyczność pozwala zespołom zautomatyzować proces wersjonowania i wyeliminować czynnik ludzki przy przygotowaniu wydania.

Version Name na iOS

Na iOS Version Name ustawia się kluczem CFBundleShortVersionString w pliku Info.plist. To obowiązkowy parametr do publikacji aplikacji w App Store i jest ściśle typowany jako ciąg znaków.

W przeciwieństwie do Androida, App Store Connect sprawdza format Version Name i wymaga zgodności ze wzorem liczb oddzielonych kropkami. Maksymalna długość ciągu to 18 znaków, a każdy komponent wersji nie może przekraczać 255.

Według Apple Developer Documentation (2025), CFBundleShortVersionString jest używany przez App Store do wyświetlania wersji w interfejsie sklepu i w systemowych oknach dialogowych na urządzeniu użytkownika.

Przy przesyłaniu kompilacji do App Store Connect upewnij się, że Version Name odpowiada wersji podanej w materiałach marketingowych — upraszcza to komunikację z użytkownikami.

Integracja z Xcode

Xcode udostępnia interfejs graficzny do zmiany Version Name w ustawieniach targetu. Pole „Marketing Version” znajduje się na zakładce General w sekcji Identity. Zmiany są automatycznie zapisywane w Info.plist.

Do automatyzacji można używać skryptów kompilacji w Xcode Build Phases lub narzędzia agvtool (Apple Generic Version Tool). agvtool umożliwia zarządzanie wersjami z wiersza poleceń i integruje się z CI/CD.

Takie podejście jest szczególnie wygodne przy używaniu fastlane lub Jenkins do automatycznej kompilacji i dostarczania aplikacji.

Różnice między Version Name a Build Number

Version Name i Build Number pełnią różne zadania w procesie tworzenia. Version Name to ciąg użytkownika, a Build Number to wewnętrzny numeryczny identyfikator, który jednoznacznie identyfikuje każdą kompilację.

Build Number (versionCode w Android, CFBundleVersion w iOS) obowiązkowo zwiększa się z każdą nową kompilacją i jest używany przez sklepy z aplikacjami do określania, która wersja jest nowsza. Version Name może pozostać niezmieniony dla kilku kompilacji tej samej wersji.

Według Google Play Policy (2025), dwie aplikacje z tym samym versionCode są uznawane za tę samą wersję — versionCode musi być unikalny dla każdego APK. Version Name nie bierze udziału w tym sprawdzeniu.

Zawsze zwiększaj Build Number przy każdej kompilacji i zmieniaj Version Name tylko przy zmianie funkcjonalności — zapobiega to konfliktom przy publikacji.

Jak wybierać Version Name

Wybór Version Name zależy od strategii wersjonowania zespołu. Najpopularniejszym podejściem jest wersjonowanie semantyczne (SemVer), ale istnieją również alternatywne schematy, takie jak wersjonowanie kalendarzowe lub wersjonowanie według daty wydania.

Semantic Versioning 2.0 zaleca format Major.Minor.Patch z opcjonalnymi sufiksami pre-release. Dla aplikacji mobilnych popularny jest również schemat Major.Minor, gdzie pomija się patch dla uproszczenia odbioru.

Wersjonowanie kalendarzowe (CalVer) używa daty wydania jako numeru wersji — na przykład 25.06 (rok i miesiąc). To podejście jest wygodne dla aplikacji z częstymi wydaniami, gdzie semantyka nie ma znaczenia.

Zalecenia dotyczące wyboru schematu

Wersjonowanie semantyczne jest odpowiednie dla aplikacji z publicznym API, gdzie ważna jest wsteczna kompatybilność. Użytkownicy i integratorzy rozumieją, jakich zmian oczekiwać przy aktualizacji.

Wersjonowanie kalendarzowe wybiera się dla aplikacji, gdzie dla użytkownika ważna jest świeżość wydania, a nie zakres zmian. Na przykład agregatory wiadomości lub aplikacje pogodowe.

Schemat hybrydowy łączy oba podejścia: Major.Minor.RC, gdzie RC to numer kompilacji dla konkretnego kandydata do wydania. Taki schemat jest wygodny przy aktywnym beta-testowaniu.

Przykłady konfiguracji Version Name

Przykłady kodu poniżej pokazują, jak ustawiać Version Name na Android i iOS. Dla Androida używany jest Gradle, dla iOS — Xcode Build Settings z agvtool.

Konfiguracja versionName w Android

W Android wersja ustawiana jest w pliku app/build.gradle wewnątrz bloku defaultConfig. Parametr versionName przyjmuje wartość ciągu znaków.

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

versionName może być również odczytywany z zewnętrznego pliku lub generowany dynamicznie za pomocą Gradle Script.

Dynamiczna generacja versionName

Wersja dynamiczna jest tworzona ze zmiennych środowiskowych systemu CI/CD. Gwarantuje to, że każda kompilacja otrzymuje poprawny numer wersji.

def getVersionName = {
    return System.getenv("VERSION_NAME") ?:
            "2.1.0"
}

android {
    defaultConfig {
        versionName getVersionName()
    }
}

Takie podejście automatyzuje wersjonowanie i eliminuje ryzyko niezgodności między kompilacją a tagiem w repozytorium.

Konfiguracja CFBundleShortVersionString w iOS

W iOS wersję można ustawić przez Xcode lub za pomocą wiersza poleceń przez agvtool.

# Ustawienie wersji marketingowej
xcrun agvtool new-marketing-version 2.1.0

# Odczyt bieżącej wersji
xcrun agvtool what-marketing-version

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