Hercules

Publish to App StorePublish to App Store

Publish your appPublish to App Store

Publish Your App

Publish your app to Google Play, the App Store, or Microsoft Store, or let people install it from the web. Hercules builds your Android and iOS apps, keeps the signing keys for you, uploads every build after the first, and submits iOS builds to App Review.

Everything starts in Mobile in the Sidebar. Click Enable mobile support if you have not yet, then click Publish to App Store under Install it on your phone.

How do I publish my app to the App Store?

Hercules builds your Android app. You upload the first release in the Play Console by hand, then Hercules uploads every later build to Google Play for you.

  1. Connect Your Store Accounts

    Click Mobile → Publish to App Store. To connect Google Play now, click Connect next to Google Play and add a service account key: see Connect Google Play below for how to create one. If your organization already has a store account, it is picked for you, and you can choose a different one from the list. Hercules then checks your package name against Google Play on the next step, and tells you the version code your next build gets.

    This is optional. Click Build your app to skip it and connect later.

  2. Name Your App

    Fill in:

    • Store icon: a square PNG at least 1024x1024px. Transparent areas become white. It becomes your launcher icon. Leave it empty to use your home screen icon: the first build copies it in
    • App name: the name shown under your icon on the phone
    • Version: the version shown on your store listing, like 1.0.0
    • Android package name: a permanent ID for your app, like app.hercules.myapp. If your app is already on Google Play, enter its package name exactly, and read How do I update an app that is already on Google Play? first
    • Device permissions: turn on Camera, Microphone, or Location if your app uses them. Each switch covers your iOS build too. With Location on, turn on Background location if your app needs to keep reading location while it is in the background or the screen is locked, such as for delivery or run tracking

    Click Create mobile app. You can change these later from App settings (the gear icon at the right of your app's name, at the top of the Mobile page).

    New Android builds need Android 7 or later (API 24). Android 6 devices cannot install or update to these builds; versions already installed keep working.

  3. Publish Your App

    Click Publish app. Hercules opens the Publish menu on the Preview tab; publish from there. Your Android app loads your published app, so Hercules cannot build until it is online.

  4. Build Your Android App

    Click Build Android App. Click View live log to watch each step.

    The first build takes longest, because Hercules installs the Android build tools first.

    To let your Android app receive push notifications, create a project in the Firebase console, add an Android app with your app's package name, and download its google-services.json. Then open App settings, turn on Android push notifications, upload the file under Android push notification config, and save before building. Your app's code can then call window.Capacitor.Plugins.PushNotifications to ask for permission, register, and get the device token from its registration event. Apps built before you turn push on cannot receive notifications: build and install a new one.

  5. Upload Your First Release

    Google requires the first release of a new app to be uploaded by hand. You need a Google Play Developer account ($25 one time).

    1. Click Download .aab to get your app bundle (the file Google Play accepts)
    2. In the Play Console, click Create app and fill in its name, language, and type. If the app already exists, open it instead
    3. Click Testing → Internal testing → Create new release
    4. Upload the .aab file
    5. Under Policy and programs → App content, complete every declaration, including Sign-in details for reviewers. Then fill in the Main store listing. See what Google Play needs
    6. Add your own Google account as a tester, then install the app from the test link
    7. Back in Hercules, click I uploaded the first release

    If Background location is on, App content also asks for a Foreground service permissions declaration: choose location, say what your app tracks and why, and link a short video (a screen recording is fine) that shows the feature in use. Complete the Location permissions declaration the same way if Play Console lists it. Google reviews these before the release goes live. While your app reads location in the background, Android shows a notification that stays until tracking stops. On Android 13 and later, it shows in the notification shade only if the person allows notifications for your app.

    Clicking I uploaded the first release locks the package name to your Play listing.

  6. Connect Google Play

    Do this once, and Hercules uploads every later build to internal testing. If you connected Google Play at the start, this step does not appear.

    1. In Google Cloud, create a service account (a robot account that acts for you) and download its JSON key
    2. In the same Google Cloud project, open the Google Play Android Developer API and click Enable
    3. In the Play Console, open Users and permissions, invite the service account email, and grant it Release apps to testing tracks for this app
    4. In Hercules, click Add credentials, choose the JSON key file, and click Connect

    Your next build uploads itself to internal testing. Before each build, Hercules checks that Google Play accepts the service account, so a missing permission or a disabled API shows up before the build starts.

  7. Go Live

    When your test build looks right, open the Play Console and promote the release from Internal testing to Production. Google reviews it before it goes live, which can take up to 7 days, or longer in exceptional cases.

Package Android yourself with PWA Builder

Only use this if you want to package the app yourself instead of letting Hercules build it.

  1. Generate Android Package with PWA Builder

    1. Go to pwabuilder.com
    2. Enter your app URL (e.g. https://my-app.onhercules.app or your custom domain)
    3. Click Start, then Package for stores
    4. Select Android and download the AAB file

  2. Set Up Digital Asset Links

    PWA Builder wraps your app in a browser window, so Google Play needs a Digital Asset Links file to confirm you own your domain. Without it, your app opens with a browser address bar instead of running full screen.

    1. On the PWA Builder Android package screen, copy the assetlinks.json snippet it generates (it includes your package name and SHA256 fingerprint, a unique ID tied to your signing key)
    2. Ask Hercules to add it to your app:
    Add Digital Asset Links file
    Create a file at public/.well-known/assetlinks.json with this exact content:

[paste the JSON PWA Builder generated for your Android package]
    1. Publish your app again so the file goes live
    2. Visit https://my-app.onhercules.app/.well-known/assetlinks.json (or your custom domain). It should return the JSON you pasted, not your app's page

  3. Submit to Google Play

    1. Go to Google Play Console
    2. Click Create app and fill in details
    3. Click Production → Create new release
    4. Upload the AAB file and complete your store listing
    5. Submit for review

Google Play says the service account has no access to my app

Google Play has not given the service account you connected permission to publish this app. Hercules checks this before each build, so the build does not start.

  1. Copy the service account email from the error (it ends in iam.gserviceaccount.com)
  2. In the Play Console, open Users and permissions and click Invite new users
  3. Enter that email, open App permissions, add this app, and grant Release apps to testing tracks
  4. Click Invite user, then build again in Hercules

To build without uploading to Google Play, detach the credential: open App settings and set Google Play credential to No credential. You can then download the .aab file and upload it by hand.

Google Play says the Android Developer API is not enabled

The Google Cloud project that holds your service account has the Google Play Android Developer API turned off, so Google refuses every request from that key. Hercules checks this before each build, so the build does not start.

  1. Open the link in the error, or open the Google Play Android Developer API page and select the project that holds your service account
  2. Click Enable
  3. Wait a few minutes, then build again in Hercules

Google Play says my app is still a draft

Google Play accepts only draft releases until the app's first release is rolled out in the Play Console, so it refuses the upload.

  1. In the Play Console, open your app and finish every setup task on its Dashboard
  2. Open Testing → Internal testing and roll out the release you uploaded by hand
  3. Build again in Hercules

Why does Google Play hold my build until I send it for review?

Sometimes Google Play takes an upload but will not send it for review on its own, for example after it rejected an earlier update. Hercules still uploads the build and shows a note on the Go Live step.

  1. In the Play Console, open Publishing overview
  2. Under Changes not yet sent for review, click Send for review

Why does my Android app show the default icon?

The app had no store icon or home screen icon when it was built. Open App settings, upload a Store icon (a square PNG at least 1024x1024px), click Save changes, and build again.

Uninstall the old version from your phone before you install the new build. Android launchers cache icons, so an update can keep showing the old one.

Why does Google Play say my app bundle needs a different package name?

Google Play ties an app to the package name of the first file uploaded to it, and rejects every later upload with a different one. The error names the package Play expects.

  • Before you click I uploaded the first release: open App settings, set Android package name to exactly the name in the error, click Save changes, and build again.
  • After that: Hercules locks the package name to match your Play listing. To publish under a new name, create a new app in the Play Console, then click Unlock for a new Play listing under the package name in App settings.

If your app was on Google Play before you used Hercules, enter its existing package name before your first build. Google Play also checks the upload key: see How do I update an app that is already on Google Play?

Do I need to save my Android signing key?

Not for apps built by Hercules. Hercules creates this app's upload key (the key that signs each .aab) on its first Android build, stores it securely, and signs every later build with it. The dashboard never shows or exports the key. Its certificate is in App settings under Android upload certificate.

With Play App Signing (the default for new apps), Google signs the copy of your app that people install with its own key. The upload key only proves that a build comes from you, and Google can reset it. To update the app with another tool later, create an upload key in that tool and request an upload key reset with its certificate. Your listing, users, and reviews stay where they are.

If you package with PWA Builder, save your signing key somewhere safe. Google will not accept an update signed with a different key unless you reset the upload key.

How do I update an app that is already on Google Play?

Google Play checks two things on every upload: the package name, and the upload key that signed the .aab. Hercules signs with its own upload key, which it creates on your first Android build.

  1. Open App settings and set Android package name to the exact package name of your Play app
  2. If the app was first published with another tool, such as PWA Builder or Android Studio, Play expects that tool's upload key and rejects Hercules builds. Build once in Hercules with no Google Play credential attached, so Hercules creates its key. Then reset the upload key to it (below)
  3. Attach a Google Play credential before you build an update: create one as in the Connect Google Play step above, then choose it under Google Play credential in App settings. Hercules then reads the highest version code on Google Play and starts above it. Without a credential, Play refuses a build whose version code it already has

To reset the upload key to the Hercules key:

  1. Open App settings and, under Android upload certificate, click Download certificate to save upload_certificate.pem. It is available after your next Android build, so build for Android once if the button is grayed out. If that does not help, contact support
  2. In the Play Console, open Protected with Play → Play Store protection → Manage Play app signing
  3. Under Upload key certificate, click Request upload key reset, enter the reason, upload upload_certificate.pem, and click Request
  4. Once the reset takes effect, build in Hercules and upload as usual

The reset needs Play App Signing. If that page shows that you manage the app signing key yourself, Hercules cannot sign updates for this app today. Contact support.

Did you reset the upload key to a key of your own? Play then rejects every Hercules build, because Hercules cannot sign with your key today. Request another reset with the Hercules upload certificate.

What do I do when a build fails?

If Hercules can tell a build would fail, it does not start it and says why, for example when your app is not published yet or Google Play has not given the service account access. Fix what it names and click the build button again.

If a build starts and then fails, the reason shows in red on the build step and on the build under Recent builds. Fix what it names, then click Build again.

If the reason is unclear or the same build keeps failing, click Report this error. The report includes the build ID, so we can look up exactly what happened. You can also copy the Build ID and send it to support.

FAQ

Why does App Review say my version cannot be reviewed?

Something Apple requires is missing. The error lists what and the next step for each:

  • Pricing: set a price under Pricing and Availability in App Store Connect (Free is fine)
  • App Privacy: answer the App Privacy questionnaire in App Store Connect
  • Screenshots, age rating, Copyright, or Keywords: fill them in the store listing in Hercules
  • What's new in this version: Apple requires it for every version after the first. Fill it in the store listing in Hercules

Then submit for review again.

Why did my iOS upload to App Store Connect fail?

The build shows Apple's reason. Common ones:

  • An earlier version supported iPad: Apple does not let an update drop devices. Turn on Also run on iPad in the store listing, add iPad screenshots, and build again
  • The version is already on the App Store: raise the Version in App settings and build again. The build number goes up on its own
  • No app with your bundle ID: create the app in App Store Connect with the exact bundle ID Hercules shows, then build again
My iOS distribution certificate or provisioning profile expires soon

Apple's signing files expire. Hercules warns you 30 days ahead under Set up iOS signing. Click Reset signing, then Set up signing, and build again. iOS builds fail once either file has expired.

Apple says I have reached the limit of distribution certificates

Your Apple Developer account allows only a few iOS distribution certificates. Revoke one you no longer use in the Apple Developer portal (Certificates, Identifiers & Profiles), then click Set up signing again.

Why was my iOS app rejected?

Common reasons: the reviewer could not sign in, no way to delete an account in the app, Google sign-in without Sign in with Apple, digital goods sold outside in-app purchase, or an app too similar to a website. Read Apple's full reason in App Store Connect, then see what App Review looks for.

Why was my Android app rejected?

Common reasons: an incomplete App content declaration, a reviewer who could not sign in, broken features, a missing privacy policy, or digital goods sold without Google Play's billing system. See what Google Play needs.

How long does review take?
  • Google Play: Google says up to 7 days, or longer in exceptional cases. Personal accounts created after November 13, 2023 also need a 14-day closed test first
  • App Store: usually 1-3 days
  • Microsoft Store: usually 1-3 days

First submissions may take longer.

Why does my Android icon look cropped or smaller than expected?

Android shows icons inside a shape, usually a circle or rounded square, so the corners of a square image are cut off. When your store icon has a plain-color border, Hercules shrinks the artwork onto that color so nothing important is cut. Icons with a photo or gradient edge stay full size and may lose their corners. Keep text and logos away from the edges of the image.

Google Play warns about edge-to-edge or large screens

Google Play shows these as recommendations, not errors, so your release still goes live. "Edge-to-edge may not display for all users" and "Your app uses deprecated APIs or parameters for edge-to-edge" come from the Android shell Hercules builds around your app, not from your app's code, and need no change from you. If Play also asks you to remove resizability and orientation restrictions, check which release it names: Hercules builds do not lock the screen orientation, so the warning comes from a release made with another tool.

Play Protect says my app was built for an older Android. Why?

Builds from Mobile → Android already target the current version. The warning comes from installing via another packager such as PWA Builder. Repackage targeting Android 16 (API 36) with your original key, or build in Hercules.

Google Play says the test app is already installed

A copy of the app with the same package name is already on the phone, often one installed from a downloaded file or signed with a different key. Uninstall every copy of the app, then open the internal testing link again.

Can I publish to multiple stores?

Yes. Each store needs its own package, but the underlying app is the same one. Hercules builds your Android and iOS apps. For Microsoft Store, use PWA Builder.

How do I switch from installing from the web to the app stores?

Go to Mobile → View all steps → Install it on your phone, then click Publish to App Store and follow the Android or iOS steps.

Why does my Android app show a browser address bar instead of running full screen?

This affects apps packaged with PWA Builder. Your Digital Asset Links file (assetlinks.json) is missing, or does not match your signing key. See the Set Up Digital Asset Links step in the PWA Builder section of the Google Play tab above. Apps built by Hercules run full screen without this file.

Do PWAs work offline?

Partly. After Enable mobile support, an installed app opens without a connection and shows the screens the person has already opened. Anything that loads or saves data still needs a connection. To change what is saved for offline use, ask Hercules to adjust the service worker (the script that caches your app on the phone).

Why PWA instead of app stores?

PWAs ship faster (no review), update the moment you publish, work on every platform, and need no developer accounts. People install them from the browser instead of a store. We recommend testing as a PWA, then publishing to the stores when you are ready.