Wersja aplikacji

Obsługa wersji to kluczowy element strategii uaktualniania i utrzymywania aplikacji. Przechowywanie wersji jest ważne, ponieważ:

  • Użytkownicy muszą mieć konkretne informacje o wersji aplikacji zainstalowanej na ich urządzeniach oraz o wersjach licencji dostępnych do zainstalowania.
  • Inne aplikacje, w tym te, które publikujesz w ramach pakietu, muszą wysyłać do systemu zapytanie o wersję aplikacji, aby ustalić jej zgodność i określić zależności.
  • Usługi, w których publikujesz aplikację, mogą również wymagać sprawdzenia wersji aplikacji, aby wyświetlić ją użytkownikom. Usługa publikowania może też sprawdzać wersję aplikacji, aby określić zgodność i nawiązać relacje między przejściem na wyższą a niższą wersję.

System Android wykorzystuje informacje o wersji aplikacji, aby chronić Cię przed przejściem na niższą wersję. System nie używa informacji o wersji aplikacji do egzekwowania ograniczeń dotyczących uaktualnień czy zgodności aplikacji innych firm. Twoja aplikacja musi egzekwować wszelkie ograniczenia wersji i informować o nich użytkowników.

System Android wymusza zgodność wersji systemu, zgodnie z ustawieniem minSdk w plikach kompilacji. To ustawienie pozwala aplikacji określić minimalny interfejs API systemu, z którym jest zgodna. Więcej informacji o wymaganiach dotyczących interfejsu API znajdziesz w artykule Określanie wymagań dotyczących poziomu interfejsu API.

Wymagania dotyczące obsługi wersji różnią się w zależności od projektu. Wielu deweloperów uważa jednak semantyczną obsługę wersji jako dobrą podstawę strategii obsługi wersji.

Ustawianie informacji o wersji aplikacji

Aby określić informacje o wersji aplikacji, ustaw wartości dla ustawień wersji w plikach kompilacji Gradle:

Odlotowy

    android {
      namespace 'com.example.testapp'
      compileSdk 33

      defaultConfig {
          applicationId "com.example.testapp"
          minSdk 24
          targetSdk 33
          versionCode 1
          versionName "1.0"
          ...
      }
      ...
    }
    ...

Kotlin

    android {
      namespace = "com.example.testapp"
      compileSdk = 33

      defaultConfig {
          applicationId = "com.example.testapp"
          minSdk = 24
          targetSdk = 33
          versionCode = 1
          versionName = "1.0"
          ...
      }
      ...
    }
    ...

Ustawienia wersji

Określ wartości dla obu dostępnych ustawień wersji: versionCode i versionName.

versionCode
Dodatnia liczba całkowita używana jako wewnętrzny numer wersji. Ta liczba pomaga określić, czy poszczególne wersje są nowsze od innych. Wyższe liczby oznaczają nowsze wersje. To nie jest numer wersji wyświetlany użytkownikom. Ten numer jest określany w ustawieniu versionName. System Android używa wartości versionCode, by chronić użytkowników przed przejściem na niższą wersję, ponieważ uniemożliwia użytkownikom instalowanie pliku APK z wartością versionCode niższą niż ta zainstalowana na urządzeniu.

Wartość jest dodatnią liczbą całkowitą, aby inne aplikacje mogły ją automatycznie ocenić, na przykład aby sprawdzić relację przejścia na wyższą lub niższą wersję usługi. Możesz ustawić dowolną dodatnią liczbę całkowitą. Zadbaj jednak o to, by każda kolejna wersja aplikacji miała wyższą wartość.

Uwaga: największa wartość versionCode w Google Play to 2 100 000 000.

Nie możesz przesłać do Sklepu Play pliku APK za pomocą kodu versionCode użytego już w poprzedniej wersji.

Uwaga: w niektórych sytuacjach możesz przesłać wersję aplikacji, która ma parametr versionCode niższy niż najnowsza wersja. Jeśli na przykład publikujesz wiele plików APK, możesz mieć gotowe zakresy versionCode dla poszczególnych plików APK. Więcej informacji o przypisywaniu wartości versionCode do wielu plików APK znajdziesz w sekcji Przypisywanie kodów wersji.

Zazwyczaj publikujesz pierwszą wersję aplikacji z wartością versionCode ustawioną na 1, a następnie monotonicznie zwiększasz tę wartość z każdą wersją aplikacji niezależnie od tego, czy jest ona wersją główną czy podrzędną. Oznacza to, że wartość versionCode nie musi być podobna do wersji aplikacji, którą widzi użytkownik. Aplikacje i usługi publikowania nie powinny wyświetlać użytkownikom tej wartości.

versionName

Ciąg znaków używany jako numer wersji wyświetlany użytkownikom. To ustawienie można określić jako ciąg nieprzetworzony lub jako odwołanie do zasobu tekstowego.

Wartość jest ciągiem znaków, dzięki czemu możesz opisać wersję aplikacji w postaci ciągu <główna>.<podrzędny>.<punkt> lub jako dowolny inny typ bezwzględnego bądź względnego identyfikatora wersji. versionName jest jedyną wartością wyświetlaną użytkownikom.

Zdefiniuj wartości wersji

Możesz zdefiniować wartości domyślne tych ustawień, umieszczając je w bloku defaultConfig {}, zagnieżdżonym w bloku android {} pliku build.gradle lub build.gradle.kts modułu. Następnie możesz zastąpić te wartości domyślne dla różnych wersji aplikacji, definiując osobne wartości dla poszczególnych typów kompilacji lub rodzajów usług. Poniższy plik zawiera ustawienia versionCode i versionName w bloku defaultConfig {} oraz blok productFlavors {}.

Wartości te są następnie łączone z plikiem manifestu aplikacji podczas kompilacji.

Odlotowy

    android {
        ...
        defaultConfig {
            ...
            versionCode 2
            versionName "1.1"
        }
        productFlavors {
            demo {
                ...
                versionName "1.1-demo"
            }
            full {
                ...
            }
        }
    }

Kotlin

    android {
        ...
        defaultConfig {
            ...
            versionCode = 2
            versionName = "1.1"
        }
        productFlavors {
            create("demo") {
                ...
                versionName = "1.1-demo"
            }
            create("full") {
                ...
            }
        }
    }

W bloku defaultConfig {} w tym przykładzie wartość versionCode wskazuje, że bieżący plik APK zawiera drugą wersję aplikacji, a ciąg versionName wskazuje, że użytkownikom będzie ona wyświetlana w wersji 1.1. Ten plik definiuje również 2 rodzaje produktu: „demo” i „full”. Typ produktu „demonstracyjny” definiuje versionName jako „1.1-demo”, dlatego kompilacja „demonstracyjna” używa tego versionName zamiast wartości domyślnej. „Pełny” blok smaku produktu nie definiuje elementu versionName, dlatego używana jest wartość domyślna „1.1”.

Uwaga: jeśli aplikacja definiuje wersję aplikacji bezpośrednio w elemencie <manifest>, wartości wersji w pliku kompilacji Gradle zastępują ustawienia w pliku manifestu. Poza tym zdefiniowanie tych ustawień w plikach kompilacji Gradle umożliwia określenie różnych wartości dla różnych wersji aplikacji. Aby zapewnić większą elastyczność i uniknąć potencjalnego zastąpienia podczas scalania pliku manifestu, usuń te atrybuty z elementu <manifest> i określ ustawienia wersji w plikach kompilacji Gradle.

Platforma Android udostępnia interfejs API, który umożliwia wysyłanie do systemu zapytań o informacje o wersji aplikacji. Aby uzyskać informacje o wersji, użyj metody PackageManager.getPackageInfo(java.lang.String, int).

Określ wymagania dotyczące poziomu interfejsu API

Jeśli Twoja aplikacja wymaga określonej minimalnej wersji platformy Androida, możesz określić ten wymóg w ustawieniach na poziomie interfejsu API w pliku build.gradle lub build.gradle.kts aplikacji. Podczas kompilacji ustawienia te są scalane z plikiem manifestu aplikacji. Określenie wymagań dotyczących poziomu interfejsu API sprawi, że Twoją aplikację będzie można instalować tylko na urządzeniach z zgodną wersją platformy Androida.

Uwaga: jeśli wymagania dotyczące poziomu interfejsu API określisz bezpośrednio w pliku manifestu aplikacji, ustawienia w pliku manifestu zastąpią odpowiednie ustawienia w plikach kompilacji. Poza tym zdefiniowanie tych ustawień w plikach kompilacji Gradle umożliwia określenie różnych wartości dla różnych wersji aplikacji. Aby zapewnić większą elastyczność i uniknąć potencjalnego zastąpienia podczas scalania pliku manifestu, usuń te atrybuty z elementu <uses-sdk> i określ ustawienia poziomu interfejsu API w plikach kompilacji Gradle.

Dostępne są 2 ustawienia na poziomie interfejsu API:

  • minSdk – minimalna wersja platformy Androida, na której będzie działać aplikacja, określona za pomocą identyfikatora poziomu interfejsu API platformy.
  • targetSdk – poziom interfejsu API, na którym ma działać aplikacja. W niektórych przypadkach pozwala to aplikacji korzystać z elementów manifestu lub zachowań zdefiniowanych na docelowym poziomie interfejsu API, zamiast ograniczać się tylko do tych zdefiniowanych na minimalnym poziomie interfejsu API.

Aby określić domyślne wymagania dotyczące poziomu interfejsu API w pliku build.gradle lub build.gradle.kts, dodaj co najmniej 1 ustawienie na poziomie interfejsu API do bloku defaultConfig{} umieszczonego w bloku android {}. Możesz też zastąpić te wartości domyślne w przypadku różnych wersji aplikacji, dodając ustawienia do typów kompilacji lub rodzajów usług.

Ten plik określa domyślne ustawienia minSdk i targetSdk w bloku defaultConfig {} oraz zastępuje minSdk w przypadku jednego rodzaju produktu:

Odlotowy

android {
    ...
    defaultConfig {
        ...
        minSdk 21
        targetSdk 33
    }
    productFlavors {
        main {
            ...
        }
        afterNougat {
            ...
            minSdk 24
        }
    }
}

Kotlin

android {
    ...
    defaultConfig {
        ...
        minSdk = 21
        targetSdk = 33
    }
    productFlavors {
        create("main") {
            ...
        }
        create("afterNougat") {
            ...
            minSdk = 24
        }
    }
}

Przygotowując się do zainstalowania aplikacji, system sprawdza wartości tych ustawień i porównuje je z wersją systemu. Jeśli wartość minSdk jest większa niż wersja systemu, system uniemożliwia instalację aplikacji.

Jeśli nie określisz tych ustawień, system przyjmie, że aplikacja jest zgodna ze wszystkimi wersjami platformy. Jest to odpowiednik ustawienia minSdk na 1.

Więcej informacji znajdziesz w artykule Co to jest poziom interfejsu API?. Informacje o ustawieniach kompilacji Gradle znajdziesz w artykule o konfigurowaniu wariantów kompilacji.