App versionieren

Die Versionsverwaltung ist ein wichtiger Bestandteil Ihrer Upgrade- und Wartungsstrategie für Apps. Die Versionsverwaltung ist aus folgenden Gründen wichtig:

• Nutzer müssen genaue Informationen über die App-Version haben, die auf ihren Geräten installiert ist, sowie die Upgrade-Versionen, die für die Installation verfügbar sind.
• Andere Anwendungen – auch andere, die Sie als Suite veröffentlichen – müssen das System nach der Version Ihrer Anwendung abfragen, um die Kompatibilität zu ermitteln und Abhängigkeiten zu identifizieren.
• Dienste, für die Sie Ihre Apps veröffentlichen, müssen möglicherweise auch die App-Version abfragen, damit sie Nutzern die Version anzeigen können. Ein Publisher-Dienst muss möglicherweise auch die Anwendungsversion prüfen, um die Kompatibilität zu ermitteln und Upgrade-/Downgrade-Beziehungen herzustellen.

Das Android-System schützt die Versionsinformationen Ihrer App vor Downgrades. Das System verwendet keine Informationen zur App-Version, um Einschränkungen für Upgrades oder die Kompatibilität von Drittanbieter-Apps zu erzwingen. Ihre App muss alle Versionseinschränkungen erzwingen und die Nutzer darüber informieren.

Das Android-System erzwingt die Kompatibilität der Systemversion, wie in der Einstellung minSdk in den Build-Dateien angegeben. Mit dieser Einstellung kann eine App die Mindestsystem-API angeben, mit der sie kompatibel ist. Weitere Informationen zu API-Anforderungen finden Sie unter Anforderungen an das API-Level angeben.

Die Versionsanforderungen unterscheiden sich je nach Projekt. Viele Entwickler ziehen jedoch die semantische Versionsverwaltung als gute Grundlage für eine Versionsverwaltungsstrategie in Betracht.

Informationen zur App-Version festlegen

Um die Versionsinformationen für Ihre App zu definieren, legen Sie Werte für die Versionseinstellungen in den Gradle-Build-Dateien fest:

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

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

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

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

Versionseinstellungen

Definieren Sie Werte für beide verfügbaren Versionseinstellungen: versionCode und versionName.

versionCode

Eine positive Ganzzahl, die als interne Versionsnummer verwendet wird. Anhand dieser Zahl lässt sich feststellen, ob eine Version aktueller ist als eine andere. Höhere Zahlen deuten auf neuere Versionen hin. Dies ist nicht die Versionsnummer, die Nutzern angezeigt wird. Sie wird in der Einstellung versionName festgelegt. Das Android-System verwendet den Wert versionCode, um Nutzer vor Downgrades zu schützen. Dabei hindert das Android-System Nutzer daran, ein APK mit einer niedrigeren versionCode als die aktuell auf ihrem Gerät installierte Version zu installieren.

Der Wert ist eine positive Ganzzahl, damit andere Apps ihn programmatisch auswerten können, beispielsweise um eine Upgrade- oder Downgrade-Beziehung zu prüfen. Sie können eine beliebige positive Ganzzahl als Wert angeben. Achte aber darauf, dass jeder Release deiner App einen höheren Wert einbringt.

Hinweis:Der größte Wert, den Google Play für versionCode zulässt, ist 21.000.000.000.

Du kannst kein APK mit einem versionCode, das du bereits für eine frühere Version verwendet hast, in den Play Store hochladen.

Hinweis: Es kann vorkommen, dass Sie eine Version Ihrer Anwendung mit einer niedrigeren versionCode als die neueste Version hochladen möchten. Wenn Sie beispielsweise mehrere APKs veröffentlichen, haben Sie möglicherweise für bestimmte APKs vordefinierte versionCode-Bereiche. Weitere Informationen zum Zuweisen von versionCode-Werten für mehrere APKs findest du unter Versionscodes zuweisen.

Normalerweise veröffentlichen Sie die erste Version Ihrer App mit versionCode auf 1 und erhöhen dann den Wert mit jedem Release monoton, unabhängig davon, ob es sich um einen Haupt- oder Nebenrelease handelt. Das bedeutet, dass der Wert versionCode nicht unbedingt der für den Nutzer sichtbaren App-Release-Version entspricht. Dieser Versionswert sollte Nutzern in Apps und Veröffentlichungsdiensten nicht angezeigt werden.

versionName

Ein String, der als Versionsnummer verwendet wird, die Nutzern angezeigt wird. Diese Einstellung kann als Rohstring oder als Verweis auf eine Stringressource angegeben werden.

Der Wert ist ein String, sodass Sie die App-Version als String des Typs <major>.<minor>.<point> oder als eine andere Art von absoluter oder relativer Versionskennung beschreiben können. versionName ist der einzige Wert, der Nutzern angezeigt wird.

Versionswerte definieren

Sie können Standardwerte für diese Einstellungen definieren, indem Sie sie in den Block defaultConfig {} aufnehmen, der im Block android {} der Datei build.gradle oder build.gradle.kts Ihres Moduls verschachtelt ist. Sie können diese Standardwerte dann für verschiedene Versionen Ihrer Anwendung überschreiben, indem Sie separate Werte für einzelne Build-Typen oder Produktvarianten definieren. Die folgende Datei zeigt die Einstellungen für versionCode und versionName im defaultConfig {}-Block sowie im productFlavors {}-Block.

Diese Werte werden dann während des Build-Prozesses in der Manifestdatei Ihrer App zusammengeführt.

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

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

Im defaultConfig {}-Block dieses Beispiels gibt der Wert versionCode an, dass das aktuelle APK den zweiten Release der App enthält. Der String versionName gibt an, dass es Nutzern als Version 1.1 angezeigt wird. In dieser Datei sind außerdem zwei Produktvarianten definiert: „demo“ und „full“. Da die Produktsorte „demo“ die versionName als „1.1-demo“ definiert, verwendet der Build „demo“ diese versionName anstelle des Standardwerts. Der Flavor-Block „full“ definiert versionName nicht und verwendet daher den Standardwert „1.1“.

Hinweis:Wenn deine App die App-Version direkt im Element <manifest> definiert, überschreiben die Versionswerte in der Gradle-Build-Datei die Einstellungen im Manifest. Wenn du diese Einstellungen in den Gradle-Build-Dateien definierst, kannst du außerdem unterschiedliche Werte für verschiedene Versionen deiner App angeben. Für mehr Flexibilität und ein mögliches Überschreiben beim Zusammenführen des Manifests solltest du diese Attribute aus dem <manifest>-Element entfernen und stattdessen deine Versionseinstellungen in den Gradle-Build-Dateien festlegen.

Das Android-Framework stellt eine API bereit, mit der Sie das System nach Versionsinformationen zu Ihrer App abfragen können. Verwenden Sie die Methode PackageManager.getPackageInfo(java.lang.String, int), um Versionsinformationen abzurufen.

Anforderungen an API-Level festlegen

Wenn für deine App eine bestimmte Mindestversion der Android-Plattform erforderlich ist, kannst du diese Versionsanforderung als API-Level-Einstellungen in der Datei build.gradle oder build.gradle.kts der App festlegen. Während des Build-Prozesses werden diese Einstellungen in der Manifestdatei Ihrer App zusammengeführt. Durch Angabe von Anforderungen auf API-Level kannst du dafür sorgen, dass deine App nur auf Geräten installiert werden kann, auf denen eine kompatible Version der Android-Plattform ausgeführt wird.

Hinweis: Wenn du Anforderungen auf API-Level direkt in der Manifestdatei deiner App festlegst, überschreiben die entsprechenden Einstellungen in den Build-Dateien die Einstellungen in der Manifestdatei. Wenn du diese Einstellungen in den Gradle-Build-Dateien definierst, kannst du außerdem unterschiedliche Werte für verschiedene Versionen deiner App angeben. Für mehr Flexibilität und ein mögliches Überschreiben beim Zusammenführen des Manifests kannst du diese Attribute aus dem <uses-sdk>-Element entfernen und stattdessen die Einstellungen auf API-Ebene in den Gradle-Build-Dateien festlegen.

Es sind zwei Einstellungen auf API-Ebene verfügbar:

• minSdk: Die Mindestversion der Android-Plattform, auf der die App ausgeführt wird, angegeben durch die API-Level-ID der Plattform.
• targetSdk: Die API-Ebene, auf der die App ausgeführt werden soll. In einigen Fällen ermöglicht dies der App, Manifestelemente oder Verhaltensweisen zu verwenden, die auf der Ziel-API-Ebene definiert sind, anstatt nur die Elemente zu verwenden, die für das Mindest-API-Level definiert sind.

Wenn Sie die Standardanforderungen für das API-Level in einer build.gradle- oder build.gradle.kts-Datei festlegen möchten, fügen Sie eine oder mehrere API-Level-Einstellungen in den defaultConfig{}-Block ein, der im android {}-Block verschachtelt ist. Sie können diese Standardwerte auch für verschiedene Versionen Ihrer App überschreiben, indem Sie die Einstellungen für Build-Typen oder Produktvarianten hinzufügen.

In der folgenden Datei werden die Standardeinstellungen minSdk und targetSdk im defaultConfig {}-Block angegeben und minSdk für eine Produktvariante überschrieben:

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

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

Bei der Vorbereitung der Installation deiner App prüft das System den Wert dieser Einstellungen und vergleicht sie mit der Systemversion. Wenn der Wert für minSdk größer als die Systemversion ist, verhindert das System die Installation der Anwendung.

Wenn Sie diese Einstellungen nicht angeben, geht das System davon aus, dass Ihre App mit allen Plattformversionen kompatibel ist. Dies entspricht der Festlegung von minSdk auf 1.

Weitere Informationen finden Sie unter Was ist das API-Level?. Informationen zu den Build-Einstellungen für Gradle finden Sie unter Build-Varianten konfigurieren.