# Android

The Google Play Store is the most widely-used Android app store. This guide focuses on how to distribute a BeeWare app on the Google Play Store.

/// note | Note

The Google Play Store makes frequent changes to the workflows and nomenclature associated with publishing apps. As a result, it's very difficult to keep a guide like this one up to date. If you spot any problems, [let us know](https://github.com/beeware/briefcase/issues/new?assignees=&labels=bug,documentation,android&projects=&template=bug_report.yml).

///

## Build the app in release mode

To build the app, you must start from the directory containing the <span class="title-ref">pyproject.toml</span> file. Use Briefcase to build a release bundle for your application:

/// tab | macOS

```console
(venv) $ briefcase package android
[hello-world] Building Android App Bundle and APK in release mode...
...
[hello-world] Packaged dist/Hello World-1.0.0.aab
```

///

/// tab | Linux

```console
(venv) $ briefcase package android
[hello-world] Building Android App Bundle and APK in release mode...
...
[hello-world] Packaged dist/Hello World-1.0.0.aab
```

///

/// tab | Windows

```doscon
(venv) C:\...>briefcase package android
[hello-world] Building Android App Bundle and APK in release mode...
...
[hello-world] Packaged dist\Hello World-1.0.0.aab
```

///

This will result in an Android App Bundle file being generated. An [Android App Bundle](https://developer.android.com/guide/app-bundle) is a publishing format that includes all your app’s compiled code and resources.

/// admonition | AAB and APK

APK (Android Package) files can be directly installed on a device. AAB is a newer format that simplifies the process of uploading your app to the Play Store, allows Google to manage the signing process, and allows the APK that is installed on your end-user's device to be smaller.

///

## Sign the Android App Bundle

/// note | Note

Before you sign the APK files, you need to [create a code signing identity][code-signing-android].

///

The Google Play Store requires that the Android App Bundle is signed before it is uploaded, using the Java jarsigner tool.

In this example below, we assume your code signing identity is stored in **upload-key-helloworld.jks** under `.android` within your home folder. We also assume that the app's formal name is Hello World. You will need to change the path to the AAB file based on your app's formal name.

/// tab | macOS

```console
$ ~/Library/Caches/org.beeware.briefcase/tools/java17/Contents/Home/bin/jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore ~/.android/upload-key-helloworld.jks "dist/Hello World-1.0.0.aab" upload-key -storepass android
   adding: META-INF/MANIFEST.MF
   adding: META-INF/UPLOAD-K.SF
   adding: META-INF/UPLOAD-K.RSA
  signing: BundleConfig.pb
  signing: BUNDLE-METADATA/com.android.tools.build.libraries/dependencies.pb
  signing: base/assets/python/app/README
...
  signing: base/manifest/AndroidManifest.xml
  signing: base/assets.pb
  signing: base/native.pb
  signing: base/resources.pb
>>> Signer
  X.509, CN=Upload Key
  [trusted certificate]

jar signed.

Warning:
The signer's certificate is self-signed.
```

///

/// tab | Linux

```console
$ ~/.cache/briefcase/tools/java17/bin/jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore ~/.android/upload-key-helloworld.jks "dist/Hello World-1.0.0.aab" upload-key -storepass android
   adding: META-INF/MANIFEST.MF
   adding: META-INF/UPLOAD-K.SF
   adding: META-INF/UPLOAD-K.RSA
  signing: BundleConfig.pb
  signing: BUNDLE-METADATA/com.android.tools.build.libraries/dependencies.pb
  signing: base/assets/python/app/README
...
  signing: base/manifest/AndroidManifest.xml
  signing: base/assets.pb
  signing: base/native.pb
  signing: base/resources.pb
>>> Signer
  X.509, CN=Upload Key
  [trusted certificate]

jar signed.

Warning:
The signer's certificate is self-signed.
```

///

/// tab | Windows (cmd)

```doscon
C:\...>%LOCALAPPDATA%\BeeWare\briefcase\Cache\tools\java\bin\jarsigner.exe -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore %HOMEPATH%\.android\upload-key-helloworld.jks "dist\Hello World-1.0.0.aab" upload-key -storepass android
   adding: META-INF/MANIFEST.MF
   adding: META-INF/UPLOAD-K.SF
   adding: META-INF/UPLOAD-K.RSA
  signing: BundleConfig.pb
  signing: BUNDLE-METADATA/com.android.tools.build.libraries/dependencies.pb
  signing: base/assets/python/app/README
...
  signing: base/manifest/AndroidManifest.xml
  signing: base/assets.pb
  signing: base/native.pb
  signing: base/resources.pb
>>> Signer
  X.509, CN=Upload Key
  [trusted certificate]

jar signed.

Warning:
The signer's certificate is self-signed.
```

///

/// tab | Windows (PowerShell)

```pwsh-session
PS C:\...> & "$env:LOCALAPPDATA\BeeWare\briefcase\Cache\tools\java\bin\jarsigner.exe" -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore "$env:HOMEPATH\.android\upload-key-helloworld.jks" "android\gradle\Hello World\app\build\outputs\bundle\release\app-release.aab" upload-key -storepass android
   adding: META-INF/MANIFEST.MF
   adding: META-INF/UPLOAD-K.SF
   adding: META-INF/UPLOAD-K.RSA
  signing: BundleConfig.pb
  signing: BUNDLE-METADATA/com.android.tools.build.libraries/dependencies.pb
  signing: base/assets/python/app/README
...
  signing: base/manifest/AndroidManifest.xml
  signing: base/assets.pb
  signing: base/native.pb
  signing: base/resources.pb
>>> Signer
  X.509, CN=Upload Key
  [trusted certificate]

jar signed.

Warning:
The signer's certificate is self-signed.
```

///

You can safely ignore the warning about the signer's certificate being self-signed. Google will manage the process of signing the app with a verified certificate when you upload your app for distribution.

## Add the app to the Google Play store

To publish to the Google Play Store, you will need a Google Play Developer account, which costs 25 USD. You will then need to provide information for your app's store listing including an icon and screenshots, upload the app to Google, and finally roll the app out to production.

### Register for a Google Play Developer account

Registering for a Google Play Developer account requires a Google Account. You will need to pay registration fee and accept an agreement in the process.

To check if you already have a Google Play Developer account, you can visit the [Google Play console.](https://play.google.com/console/about/) If you see a button to **Publish an Android App on Google Play** or a button to **Create Application**, you can skip this step.

To create your Google Play developer account, pay the fee, and review the agreements, [follow Google's documentation.](https://support.google.com/googleplay/android-developer/answer/6112435?hl=en)

### Create a listing

Visit the [Google Play console.](https://play.google.com/console/about/) and log in. You will see a button labeled **Create App**; click this button.

Fill out the details for your app. We suggest using your app's formal name (as defined in `pyproject.toml` as the App name; the other details relate to the listing and legal compliance. At the bottom of of the page, press **Create App**.

This will take you to **Store Listing** section of your app. You will need to provide a short app description (up to 80 characters) and a full description (up to 4000 characters). Your app metadata may be helpful here.

You will also need to provide a collection of assets that will be used to promote your application:

> - **A 512x512px icon.** This will be the icon that appears in the Play
>   Store. It should match the icon you set on the application itself.
>
> - **At least 2 screen screenshots of the app.** Google recommends
>   using a screenshot [without
>   framing.](https://developer.android.com/distribute/marketing-tools/device-art-generator)
>   One way to capture such a screenshot is with the Android emulator's
>   screenshot functionality (the camera icon on the simulator
>   controls). This allows your screenshot to contain just what appears
>   on the screen rather than a picture of the virtual device. This will
>   store a file in your Desktop folder.
>
>   Screenshots must be at least 320px on their smallest dimension, no
>   larger than 3480px on their largest dimension, and can't have an
>   aspect ratio more extreme than 2:1. A screenshot from the Android
>   emulator typically fulfills these requirements.
>
> - **A 1024x500px feature graphic.** A feature graphic visually
>   represents the purpose of the app or your logo and can optionally
>   include a screenshot of the app in use, typically including device
>   framing.

Google Play supports optional graphic assets including promo videos, TV banners, and 360 degree stereoscopic images. See also [Google's advice on graphic assets.](https://support.google.com/googleplay/android-developer/answer/9866151)

Once you've completed the store listing, you'll need to fill out a range of other details about your app, including the category where it should appear in the Play Store, pricing details, details about the app's content and its suitability for children, and contact details for you as a developer. The navigation pane (typically on the left side of the screen) contains grayed out check marks covering all the sections with required details. Visit each of these sections in turn; when you have met the requirements of each section, the check mark will turn green. Once all the checkmarks are green, you're ready to release your app.

### Create a release

In the left navigation bar, select **Production** (in the "Release" grouping), Then select **Create Release.** If prompted to enable App Signing by Google Play, click **Continue**.

/// admonition | Non-production releases

The Play Store also supports releasing your app for internal, alpha and beta testing. Google's documentation [contains more details about creating test releases](https://support.google.com/googleplay/android-developer/answer/9845334).


///

In an earlier section of this tutorial, we used `briefcase publish` and `jarsigner` to create a signed Android App Bundle file. It is stored in the `dist` folder of your project. Upload this file to the Google Play console in the **App Bundles** section, fill out the **Release notes** section of the app, and click **Next**.

Google will then check that you've filled out all the necessary compliance details for your app; if there are any missing, you'll be prompted to complete those details.

Once you've completed those details, select **Publishing Overview** from the navigation sidebar. You should see "Changes ready to send for review", and a button marked **Send for review**. Click this button.

The Google Play Store will now review your app. You will be emailed if any updates are required; otherwise, after a day or two, your app will be rolled out to the Play Store.

## Publish an update

At some point, you'll want to publish an updated version of your application. Generate a fresh AAB file, signed with the *same* certificate as your original release. Then log into the Play Store console, and select your application. Select **Release Management** in the navigation bar, then **App Releases**.

At this point, the release process is the same as it was for your initial release; create a release, upload your AAB file, and submit the application for roll-out.
