Android Distribution

Setting up Android distribution requires a Google Play Developer account. The signing keystore is automatically generated by the platform.

Before starting, make sure you’ve completed the shared Prerequisites in App Configuration.

1. Create a Google Play Developer Account

If you haven’t already, register at play.google.com/console/signup. There is a one-time $25 registration fee.

2. Create Your App in Google Play Console

1. Go to play.google.com/console

2. Click Create app

3. Fill in the app name, default language, app type (App), and whether it’s free or paid

4. Accept the declarations and click Create app

3. Create a Google Cloud Service Account

A service account allows the build system to upload your app to Google Play automatically.

1. Go to console.cloud.google.com

2. Create a new project (or select an existing one)

3. Enable the Google Play Android Developer API:

   • Go to APIs & Services → Library
   • Search for “Google Play Android Developer API”
   • Click Enable

4. Create a service account:

   • Go to APIs & Services → Credentials
   • Click Create Credentials → Service Account
   • Enter a name (e.g., “Play Store Upload”) and click Create and Continue
   • Skip the optional role and user access steps
   • Click Done

5. Create a JSON key:

   • Click on the service account you just created
   • Go to the Keys tab
   • Click Add Key → Create new key
   • Select JSON and click Create
   • Save the downloaded GoogleCloudServiceKey.json file

   'Service account key creation is disabled' error

   Google Cloud organizations created after May 3, 2024 block service account key creation by default via the iam.disableServiceAccountKeyCreation organization policy. Follow these steps to disable it:

   Step 1 — Grant yourself the Organization Policy Administrator role:

   The project Owner role does not include organization policy permissions. You must grant yourself the Organization Policy Administrator role at the organization level (not the project level).

   1. Go to console.cloud.google.com
   2. Click the project picker in the top bar
   3. In the picker dialog, select the All tab
   4. Select your organization (the top-level entry, not a project underneath it)
   5. Go to IAM & Admin → IAM
   6. Click + Grant Access
   7. In the New principals field, enter your email address
   8. In the Select a role dropdown, search for Organization Policy Administrator and select it
   9. Click Save

   Step 2 — Disable both policies:

   Searching for “Disable service account key creation” returns two policies. You must disable both or key creation will still be blocked.

   1. In the project picker, switch back to your project (not the organization)
   2. Go to IAM & Admin → Organization Policies
   3. In the filter bar, search for “Disable service account key creation”
   4. Click the first policy (iam.disableServiceAccountKeyCreation)
   5. Click Manage Policy
   6. Under Policy source, select Override parent’s policy
   7. Click Add a rule
   8. Set Enforcement to Off
   9. Click Set Policy
   10. Go back to the Organization Policies list and click the second policy (iam.managed.disableServiceAccountKeyCreation)
   11. Repeat steps 5–9 for this policy
   12. Wait a few minutes for the changes to propagate

   You can now go back and create the JSON key. After creating the key, you may optionally re-enable both policies by repeating the steps above and setting Enforcement back to On.

6. Link the service account to Google Play Console:

   • Go to play.google.com/console → Users and permissions
   • Click Invite new users
   • In the email address field, enter the service account email (found on the service account details page in Google Cloud Console, e.g. [email protected])
   • Under App permissions, select your app and click Apply
   • Under Account permissions, enable at minimum: Release to production, exclude devices, and use Play App Signing
   • Click Invite user and then Send invite

4. Set the Application ID

The Application ID is the unique package name that identifies your app on Google Play. It is permanently baked into the app binary and cannot be changed after the first upload to Google Play.

1. In the admin panel, go to App Studio → Distribution → Android

2. Enter your Application ID using reverse domain notation (e.g., com.yourcompany.yourapp)

3. The field saves automatically

Caution

Choose carefully — this value becomes permanent once the first build is uploaded to Google Play. It must be unique across all apps on Google Play and follow Android package naming rules (lowercase letters, numbers, and dots only).

5. Upload Android Assets

Upload your files to the platform:

1. In the admin panel, go to App Studio → Distribution → Android
2. Upload the following files:

File	Description
GoogleCloudServiceKey.json	Google Play API service account key

Tip

The signing keystore is automatically generated by the platform and managed via Google Play App Signing. You do not need to create or upload a keystore manually.

6. First Release: Manual Upload Required

Google Play requires the very first app bundle to be uploaded manually through the Play Console. The API cannot create a new app listing — it can only update existing ones.

1. Trigger a build from the admin panel — the build will succeed and produce an AAB file

2. Download the AAB from the admin panel (App Studio → Distribution → Android → Download)

3. In Google Play Console, go to your app → Testing → Internal testing → Create new release

4. Upload the AAB file and complete the release

Tip

You only need to do this once. After the first manual upload, all subsequent builds will upload to Google Play automatically.

7. Verify Android Configuration

In App Studio → Distribution → Android, verify that all fields are filled in and no validation errors are shown before triggering a build.

Troubleshooting

”Application ID is required for Android distribution”

The Application ID has not been set. Go to App Studio → Distribution → Android and enter your Application ID (e.g., com.yourcompany.yourapp). This is the unique package name for your app on Google Play. See step 4 above.

”Google Play service account not found”

The GoogleCloudServiceKey.json file is missing or wasn’t uploaded. Upload it via the Distribution page.

”Package name must be specified”

Same as the Application ID error above. The Application ID field on the Distribution page must be filled in before building.

”Upload to Google Play failed”

The service account may not have the correct permissions. Verify:

• The service account is linked in Google Play Console → Settings → API access
• The service account has permission to release to production for your app
• The Google Play Android Developer API is enabled in your Google Cloud project