App versionieren

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

  • Nutzer benötigen bestimmte Informationen zur App-Version, die auf ihren Geräten installiert ist, und zu den Upgrade-Versionen, die für die Installation verfügbar sind.
  • Andere Apps, einschließlich anderer Apps, die Sie als Suite veröffentlichen, müssen das System nach der Version Ihrer App abfragen, um die Kompatibilität zu ermitteln und Abhängigkeiten zu identifizieren.
  • Dienste, in denen Sie Ihre App(s) veröffentlichen, müssen möglicherweise auch die Version Ihrer App abfragen, damit sie sie Nutzern anzeigen können. Ein Veröffentlichungsdienst muss möglicherweise auch die App-Version prüfen, um die Kompatibilität zu ermitteln und Upgrade-/Downgrade-Beziehungen herzustellen.

Das Android-System prüft die Versionsinformationen Ihrer App, um Downgrades zu verhindern. 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 Versionsbeschränkungen durchsetzen und Nutzer darüber informieren.

Das Android-System erzwingt die Kompatibilität mit der Systemversion, die durch die minSdk-Einstellung in den Build-Dateien angegeben wird. 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 (SDK-Version) angeben.

Die Anforderungen an die Versionsverwaltung variieren je nach Projekt. Viele Entwickler halten Semantic Versioning jedoch für eine gute Grundlage für eine Versionsstrategie.

App-Versionsinformationen festlegen

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

Groovy

    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"
          ...
      }
      ...
    }
    ...

Versionseinstellungen

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

versionCode
Eine positive Ganzzahl, die als interne Versionsnummer verwendet wird. Anhand dieser Nummer lässt sich feststellen, ob eine Version neuer als eine andere ist. Höhere Zahlen weisen auf neuere Versionen hin. Das ist nicht die Versionsnummer, die Nutzern angezeigt wird. Diese wird durch die Einstellung versionName festgelegt. Das Android-System verwendet den Wert versionCode, um Downgrades zu verhindern. Nutzer können also kein APK mit einem niedrigeren versionCode als die derzeit auf ihrem Gerät installierte Version installieren.

Der Wert ist eine positive Ganzzahl, damit andere Apps ihn programmatisch auswerten können, z. B. um eine Upgrade- oder Downgrade-Beziehung zu prüfen. Sie können den Wert auf eine beliebige positive Ganzzahl festlegen. Achten Sie jedoch darauf, dass bei jedem nachfolgenden Release Ihrer App ein höherer Wert verwendet wird.

Hinweis:Der größte Wert, der für versionCode bei Google Play zulässig ist, ist 2100000000.

Sie können kein APK mit einem versionCode in den Play Store hochladen, das Sie bereits für eine frühere Version verwendet haben.

Hinweis:In einigen Fällen kann es sinnvoll sein, eine Version Ihrer App mit einer niedrigeren versionCode als die aktuelle Version hochzuladen. Wenn Sie beispielsweise mehrere APKs veröffentlichen, haben Sie möglicherweise versionCode-Bereiche für bestimmte APKs voreingestellt. Weitere Informationen zum Zuweisen von versionCode-Werten für mehrere APKs finden Sie unter Versionscodes zuweisen.

Normalerweise veröffentlichen Sie die erste Version Ihrer App mit versionCode auf 1 gesetzt und erhöhen den Wert dann mit jeder Version monoton, unabhängig davon, ob es sich um eine Haupt- oder Nebenversion handelt. Das bedeutet, dass der versionCode-Wert nicht unbedingt der für den Nutzer sichtbaren App-Release-Version entspricht. Apps und Veröffentlichungsdienste dürfen diesen Versionswert Nutzern nicht anzeigen.

versionName

Ein String, der als Versionsnummer für Nutzer 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 im Format <major>.<minor>.<point> oder als beliebige andere Art von absoluter oder relativer Versions-ID beschreiben können. Der 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 defaultConfig {}-Block einfügen, der im android {}-Block der build.gradle- oder build.gradle.kts-Datei Ihres Moduls verschachtelt ist. Sie können diese Standardwerte dann für verschiedene Versionen Ihrer App überschreiben, indem Sie separate Werte für einzelne Build-Typen oder Produktvarianten definieren. Die folgende Datei zeigt die Einstellungen versionCode und versionName im Block defaultConfig {} sowie den Block productFlavors {}.

Diese Werte werden dann während des Build-Prozesses in die Manifestdatei Ihrer App eingefügt.

Groovy

    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") {
                ...
            }
        }
    }

Im defaultConfig {}-Block dieses Beispiels gibt der Wert versionCode an, dass das aktuelle APK den zweiten Release der App enthält, und der String versionName gibt an, dass er Nutzern als Version 1.1 angezeigt wird. In dieser Datei werden auch zwei Produktvarianten definiert: „demo“ und „full“. Da für die Produktvariante „demo“ versionName als „1.1-demo“ definiert ist, wird für den „demo“-Build dieser versionName-Wert anstelle des Standardwerts verwendet. Im Block für die Produktvariante „full“ wird versionName nicht definiert. Daher wird der Standardwert „1.1“ verwendet.

Hinweis:Wenn die App-Version direkt im <manifest>-Element definiert ist, überschreiben die Versionswerte in der Gradle-Build-Datei die Einstellungen im Manifest. Wenn Sie diese Einstellungen in den Gradle-Build-Dateien definieren, können Sie außerdem unterschiedliche Werte für verschiedene Versionen Ihrer App angeben. Um mehr Flexibilität zu erhalten und ein potenzielles Überschreiben beim Zusammenführen des Manifests zu vermeiden, sollten Sie diese Attribute aus dem <manifest>-Element entfernen und Ihre Versionseinstellungen stattdessen in den Gradle-Build-Dateien definieren.

Das Android-Framework bietet eine API, 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.

API-Level-Anforderungen (SDK-Version) angeben

Wenn Ihre App eine bestimmte Mindestversion der Android-Plattform erfordert, können Sie diese Version als API-Level-Einstellung in der Datei build.gradle oder build.gradle.kts der App angeben. Beim Erstellen werden diese Einstellungen in das Manifest Ihrer App eingefügt. Durch die Angabe von API-Level-Anforderungen wird sichergestellt, dass Ihre App nur auf Geräten installiert werden kann, auf denen eine kompatible Version der Android-Plattform ausgeführt wird.

Hinweis:Wenn Sie API-Level-Anforderungen direkt im Manifest Ihrer App angeben, werden die entsprechenden Einstellungen in den Build-Dateien die Einstellungen in der Manifestdatei überschreiben. Wenn Sie diese Einstellungen in den Gradle-Build-Dateien definieren, können Sie außerdem unterschiedliche Werte für verschiedene Versionen Ihrer App angeben. Um mehr Flexibilität zu erhalten und ein potenzielles Überschreiben beim Zusammenführen des Manifests zu vermeiden, sollten Sie diese Attribute aus dem <uses-sdk>-Element entfernen und Ihre API-Level-Einstellungen stattdessen in den Gradle-Build-Dateien definieren.

Es gibt zwei Einstellungen für die API-Ebene:

  • minSdk: Die Mindestversion der Android-Plattform, auf der die App ausgeführt wird, angegeben durch die API-Level-Kennung der Plattform.
  • targetSdk: Das API-Level, das mit der Konstanten <SDK_INT> verknüpft ist, für die die App entwickelt wurde. In einigen Fällen kann die App dadurch Manifestelemente oder Verhaltensweisen verwenden, die im Ziel-API-Level definiert sind, anstatt nur auf die Elemente oder Verhaltensweisen beschränkt zu sein, die für das Mindest-API-Level definiert sind.

    • Es ist nicht möglich, anzugeben, dass eine App entweder auf eine Nebenversion des SDK ausgerichtet ist oder diese erfordert. Wenn Sie neue APIs aufrufen möchten, die eine höhere Haupt- oder Nebenversion des SDK als Ihr minSdkVersion erfordern, können Sie einen Codeblock mit einem Check für eine Neben- oder Hauptversion mithilfe der Konstanten SDK_INT_FULL schützen.

    if (SDK_INT_FULL >= VERSION_CODES_FULL.[MAJOR or MINOR RELEASE]) {
  // Use APIs introduced in a major or minor SDK version
}

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

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

Groovy

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
        }
    }
}

Bei der Vorbereitung der Installation Ihrer App prüft das System den Wert dieser Einstellungen und vergleicht ihn mit der Systemversion. Wenn der Wert von minSdk größer als die Systemversion ist, verhindert das System die Installation der App.

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

Weitere Informationen finden Sie unter Was ist das API-Level?. Informationen zu Gradle-Buildeinstellungen finden Sie unter Build-Varianten konfigurieren.