Preparing Your Android App for Release: A Step-by-Step Guide

Introduction / Why This Is Needed

Release preparation is a critical stage before publishing an Android application to Google Play. It ensures your build is signed, optimized, and compliant with store requirements. After completing this guide, you will have an APK or AAB file ready for upload that correctly displays the version and can be installed on user devices.

Prerequisites / Preparation

Before you begin, ensure you have the following installed:

Android Studio (version Flamingo | 2022.2.1 or newer) with Android SDK (API level 33+).
Gradle (version 7.4+), integrated into your project.
Java Development Kit (JDK) 11 or higher to use keytool.
A completed Android project you wish to release.
Access to a computer with administrator privileges (for some keystore operations).

If you already have a keystore for signing, prepare its location, alias, and passwords. If you do not have a keystore, you will create one in one of the steps.

Step 1: Configure versionCode and versionName

Every public version of your app on Google Play must have unique versionCode (an integer) and a user-friendly versionName (a string). These parameters are set in the build.gradle file of the app module.

Open the app/build.gradle file (or build.gradle.kts for Kotlin DSL).
Locate the defaultConfig block inside android.
Update the values:
- versionCode: increment by 1 relative to the previous publication (e.g., from 1 to 2).
- versionName: set a readable version, such as "1.0.1" or "2.0 beta".

Example for Groovy DSL:

android {
    defaultConfig {
        applicationId "com.example.myapp"
        minSdkVersion 21
        targetSdkVersion 33
        versionCode 2
        versionName "1.0.1"
    }
}

For Kotlin DSL:

android {
    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 21
        targetSdk = 33
        versionCode = 2
        versionName = "1.0.1"
    }
}

⚠️ Important: versionCode must be an integer and strictly increase. Google Play will not accept a build with the same or lower versionCode than the current version.

Step 2: Create or Use an Existing Keystore

A keystore is a file containing the cryptographic key used to sign your APK/AAB. Without it, you cannot update your app on Google Play. If you already have a keystore, skip to Step 3.

Open a terminal (in Android Studio or a separate window).
Run the keytool command (included with JDK). Example to create a keystore valid for 25 years:
```
keytool -genkeypair -v -keystore my-release-key.jks -alias my-key-alias -keyalg RSA -keysize 2048 -validity 9125
```
- -keystore my-release-key.jks — the keystore file name (can be .keystore or .jks).
- -alias my-key-alias — the key alias (remember this).
- -validity 9125 — validity period in days (25 years ≈ 9125 days).
Follow the prompts: enter the keystore password, owner information (name, organization, country, etc.), and confirm passwords.

💡 Tip: Store your keystore in a secure location (not in your project, not in an unencrypted cloud). Create a backup. Losing the keystore means you cannot update your app.

Step 3: Configure Release Build Signing

In the build.gradle file of the app module, add a signing configuration for the release build.

In the same build.gradle file, inside the android block, add signingConfigs:

android {
    signingConfigs {
        release {
            storeFile file('path/to/my-release-key.jks')
            storePassword 'your_keystore_password'
            keyAlias 'my-key-alias'
            keyPassword 'your_key_password'
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
            minifyEnabled true  // optional: enable ProGuard/R8
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
}

Replace 'path/to/my-release-key.jks', 'your_keystore_password', 'my-key-alias', and 'your_key_password' with your actual values.

For security, do not store passwords in plain text. Use environment variables or gradle.properties:

In gradle.properties (in the project root or ~/.gradle/):

MY_KEYSTORE_PASSWORD=your_keystore_password
MY_KEY_PASSWORD=your_key_password

In build.gradle:

storePassword System.getenv("MY_KEYSTORE_PASSWORD")
keyPassword System.getenv("MY_KEY_PASSWORD")

⚠️ Important: Ensure your release build uses signingConfigs.release. If you omit this, the build will be unsigned and will not be accepted by Google Play.

Step 4: Build the Release APK or AAB

You can generate a signed build via Android Studio or the command line.

Method A: Through Android Studio (recommended for beginners)

From the menu, select Build → Generate Signed Bundle / APK.
In the wizard:
- Choose Android App Bundle (AAB) or APK. Google requires AAB for new apps.
- Click Next.
- Select the module (usually app).
- In the Key store path section, specify the keystore path or create a new one.
- Enter passwords and alias.
- Select release in Build Variant.
- Click Finish.
The generated file will be in app/build/outputs/bundle/release/ (for AAB) or app/build/outputs/apk/release/ (for APK).

Method B: Through Gradle (for automation)

For AAB:
```
./gradlew bundleRelease
```
For APK:
```
./gradlew assembleRelease
```

Files will appear in the same directories as when building via Android Studio.

💡 Tip: If the build fails, check logs in Build → Build Output in Android Studio or in the terminal. Common errors: incorrect keystore password, missing keystore file.

Step 5: Verify and Optimize the Build

After building, ensure your APK (if chosen) is optimized using zipalign. AABs are automatically optimized by Google Play, but for APKs this is mandatory.

For APK: If you used assembleRelease, the APK might not be aligned. Run:
```
zipalign -v -p 4 app/build/outputs/apk/release/app-release-unsigned.apk app-release-aligned.apk
```
Then sign it if not already signed (but in Step 3 we configured signing, so app-release.apk should already be signed and aligned if zipAlignEnabled is enabled — it is by default for release). Verify:
```
zipalign -c -v 4 app/build/outputs/apk/release/app-release.apk
```
If the output is Verification successful, the APK is ready.

For AAB: Verify integrity:

jarsigner -verify -verbose -certs app/build/outputs/bundle/release/app-release.aab

It should output jar verified..

Testing: Install the build on a device or emulator:
```
adb install -r app/build/outputs/apk/release/app-release.apk
```
Or for AAB, use internal testing in Google Play Console (see related guide).

Verification Checklist

After completing all steps, ensure:

File exists: The APK or AAB is in the specified directory.
Signature is valid: Run jarsigner -verify -verbose -certs your_file.apk (for APK) or your_file.aab (for AAB). Your certificate details should be displayed.
Zipalign for APK: zipalign -c -v 4 your_file.apk returns Verification successful.
versionCode and versionName: Open AndroidManifest.xml in the compiled APK (using aapt dump badging your_file.apk) and check versionCode and versionName.
Installation: The app installs on a device without errors and launches.

Troubleshooting

Error: "Keystore was tampered with, or password was incorrect"

Cause: Incorrect keystore or alias password during build.
Solution: Check passwords in build.gradle or environment variables. Ensure you are using the correct alias.

Error: "Version code must be greater than previous"

Cause: versionCode was not incremented or matches the previous version on Google Play.
Solution: Increase versionCode in build.gradle (e.g., by 1) and rebuild.

Error: "Execution failed for task ':app:validateSigningRelease'. > Keystore file not found"

Cause: Incorrect keystore path specified in build.gradle.
Solution: Use an absolute path or file('relative/path'). Verify the file exists.

Issue: AAB or APK not optimized, large size

Cause: minifyEnabled or shrinkResources not enabled for the release build.

Solution: In build.gradle for release, add:

buildTypes {
    release {
        minifyEnabled true
        shrinkResources true
        proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
    }
}

Rebuild. The size will decrease, but test your app after obfuscation.

Issue: Installing release build fails with "App not installed"

Cause: Signature mismatch (e.g., trying to install over a debug build) or a corrupted APK.
Solution: Uninstall the debug version from the device. Verify zipalign and signature. Ensure minSdkVersion matches the device.

If the issue persists, check adb logcat during installation or refer to other guides on installation errors.

F.A.Q.

What are versionCode and versionName in Android?

How to create a keystore for APK signing?

What's the difference between APK and AAB for release?

How to test the release build before uploading?

Hints

Configure versionCode and versionName

Create or use an existing keystore

Configure release build signing

Build release APK or AAB

Verify and optimize the build