upload_to_app_store

Upload metadata and binary to App Store Connect (via deliver)

deliver uploads screenshots, metadata and binaries to App Store Connect. Use deliver to submit your app for App Store review.

Features • Quick Start • Usage • Tips

deliver is part of fastlane: The easiest way to automate beta deployments and releases for your iOS and Android apps.

Features

• Upload hundreds of localized screenshots completely automatically
• Upload a new ipa/pkg file to App Store Connect without Xcode from any Mac
• Maintain your app metadata locally and push changes back to App Store Connect
• Easily implement a real Continuous Deployment process using fastlane
• Store the configuration in git to easily deploy from any Mac, including your Continuous Integration server
• Get a HTML preview of the fetched metadata before uploading the app metadata and screenshots to iTC
• Automatically uses precheck to ensure your app has the highest chances of passing app review the first time

To upload builds to TestFlight check out pilot.

Quick Start

The guide will create all the necessary files for you, using the existing app metadata from App Store Connect.

• cd [your_project_folder]
• fastlane deliver init
• Enter your App Store Connect credentials
• Enter your app identifier
• Enjoy a good drink, while the computer does all the work for you

From now on, you can run fastlane deliver to deploy a new update, or just upload new app metadata and screenshots.

Usage

Check out your local ./fastlane/metadata and ./fastlane/screenshots folders (if you don't use fastlane it's ./metadata instead)

You'll see your metadata from App Store Connect. Feel free to store the metadata in git (not the screenshots). You can now modify it locally and push the changes back to App Store Connect.

Run fastlane deliver to upload the app metadata from your local machine

fastlane deliver

Provide the path to an ipa file to upload and submit your app for review:

fastlane deliver --ipa "App.ipa" --submit_for_review

or you can specify path to pkg file for macOS apps:

fastlane deliver --pkg "MacApp.pkg"

If you use fastlane you don't have to manually specify the path to your ipa/pkg file.

This is just a small sub-set of what you can do with deliver, check out the full documentation in #more-options

Download existing screenshots from App Store Connect

fastlane deliver download_screenshots

Download existing metadata from App Store Connect

fastlane deliver download_metadata

To get a list of available options run

fastlane action deliver

Use in a Fastfile

deliver

deliver(
  submit_for_review: true,
  force: true,
  metadata_path: "./metadata"
)

More options

deliver(
  submit_for_review: true,
  metadata_path: "../folder"
)

ipa("App.ipa")

pkg("MacApp.pkg")

app_version("2.0")

skip_app_version_update(true)

submit_for_review(true)

force(true)

price_tier 0

trade_representative_contact_information(
  first_name: "Felix",
  last_name: "Krause",
  address_line1: "1 Infinite Loop",
  address_line2: "",
  address_line3: null,
  city_name: "Cupertino",
  state: "California",
  country: "United States",
  postal_code: "95014",
  phone_number: "+43 123123123",
  email_address: "github@krausefx.com",
)

app_review_information(
  first_name: "Felix",
  last_name: "Krause",
  phone_number: "+43 123123123",
  email_address: "github@krausefx.com",
  demo_user: "demoUser",
  demo_password: "demoPass",
  notes: "such notes, very text"
)

app_review_attachment_file: "./readme.txt"

submission_information({
  add_id_info_serves_ads: true,
  ...
})

automatic_release(true)
# or
automatic_release(false)

phased_release(true)
# or
phased_release(false)

reset_ratings(true)
# or
reset_ratings(false)

description({
  'en-US' => "English Description here",
  'de-DE' => "Deutsche Beschreibung hier"
})

subtitle(
  "en-US" => "Awesome English subtitle here",
  "de-DE" => "Jetzt mit deutschen Untertiteln!"
)

keywords(
  "en-US" => "Keyword1, Keyword2"
)

promotional_text(
  "en-US" => "Hey, you should totally buy our app, it's the best",
  "de-DE" => "App kaufen bitte"
)

app_icon('./AppIcon.png')

apple_watch_app_icon('./AppleWatchAppIcon.png')

copyright("#{Time.now.year} Felix Krause")

Submit Build

deliver allows you to promote an existing build to production. Below are examples to select a previously uploaded build and submit it for review.

fastlane deliver submit_build --build_number 830

Submit build in a Fastfile

lane :submit_review do
  deliver(
    build_number: '830',
    submit_for_review: true,
    automatic_release: true,
    force: true, # Skip HTMl report verification
    skip_metadata: true,
    skip_screenshots: true,
    skip_binary_upload: true
  )
end

Omit build_number to let fastlane automatically select the latest build number for the current version being edited for release from App Store Connect.

Compliance and IDFA settings

Use the submission_information parameter for additional submission specifiers, including compliance and IDFA settings. Look at the Spaceship's app_submission.rb file for options. See this example.

fastlane deliver submit_build --build_number 830 --submission_information "{\"export_compliance_uses_encryption\": false, \"add_id_info_uses_idfa\": false }"

App Privacy Details

Starting on December 8, 2020, Apple announced that developers are required to provide app privacy details that will help users understand an app's privacy practices. deliver does not allow for updating of this information but this can be done with the upload_app_privacy_details_to_app_store action. More information on Uploading App Privacy Details

Credentials

A detailed description about how your credentials are handled is available in a credentials_manager.

How does this thing even work? Is magic involved? 🎩

Your password will be stored in the macOS keychain, but can also be passed using environment variables. (More information available on CredentialsManager)

Before actually uploading anything to iTunes, deliver will generate a HTML summary of the collected data.

deliver uses the following techniques under the hood:

• The iTMSTransporter tool is used to upload the binary to App Store Connect. iTMSTransporter is a command line tool provided by Apple.
• For all metadata related actions deliver uses spaceship

Tips

Available language codes

ar-SA, ca, cs, da, de-DE, el, en-AU, en-CA, en-GB, en-US, es-ES, es-MX, fi, fr-CA, fr-FR, he, hi, hr, hu, id, it, ja, ko, ms, nl-NL, no, pl, pt-BR, pt-PT, ro, ru, sk, sv, th, tr, uk, vi, zh-Hans, zh-Hant

Available Metadata Folder Options

deliver allows for metadata to be set through .txt files in the metadata folder. This metadata folder location is defaulted to ./fastlane/metadata but can be overridden through the metadata_path parameter. Below are all allowed metadata options.

Non-Localized Metadata

Localized Metadata

Review Information Metadata

Reference

Default values

Deliver has a special default language code which allows you to provide values that are not localized, and which will be used as defaults when you don’t provide a specific localized value.

In order to use default, you will need to tell deliver which languages your app uses. You can do this in either of two ways:

1. Create the folders named with the language in the metadata folder (i.e. fastlane/metadata/en-US or fastlane/metadata/de-DE)
2. Add the following to your Deliverfile languages(['en-US','de-DE'])

You can use this either in json within your Deliverfile and/or as folders in your metadata folder. deliver will take the union of both language sets from the Deliverfile and from the metadata folder and create on single set of languages which will be enabled.

Imagine that you have localized data for the following language codes: en-US, de-DE, el, it

You can set the following in your Deliverfile

release_notes({
  'default' => "Shiny and new",
  'de-DE' => "glaenzend und neu"
})

Deliver will use "Shiny and new" for en-US, el and it.

It will use "glaenzend und neu" for de-DE.

You can do the same with folders

   default
      keywords.txt
      marketing_url.txt
      name.txt
      privacy_url.txt
      support_url.txt
      release_notes.txt
   en-US
      description.txt
   de-DE
      description.txt
   el
      description.txt
   it
      description.txt

In this case, default values for keywords, urls, name and release notes are used in all localizations, but each language has a fully localized description

Uploading screenshots for "iPad Pro (12.9-inch) (3rd generation)"

Starting March 20, 2019 Apple's App Store requires 12.9-inch iPad Pro (3rd generation) screenshots additionally to the iPad Pro 2nd generation screenshots. As fastlane historically uses the screenshot dimensions to determine the "display family" of a screenshot, this poses a problem as both use the same dimensions and are recognized as the same device family.

To solve this a screenshot of a 12.9-inch iPad Pro (3rd generation) must contain either the string iPad Pro (12.9-inch) (3rd generation), IPAD_PRO_3GEN_129, or ipadPro129 (Apple's internal naming of the display family for the 3rd generation iPad Pro) in its filename to be assigned the correct display family and to be uploaded to the correct screenshot slot in your app's metadata.

Automatically create screenshots

If you want to integrate deliver with snapshot, check out fastlane!

Jenkins integration

Detailed instructions about how to set up deliver and fastlane in Jenkins can be found in the fastlane README.

Firewall Issues

deliver uses the iTunes Transporter to upload metadata and binaries. In case you are behind a firewall, you can specify a different transporter protocol using

DELIVER_ITMSTRANSPORTER_ADDITIONAL_UPLOAD_PARAMETERS="-t DAV" fastlane deliver

HTTP Proxy

iTunes Transporter is a Java application bundled with Xcode. In addition to utilizing the DELIVER_ITMSTRANSPORTER_ADDITIONAL_UPLOAD_PARAMETERS="-t DAV", you need to configure the transporter application to use the proxy independently from the system proxy or any environment proxy settings. You can find the configuration file within Xcode:

for Xcode11 and later

TOOLS_PATH=$( xcode-select -p )
REL_PATH='../SharedFrameworks/ContentDeliveryServices.framework/Versions/A/itms/java/lib/net.properties'
echo "$TOOLS_PATH/$REL_PATH"

for Xcode10 or earlier

TOOLS_PATH=$( xcode-select -p )
REL_PATH='../Applications/Application Loader.app/Contents/itms/java/lib/net.properties'
echo "$TOOLS_PATH/$REL_PATH"

Add necessary proxy configuration values to the net.properties according to Java Proxy Configuration.

As an alternative to editing the properties files, proxy configuration can be specified on the command line directly:

DELIVER_ITMSTRANSPORTER_ADDITIONAL_UPLOAD_PARAMETERS="-t DAV -Dhttp.proxyHost=myproxy.com -Dhttp.proxyPort=8080"

Limit

App Store Connect has a limit of 150 binary uploads per day.

Editing the Deliverfile

Change syntax highlighting to Ruby.

Provider Short Name

If you are on multiple App Store Connect teams, deliver needs a provider short name to know where to upload your binary. deliver will try to use the long name of the selected team to detect the provider short name. To override the detected value with an explicit one, use the itc_provider option.

3 Examples

upload_to_app_store(
  force: true, # Set to true to skip verification of HTML preview
  itc_provider: "abcde12345" # pass a specific value to the iTMSTransporter -itc_provider option
)

deliver   # alias for "upload_to_app_store"

appstore  # alias for "upload_to_app_store"

Parameters

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

Documentation

To show the documentation in your terminal, run

fastlane action upload_to_app_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_app_store

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

fastlane run upload_to_app_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