deliver

Alias for the upload_to_app_store action

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


FeaturesQuick StartUsageTips


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)

/img/actions/deliver_metadata.png

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

Select a previously uploaded build and submit it for review.

fastlane deliver submit_build --build_number 830

Use in a Fastfile

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

More options

View all available options and their valid values

Available options

All the options below can easily be added to your Deliverfile. The great thing: if you use fastlane you can use all these options from your Fastfile too, for example:

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

The bundle identifier (e.g. "com.krausefx.app")

username

Your Apple ID email address

ipa

A path to a signed ipa file, which will be uploaded. If you don't provide this value, only app metadata will be uploaded. If you want to submit the app for review make sure to either use fastlane deliver --submit_for_review or add submit_for_review true to your Deliverfile

ipa("App.ipa")

if you use fastlane the ipa file will automatically be detected.

pkg

A path to a signed pkg file, which will be uploaded. Submission logic of ipa applies to pkg files.

pkg("MacApp.pkg")
app_version

Optional, as it is usually automatically detected. Specify the version that should be created / edited on App Store Connect:

app_version("2.0")
skip_app_version_update

In the case if deliver uploads your application to App Store Connect it will automatically update "Prepare for submission" app version (which could be found on App Store Connect->My Apps->App Store page)

The option allows uploading your app without updating "Prepare for submission" version.

This could be useful in the case if you are generating a lot of uploads while not submitting the latest build for Apple review.

The default value is false.

skip_app_version_update(true)
submit_for_review

Add this to your Deliverfile to automatically submit the app for review after uploading metadata/binary. This will select the latest build.

submit_for_review(true)
screenshots_path

A path to a folder containing subfolders for each language. This will automatically detect the device type based on the image resolution. Also includes  Watch Support.

/img/actions/deliver_screenshots.png

metadata_path

Path to the metadata you want to use. The folder has to be structured like this

/img/actions/deliver_metadata.png

If you run deliver init this will automatically be created for you.

force
force(true)

If set to true, no HTML report will be generated before the actual upload. You can also pass --force when calling deliver.

price_tier

Pass the price tier as number. This will be active from the current day.

price_tier 0
trade_representative_contact_information

Trade Representative Contact information for Korean App Store. Available options: first_name, last_name, address_line1, address_line2, address_line3, city_name, state, country, postal_code, phone_number, email_address, is_displayed_on_app_store.

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",
)

You can also provide these values by creating files in a metadata/trade_representative_contact_information/ directory. The file names must match the pattern <key>.txt (e.g. first_name.txt, address_line1.txt etc.). The contents of each file will be used as the value for the matching key. Values provided in the Deliverfile or Fastfile will be take priority over values from these files.

is_displayed_on_app_store is the option on App Store Connect described as: Display Trade Representative Contact Information on the Korean App Store

app_review_information

Contact information for the app review team. Available options: first_name, last_name, phone_number, email_address, demo_user, demo_password, notes.

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"
)

You can also provide these values by creating files in a metadata/review_information/ directory. The file names must match the pattern <key>.txt (e.g. first_name.txt, notes.txt etc.). The contents of each file will be used as the value for the matching key. Values provided in the Deliverfile or Fastfile will be take priority over values from these files.

submission_information

Must be a hash. This is used as the last step for the deployment process, where you define if you use third party content or use encryption. A list of available options.

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

Should the app be released to all users once Apple approves it? If set to false, you'll have to manually release the update once it got approved.

automatic_release(true)
# or
automatic_release(false)
phased_release

Enable or disable the phased releases feature of App Store Connect. If set to true, the update will be released over a 7 day period. Default behavior is to leave whatever you defined on App Store Connect.

phased_release(true)
# or
phased_release(false)
app_rating_config_path

You can set the app age ratings using deliver. You'll have to create and store a JSON configuration file. Copy the template to your project folder and pass the path to the JSON file using the app_rating_config_path option.

The keys/values on the top allow values from 0-2, and the items on the bottom allow only 0 or 1. More information in #reference.

Metadata

All options below are useful if you want to specify certain app metadata in your Deliverfile or Fastfile

Localized

Localized values should be set like this

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

The title/name of the app

subtitle

Localized subtitle of the app

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

The description of the app

release_notes

The release_notes (What's new / Changelog) of the latest version

support_url, marketing_url, privacy_url

These URLs are shown in the AppStore

keywords

Keywords separated using a comma.

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

Localized promotional text

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

A path to a new app icon, which must be exactly 1024x1024px

app_icon('./AppIcon.png')
apple_watch_app_icon

A path to a new app icon for the  Watch, which must be exactly 1024x1024px

apple_watch_app_icon('./AppleWatchAppIcon.png')
platform

The platform of your application (a.e. ios, osx).

This option is optional. The default value is "ios" and deliver should be able to figure out the platform from your binary.

However, in the case if multiple binaries present, you can specify a platform which you want to deliver explicitly.

The available options:

  • 'ios'
  • 'appletvos'
  • 'osx'

Non-Localized

The up to date copyright information.

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

The english name of the category you want to set (e.g. Business, Books)

See #reference for a list of available categories

secondary_category

The english name of the secondary category you want to set

primary_first_sub_category

The english name of the primary first sub category you want to set

primary_second_sub_category

The english name of the primary second sub category you want to set

secondary_first_sub_category

The english name of the secondary first sub category you want to set

secondary_second_sub_category

The english name of the secondary second sub category you want to set

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

da, de-DE, el, en-AU, en-CA, en-GB, en-US, es-ES, es-MX, fi, fr-CA, fr-FR, id, it, ja, ko, ms, nl-NL, no, pt-BR, pt-PT, ru, sv, th, tr, 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

Key Editable While Live Directory Filename
copyright Yes <metadata_path> copyright.txt
primary_category No <metadata_path> primary_category.txt
secondary_category No <metadata_path> secondary_category.txt
primary_first_sub_category No <metadata_path> primary_first_sub_category.txt
primary_second_sub_category No <metadata_path> primary_second_sub_category.txt
secondary_first_sub_category No <metadata_path> secondary_first_sub_category.txt
secondary_second_sub_category No <metadata_path> secondary_second_sub_category.txt

Localized Metadata

Key Editable While Live Directory Filename
name No <metadata_path>/<lang>/ name.txt
subtitle No <metadata_path>/<lang>/ subtitle.txt
privacy_url Yes <metadata_path>/<lang>/ privacy_url.txt
description Yes <metadata_path>/<lang>/ description.txt
keywords No <metadata_path>/<lang>/ keywords.txt
release_notes Yes <metadata_path>/<lang>/ release_notes.txt
support_url Yes <metadata_path>/<lang>/ support_url.txt
marketing_url Yes <metadata_path>/<lang>/ marketing_url.txt
promotional_text Yes <metadata_path>/<lang>/ promotional_text.txt

Trade Representative Contact Information Metadata

Key Editable While Live Directory Filename
trade_name Yes <metadata_path>/trade_representative_contact_information trade_name.txt
first_name Yes <metadata_path>/trade_representative_contact_information first_name.txt
last_name Yes <metadata_path>/trade_representative_contact_information last_name.txt
address_line1 Yes <metadata_path>/trade_representative_contact_information address_line1.txt
address_line2 Yes <metadata_path>/trade_representative_contact_information address_line2.txt
address_line3 Yes <metadata_path>/trade_representative_contact_information address_line3.txt
city_name Yes <metadata_path>/trade_representative_contact_information city_name.txt
state Yes <metadata_path>/trade_representative_contact_information state.txt
country Yes <metadata_path>/trade_representative_contact_information country.txt
postal_code Yes <metadata_path>/trade_representative_contact_information postal_code.txt
phone_number Yes <metadata_path>/trade_representative_contact_information phone_number.txt
email_address Yes <metadata_path>/trade_representative_contact_information email_address.txt
is_displayed_on_app_store Yes <metadata_path>/trade_representative_contact_information is_displayed_on_app_store.txt

Review Information Metadata

Key Editable While Live Directory Filename
first_name Yes <metadata_path>/review_information first_name.txt
last_name Yes <metadata_path>/review_information last_name.txt
phone_number Yes <metadata_path>/review_information phone_number.txt
email_address Yes <metadata_path>/review_information email_address.txt
demo_user Yes <metadata_path>/review_information demo_user.txt
demo_password Yes <metadata_path>/review_information demo_password.txt
notes Yes <metadata_path>/review_information notes.txt

Reference

View all available categories, languages, etc.

Available Categories

You can always prefix the category using MZGenre. (e.g. MZGenre.Book). deliver supports both notations.

  • Book
  • Business
  • Apps.Catalogs
  • Education
  • Entertainment
  • Finance
  • Apps.Food_Drink
  • Games
  • Healthcare_Fitness
  • Lifestyle
  • Medical
  • Music
  • Navigation
  • News
  • Apps.Newsstand
  • Photography
  • Productivity
  • Reference
  • Apps.Shopping
  • SocialNetworking
  • Sports
  • Stickers
  • Travel
  • Utilities
  • Weather

Available Game Subcategories

  • MZGenre.Action
  • MZGenre.Adventure
  • MZGenre.Arcade
  • MZGenre.Board
  • MZGenre.Card
  • MZGenre.Casino
  • MZGenre.Dice
  • MZGenre.Educational
  • MZGenre.Family
  • MZGenre.Music
  • MZGenre.Puzzle
  • MZGenre.Racing
  • MZGenre.RolePlaying
  • MZGenre.Simulation
  • MZGenre.Sports
  • MZGenre.Strategy
  • MZGenre.Trivia
  • MZGenre.Word

Available Magazines & Newspapers Subcategories

  • MZGenre.Apps.Arts_Photography
  • MZGenre.Apps.Automotive
  • MZGenre.Apps.Brides_Weddings
  • MZGenre.Apps.Business_Investing
  • MZGenre.Apps.Childrens_Magazines
  • MZGenre.Apps.Computers_Internet
  • MZGenre.Apps.Cooking_Food_Drink
  • MZGenre.Apps.Crafts_Hobbies
  • MZGenre.Apps.Electronics_Audio
  • MZGenre.Apps.Entertainment
  • MZGenre.Apps.Fashion_Style
  • MZGenre.Apps.Health_Mind_Body
  • MZGenre.Apps.History
  • MZGenre.Apps.Home_Garden
  • MZGenre.Apps.Literary_Magazines_Journals
  • MZGenre.Apps.Mens_Interest
  • MZGenre.Apps.Movies_Music
  • MZGenre.Apps.News_Politics
  • MZGenre.Apps.Outdoors_Nature
  • MZGenre.Apps.Parenting_Family
  • MZGenre.Apps.Pets
  • MZGenre.Apps.Professional_Trade
  • MZGenre.Apps.Regional_News
  • MZGenre.Apps.Science
  • MZGenre.Apps.Sports_Leisure
  • MZGenre.Apps.Teens
  • MZGenre.Apps.Travel_Regional
  • MZGenre.Apps.Womens_Interest

Available Stickers Subcategories

  • MZGenre.Apps.Stickers.Animals
  • MZGenre.Apps.Stickers.Art
  • MZGenre.Apps.Stickers.BirthdaysAndCelebrations
  • MZGenre.Apps.Stickers.Celebrities
  • MZGenre.Apps.Stickers.Characters
  • MZGenre.Apps.Stickers.FoodAndDrink
  • MZGenre.Apps.Stickers.Emotions
  • MZGenre.Apps.Stickers.Fashion
  • MZGenre.Apps.Stickers.Games
  • MZGenre.Apps.Stickers.KidsAndFamily
  • MZGenre.Apps.Stickers.MoviesAndTV
  • MZGenre.Apps.Stickers.Music
  • MZGenre.Apps.Stickers.People
  • MZGenre.Apps.Stickers.Places
  • MZGenre.Apps.Stickers.Sports

Available Languages

  • da
  • de-DE
  • el
  • en-AU
  • en-CA
  • en-GB
  • en-US
  • es-ES
  • es-MX
  • fi
  • fr-CA
  • fr-FR
  • id
  • it
  • ja
  • ko
  • ms
  • nl-NL
  • no
  • pt-BR
  • pt-PT
  • ru
  • sv
  • th
  • tr
  • vi
  • zh-Hans
  • zh-Hant

Available age rating groups

Non Boolean

Values

  • 0: None
  • 1: Infrequent/Mild
  • 2: Frequent/Intense

Keys

  • CARTOON_FANTASY_VIOLENCE
  • REALISTIC_VIOLENCE
  • PROLONGED_GRAPHIC_SADISTIC_REALISTIC_VIOLENCE
  • PROFANITY_CRUDE_HUMOR
  • MATURE_SUGGESTIVE
  • HORROR
  • MEDICAL_TREATMENT_INFO
  • ALCOHOL_TOBACCO_DRUGS
  • GAMBLING
  • SEXUAL_CONTENT_NUDITY
  • GRAPHIC_SEXUAL_CONTENT_NUDITY

Boolean

Keys

  • UNRESTRICTED_WEB_ACCESS
  • GAMBLING_CONTESTS


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

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:

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.


deliver
Supported platforms ios, mac
Author @KrauseFx

3 Examples

upload_to_app_store(
  force: true, # Set to true to skip PDF verification
  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

Key Description Default
username Your Apple ID Username *
app_identifier The bundle identifier of your app *
app The app ID of the app you want to use/modify
edit_live Modify live metadata, this option disables ipa upload and screenshot upload false
ipa Path to your ipa file *
pkg Path to your pkg file *
platform The platform to use (optional) ios
metadata_path Path to the folder containing the metadata files
screenshots_path Path to the folder containing the screenshots
skip_binary_upload Skip uploading an ipa or pkg to App Store Connect false
use_live_version Force usage of live version rather than edit version false
skip_screenshots Don't upload the screenshots false
app_version The version that should be edited or created
skip_metadata Don't upload the metadata (e.g. title, description). This will still upload screenshots false
skip_app_version_update Don't update app version for submission false
force Skip the HTML report file verification false
submit_for_review Submit the new version for Review after uploading everything false
reject_if_possible Rejects the previously submitted build if it's in a state where it's possible false
automatic_release Should the app be automatically released once it's approved? false
auto_release_date Date in milliseconds for automatically releasing on pending approval
phased_release Enable the phased release feature of iTC false
price_tier The price tier of this application
build_number If set the given build number (already uploaded to iTC) will be used instead of the current built one
app_rating_config_path Path to the app rating's config
submission_information Extra information for the submission (e.g. third party content)
team_id The ID of your App Store Connect team if you're in multiple teams *
team_name The name of your App Store Connect team if you're in multiple teams *
dev_portal_team_id The short ID of your Developer Portal team, if you're in multiple teams. Different from your iTC team ID! *
dev_portal_team_name The name of your Developer Portal team if you're in multiple teams *
itc_provider The provider short name to be used with the iTMSTransporter to identify your team. To get provider short name run pathToXcode.app/Contents/Applications/Application\ Loader.app/Contents/itms/bin/iTMSTransporter -m provider -u 'USERNAME' -p 'PASSWORD' -account_type itunes_connect -v off. The short names of providers should be listed in the second column
overwrite_screenshots Clear all previously uploaded screenshots before uploading the new ones false
run_precheck_before_submit Run precheck before submitting to app review true
precheck_default_rule_level The default rule level unless otherwise configured :warn
app_icon Metadata: The path to the app icon
apple_watch_app_icon Metadata: The path to the Apple Watch app icon
copyright Metadata: The copyright notice
primary_category Metadata: The english name of the primary category (e.g. Business, Books)
secondary_category Metadata: The english name of the secondary category (e.g. Business, Books)
primary_first_sub_category Metadata: The english name of the primary first sub category (e.g. Educational, Puzzle)
primary_second_sub_category Metadata: The english name of the primary second sub category (e.g. Educational, Puzzle)
secondary_first_sub_category Metadata: The english name of the secondary first sub category (e.g. Educational, Puzzle)
secondary_second_sub_category Metadata: The english name of the secondary second sub category (e.g. Educational, Puzzle)
trade_representative_contact_information Metadata: A hash containing the trade representative contact information
app_review_information Metadata: A hash containing the review information
description Metadata: The localised app description
name Metadata: The localised app name
subtitle Metadata: The localised app subtitle
keywords Metadata: An array of localised keywords
promotional_text Metadata: An array of localised promotional texts
release_notes Metadata: Localised release notes for this version
privacy_url Metadata: Localised privacy url
support_url Metadata: Localised support url
marketing_url Metadata: Localised marketing url
languages Metadata: List of languages to activate
ignore_language_directory_validation Ignore errors when invalid languages are found in metadata and screeenshot directories false
precheck_include_in_app_purchases Should precheck check in-app purchases? true

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


To show the documentation in your terminal, run

fastlane action deliver

View source code


Back to actions