upload_to_play_store

Upload metadata, screenshots and binaries to Google Play (via supply)

Command line tool for updating Android apps and their metadata on the Google Play Store

supply uploads app metadata, screenshots, binaries, and app bundles to Google Play. You can also select tracks for builds and promote builds to production.

Features • Setup • Quick Start • Commands • Uploading an APK • Uploading an AAB • Images

Features

  • Update existing Android applications on Google Play via the command line
  • Upload new builds (APKs and AABs)
  • Retrieve and edit metadata, such as title and description, for multiple languages
  • Upload the app icon, promo graphics and screenshots for multiple languages
  • Have a local copy of the metadata in your git repository
  • Retrieve version code numbers from existing Google Play tracks

Setup

Setup consists of setting up your Google Developers Service Account

Tip: If you see Google Play Console or Google Developer Console in your local language, add &hl=en at the end of the URL (before any #...) to switch to English. All the links below already have this to make it easier to find the correct buttons.

Note: if you face issues when following these instructions, you might want to refer to the official documentation by Google.

  1. Open the Google Play Console
    1. Click Account Details, and note the Google Cloud Project ID listed there
  2. Enable the Google Play Developer API by selecting an existing Google Cloud Project that fits your needs and pushing ENABLE
    1. If you don't have an existing project or prefer to have a dedicated one for fastlane, create a new one here and follow the instructions
  3. Open Service Accounts on Google Cloud and select the project you'd like to use
    1. Click the CREATE SERVICE ACCOUNT button at the top of the Google Cloud Platform Console page
    2. Verify that you are on the correct Google Cloud Platform Project by looking for the Google Cloud Project ID from earlier within the light gray text in the second input, preceding .iam.gserviceaccount.com, or by checking the project name in the navigation bar. If not, open the picker in the top navigation bar, and find the right one.
    3. Provide a Service account name (e.g. fastlane-supply)
    4. Copy the generated email address that is noted below the Service account-ID field for later use
    5. Click DONE (don't click CREATE AND CONTINUE as the optional steps such as granting access are not needed):
    6. Click on the Actions vertical three-dot icon of the service account you just created
    7. Select Manage keys on the menu
    8. Click ADD KEY → Create New Key
    9. Make sure JSON is selected as the Key type, and click CREATE
    10. Save the file on your computer when prompted and remember where it was saved at
  4. Open the Google Play Console and select Users and Permissions
    1. Click Invite new users
    2. Paste the email address you saved for later use into the email address field
    3. Click on Account Permissions
    4. Choose the permissions you'd like this account to have. We recommend Admin (all permissions), but you may want to manually select all checkboxes and leave out some of the Releases permissions such as Release to production, exclude devices, and use Play App Signing
    5. Click on Invite User

You can use fastlane run validate_play_store_json_key json_key:/path/to/your/downloaded/file.json to test the connection to Google Play Store with the downloaded private key. Once that works, add the path to the JSON file to your Appfile:

json_key_file("path/to/your/play-store-credentials.json")
package_name("my.package.name")

The path is relative to where you normally run fastlane.

Migrating Google credential format (from .p12 key file to .json)

In previous versions of supply, credentials to your Play Console were stored as .p12 files. Since version 0.4.0, supply now supports the recommended .json key Service Account credential files. If you wish to upgrade:

  • follow the Setup procedure once again to make sure you create the appropriate JSON file
  • update your fastlane configuration or your command line invocation to use the appropriate argument if necessary. Note that you don't need to take note nor pass the issuer argument anymore.

The previous p12 configuration is still currently supported.

Quick Start

Before using supply to connect to Google Play Store, you'll need to set up your app manually first by uploading at least one build to Google Play Store. See fastlane/fastlane#14686 for more info.

  • cd [your_project_folder]
  • fastlane supply init
  • Make changes to the downloaded metadata, add images, screenshots and/or an APK
  • fastlane supply

Available Commands

  • fastlane supply: update an app with metadata, a build, images and screenshots
  • fastlane supply init: download metadata for an existing app to a local directory
  • fastlane action supply: show information on available commands, arguments and environment variables

You can either run supply on its own and use it interactively, or you can pass arguments or specify environment variables for all the options to skip the questions.

Uploading an APK

To upload a new binary to Google Play, simply run

fastlane supply --apk path/to/app.apk

This will also upload app metadata if you previously ran fastlane supply init.

To gradually roll out a new build use

fastlane supply --apk path/app.apk --track beta --rollout 0.5

To set the in-app update priority level for a release, set a valid update priority (an integer value from 0 to 5) using option in_app_update_priority

fastlane supply --apk path/app.apk --track beta --in_app_update_priority 3

Expansion files (.obb)

Expansion files (obbs) found under the same directory as your APK will also be uploaded together with your APK as long as:

  • they are identified as type 'main' or 'patch' (by containing 'main' or 'patch' in their file name)
  • you have at most one of each type

If you only want to update the APK, but keep the expansion files from the previous version on Google Play use

fastlane supply --apk path/app.apk --obb_main_references_version 21 --obb_main_file_size 666154207

or

fastlane supply --apk path/app.apk --obb_patch_references_version 21 --obb_patch_file_size 666154207

Uploading an AAB

To upload a new Android application bundle to Google Play, simply run

fastlane supply --aab path/to/app.aab

This will also upload app metadata if you previously ran fastlane supply init.

To gradually roll out a new build use

fastlane supply --aab path/app.aab --track beta --rollout 0.5

To set the in-app update priority level for a release, set a valid update priority (an integer value from 0 to 5) using option in_app_update_priority

fastlane supply --aab path/app.aab --track beta --in_app_update_priority 3

Images and Screenshots

After running fastlane supply init, you will have a metadata directory. This directory contains one or more locale directories (e.g. en-US, en-GB, etc.), and inside this directory are text files such as title.txt and short_description.txt.

Inside of a given locale directory is a folder called images. Here you can supply images with the following file names (extension can be png, jpg or jpeg):

  • featureGraphic
  • icon
  • promoGraphic
  • tvBanner

You can also supply screenshots by creating directories within the images directory with the following names, containing PNGs or JPEGs:

  • phoneScreenshots/
  • sevenInchScreenshots/ (7-inch tablets)
  • tenInchScreenshots/ (10-inch tablets)
  • tvScreenshots/
  • wearScreenshots/

You may name images anything you like, but screenshots will appear in the Play Store in alphanumerical filename order. Note that these will replace the current images and screenshots on the play store listing, not add to them.

Changelogs (What's new)

You can add changelog files under the changelogs/ directory for each locale. The filename should exactly match the version code of the APK that it represents. You can also provide default notes that will be used if no files match the version code by adding a default.txt file. fastlane supply init will populate changelog files from existing data on Google Play if no metadata/ directory exists when it is run.

└── fastlane
    └── metadata
        └── android
            ├── en-US
            │   └── changelogs
            │       ├── default.txt
            │       ├── 100000.txt
            │       └── 100100.txt
            └── fr-FR
                └── changelogs
                    ├── default.txt
                    └── 100100.txt

Track Promotion

A common Play publishing scenario might involve uploading an APK version to a test track, testing it, and finally promoting that version to production.

This can be done using the --track_promote_to parameter. The --track_promote_to parameter works with the --track parameter to command the Play API to promote existing Play track APK version(s) (those active on the track identified by the --track param value) to a new track (--track_promote_to value).

Retrieve Track Release Names & Version Codes

Before performing a new APK upload you may want to check existing track version codes or release names, or you may simply want to provide an informational lane that displays the currently promoted version codes or release name for the production track. You can use the google_play_track_version_codes action to retrieve existing version codes for a package and track. You can use the google_play_track_release_names action to retrieve existing release names for a package and track. For more information, see the fastlane action google_play_track_version_codes and fastlane action google_play_track_release_names help output.

Parallel uploads

By default supply will spawn 10 threads to upload the metadata concurrently (images, screenshots, texts). If you want to change this, set either DELIVER_NUMBER_OF_THREADS or FL_NUMBER_OF_THREADS environment variable to any value between 1 and 10.

If you want supply to upload with more than 10 threads in parallel then you need to additionally set FL_MAX_NUMBER_OF_THREADS environment variable to the max number of parallel upload threads you wish to have (Warning ⚠️ use this at your own risk!).

Migration from AndroidPublisherV2 to AndroidPublisherV3 in fastlane 2.135.0

New Options

  • :version_name
    • Used when uploading with :apk_path, :apk_paths, :aab_path, and :aab_paths
    • Can be any string such (example: "October Release" or "Awesome New Feature")
    • Defaults to the version name in app/build.gradle or AndroidManifest.xml
  • :release_status
    • Used when uploading with :apk_path, :apk_paths, :aab_path, and :aab_paths
    • Can set as "draft" to complete the release at some other time
    • Defaults to "completed"
  • :version_code
    • Used for :update_rollout, :track_promote_to, and uploading of meta data and screenshots
  • :skip_upload_changelogs
    • Changelogs were previously included with the :skip_upload_metadata but is now its own option

Deprecated Options

  • :check_superseded_tracks
    • Google Play will automatically remove releases that are superseded now
  • :deactivate_on_promote
    • Google Play will automatically deactivate a release from its previous track on promote
upload_to_play_store
Supported platforms android
Author @KrauseFx

2 Examples

upload_to_play_store

supply # alias for "upload_to_play_store"

Parameters

Key Description Default
package_name The package name of the application to use *
version_name Version name (used when uploading new apks/aabs) - defaults to 'versionName' in build.gradle or AndroidManifest.xml *
version_code The versionCode for which to download the generated APK *
release_status Release status (used when uploading new apks/aabs) - valid values are completed, draft, halted, inProgress *
track The track of the application to use. The default available tracks are: production, beta, alpha, internal production
rollout The percentage of the user fraction when uploading to the rollout track (setting to 1 will complete the rollout)
metadata_path Path to the directory containing the metadata files *
key DEPRECATED! Use --json_key instead - The p12 File used to authenticate with Google *
issuer DEPRECATED! Use --json_key instead - The issuer of the p12 file (email address of the service account) *
json_key The path to a file containing service account JSON, used to authenticate with Google *
json_key_data The raw service account JSON data used to authenticate with Google *
apk Path to the APK file to upload *
apk_paths An array of paths to APK files to upload
aab Path to the AAB file to upload *
aab_paths An array of paths to AAB files to upload
skip_upload_apk Whether to skip uploading APK false
skip_upload_aab Whether to skip uploading AAB false
skip_upload_metadata Whether to skip uploading metadata, changelogs not included false
skip_upload_changelogs Whether to skip uploading changelogs false
skip_upload_images Whether to skip uploading images, screenshots not included false
skip_upload_screenshots Whether to skip uploading SCREENSHOTS false
sync_image_upload Whether to use sha256 comparison to skip upload of images and screenshots that are already in Play Store false
track_promote_to The track to promote to. The default available tracks are: production, beta, alpha, internal
track_promote_release_status Promoted track release status (used when promoting a track) - valid values are completed, draft, halted, inProgress completed
validate_only Only validate changes with Google Play rather than actually publish false
mapping Path to the mapping file to upload (mapping.txt or native-debug-symbols.zip alike)
mapping_paths An array of paths to mapping files to upload (mapping.txt or native-debug-symbols.zip alike)
root_url Root URL for the Google Play API. The provided URL will be used for API calls in place of https://www.googleapis.com/
check_superseded_tracks DEPRECATED! Google Play does this automatically now - Check the other tracks for superseded versions and disable them false
timeout Timeout for read, open, and send (in seconds) 300
deactivate_on_promote DEPRECATED! Google Play does this automatically now - When promoting to a new track, deactivate the binary in the origin track true
version_codes_to_retain An array of version codes to retain when publishing a new APK
changes_not_sent_for_review Indicates that the changes in this edit will not be reviewed until they are explicitly sent for review from the Google Play Console UI false
rescue_changes_not_sent_for_review Catches changes_not_sent_for_review errors when an edit is committed and retries with the configuration that the error message recommended true
in_app_update_priority In-app update priority for all the newly added apks in the release. Can take values between [0,5]
obb_main_references_version References version of 'main' expansion file
obb_main_file_size Size of 'main' expansion file in bytes
obb_patch_references_version References version of 'patch' expansion file
obb_patch_file_size Size of 'patch' expansion file in bytes
ack_bundle_installation_warning Must be set to true if the bundle installation may trigger a warning on user devices (e.g can only be downloaded over wifi). Typically this is required for bundles over 150MB false

* = default value is dependent on the user's system

Documentation

To show the documentation in your terminal, run

fastlane action upload_to_play_store

CLI

It is recommended to add the above action into your Fastfile, however sometimes you might want to run one-offs. To do so, you can run the following command from your terminal

fastlane run upload_to_play_store

To pass parameters, make use of the : symbol, for example

fastlane run upload_to_play_store parameter1:"value1" parameter2:"value2"

It's important to note that the CLI supports primitive types like integers, floats, booleans, and strings. Arrays can be passed as a comma delimited string (e.g. param:"1,2,3"). Hashes are not currently supported.

It is recommended to add all fastlane actions you use to your Fastfile.

Source code

This action, just like the rest of fastlane, is fully open source, view the source code on GitHub

Back to actions