Disparate Matters

Release A Flutter-built iOS App To TestFlight In 47 Simple Steps

As of: 11/25/2023

These are the steps I took to release my aforementioned Flutter-built app to TestFlight in the Apple App Store. Where I thought it would be helpful for others, I've included notes identifying obstacles I had to get around in order to proceed. If you attempt to follow these steps and something has changed since I published this post, please do reach out (via the link at the bottom of the page) and let me know what you had to do differently, so I can update my instructions accordingly.

First, a couple of preliminary notes. Use Safari for all browser steps. I used Android Studio for my Flutter development but you can use Visual Studio Code, which also has Flutter/Dart extensions. And, most critically, you MUST have a Mac, capable of running XCode, to ship iOS apps.

OK, buckle up!

Enrolled in Apple Developer Program:

  1. Opened browser, navigated to: https://developer.apple.com/programs/enroll/
  2. Pressed "Start Your Enrollment"
    NOTE: If you are signed in with an Apple ID already, it will be assumed you want to use that for your Apple Developer Account. If you want to use/create a different account or if you're not signed in with an Apple ID, follow the relevant path Apple will take you through.
  3. Clicked "Continue enrollment on the web"
  4. On "Confirm your personal information" form, entered my name, address, and phone number and pressed "Continue"
  5. On "Select your entity type" form, for "I develop apps as" selected "Company/Organization" and pressed "Continue"
  6. On "Tell us about your organization" form, entered my company name and D-U-N-S Number, and the CAPTCHA letters, and pressed "Continue"
    NOTE: I kept receiving an error stating "The information you entered did not match your D&B profile. Before submitting your information, look up your D&B profile." even after I used the "look up" link Apple provided in the error message to have them email what they thought my D-U-N-S Number should be (it matched what I'd been given prior by D&B themselves!). I submitted a help request, describing the problem in detail and then had an incremental back-and-forth, with various service reps at Apple, until the issue was resolved and I could proceed:
    1. First Apple told me I needed to contact D&B to have them update their records, which could take a couple of days, so I did that.
    2. Then I received an email, from Apple support, containing a deeplink which took me back into the account creation flow and prompted me for the following information, which I supplied:
      1. Company Email Address
      2. My Work Email Address
      3. Legal Entity Name
      4. Legal Entity Address
    3. Then I received an email, from Apple support, informing me I needed to supply one from a list of documents related to the formation of my company, and containing a deeplink which took me back into the account creation flow and prompted me to upload the requested documentation; I uploaded my LLC's Articles of Organization and latest Periodic Report
    4. I then received an email, from Apple support, informing me that, in order to proceed with my developer account creation process, I needed to speak with someone by phone. They supplied me with yet another deeplink to submit a request to be called back. When the guy from Apple called, he was very friendly and merely had to have me orally state that I was able to legally represent my company and sign legal documents on its behalf.
    5. I received a final email, from Apple support, stating that my enrollment request had been accepted and that I needed to review the Program License Agreement, with a deeplink to do so.
  7. I accepted the Program License Agreement
  8. I paid $99 for an annual developer license
    NOTE: Though it said I might have to wait up to 48 hours for them to process my credit card payment it went through in about 12. :)

Created Bundle ID:

  1. Opened browser, navigated to: https://developer.apple.com/account and signed in with Apple Developer Account credentials
  2. Under Certificates, IDs, & Profiles, clicked "Identifiers" (which routed me to: https://developer.apple.com/account/resources/identifiers/list)
  3. Pushed "Register an App ID" (which routed me to: https://developer.apple.com/account/resources/identifiers/add/bundleId)
  4. Selected App IDs, pushed "Continue"
  5. Under "Select a type", selected "App", pushed "Continue "(which routed me to: https://developer.apple.com/account/resources/identifiers/bundleId/add/bundle)
  6. On Register an App ID page:
    1. Entered Description
    2. For Bundle ID, selected "Explicit" and entered: [reverse domain].[app name]
    3. I didn't select any of the Capabilities or App Services as my app uses none of them
    4. Pressed "Continue"
    5. Confirmed the details and pressed "Register" to register the Bundle ID

Defined App in App Store Connect:

  1. With Safari browser, navigated to: https://appstoreconnect.apple.com and signed in with Apple Developer Account credentials
  2. Accepted TOS
  3. Clicked "+" in the top-left corner of the page, next to "Apps", and selected "New App"
  4. Under "Platforms", selected "iOS"
  5. Entered app name in "Name" field
    NOTE: If the name you want to use is taken (you won't be told this is the case until you click the "Create" button), save yourself some frustration by searching in the App Store to find a suitable alternative rather than guessing-and-checking repeatedly!
  6. For "Primary Language", selected "English (U.S.)"
  7. Selected "Bundle ID" created in step #14 (above), via dropdown
    NOTE: If nothing is in dropdown you need to return to step #9 (above).
  8. For "SKU", entered an identifier I'll recognize on an invoice
  9. For "User Access", selected "Full Access"
  10. Pressed "Create"

Reviewed Xcode Project Settings:

  1. Opened the default Xcode workspace in the project, in a terminal window, from the Flutter project directory:
    $ open ios/Runner.xcworkspace
  2. Selected the Runner target in the Xcode navigator
  3. Verified the most important settings:
    1. On the General tab:
      1. In the Supported Destinations section:
        Confirmed iPhone, iPad and Mac (Designed for iPad) are present
      2. In the Minimum Deployments section:
        Left iOS set to: 11.0
        NOTE: If you changed this, you need to open ios/Flutter/AppframeworkInfo.plist in your Flutter app and update the MinimumOSVersion value to match.
      3. In the Identity section:
        1. Selected App Category
        2. Entered Display Name
        3. Set Bundle Identifier to match step #14 (above)
        4. Set Version: 1.0.0
        5. Set Build: 1
      4. In the Deployment Info section:
        Confirmed these were set as-follows:
        1. iPhone Orientation: Portrait, Landscape Left, Landscape Right
        2. Orientation: Portrait, Upside Down, Landscape Left, Landscape Right
        3. Status Bar Style: Default
    2. On the Signing & Capabilities tab:
      1. Confirmed "Automatically manage signing" checked
      2. For Team, selected "Add Account", was prompted to sign in with Apple Id associated with my registered Apple Developer account, which then populated the Team field and allowed me to enter Bundle Identifier matching step #14 (above)

Added An App Icon:

  1. Used https://imageresizer.com/ to resize the .png file, from vector set I purchased, to 1024x1024, per Apple standards
  2. In the Xcode project navigator, in the Runner folder, selected Assets
  3. Double-clicked on default Flutter icon ("AppIcon", selected my custom .png icon (from step #28, above)
    NOTE: App icons must be in .png format (per: https://developer.apple.com/design/human-interface-guidelines/app-icons#App-icon-attributes)
  4. Renamed "AppIcon" in Xcode to literal filename of that in step #30 (above), minus the .png suffix
  5. Verified the default Flutter icon had been replaced by my custom icon, by re-running the app in Android Studio:
    $ flutter run

Added a Launch Screen:

  1. In the Xcode project navigator, in the Runner folder, selected LaunchScreen, which displayed View Controller Scene
    NOTE: Per https://docs.flutter.dev/platform-integration/ios/launch-screen, this should generally be defined as an empty screen with the background color of your app's first screen.
  2. Set background color:
    1. Expanded View Controller Scene >> View Controller and clicked on View
    2. From Xcode app menu, select View >> Inspectors >> Attributes to open right-side properties pane
    3. In Background property, selected "Custom" and then used eye dropper color sampler to pull background color from app running in Flutter iOS Simulator
      NOTE: I am CERTAIN there is a simpler way to do this. :)

Registered a (Suitable?) iOS Device For Cert Signing:

  1. Connected an iPhone to Mac/my development machine via cable, unlocked it, and told it to trust Mac
  2. In Xcode, selected the Runner target in the Xcode navigator:
    1. On the Signing & Capabilities tab:
      In the iOS section, pressed "Register Device"
    2. Confirmed the phone is visible under Certificates, Identifiers & Profiles >> Devices

Created an Xcode Build Archive and App Store App Bundle:

  1. Confirmed the app's (Flutter) build and version numbers are set as desired in Android Studio:
    In pubspec.yaml, found "version" and confirmed it looked good (i.e., was already set to "1.0.0+1")
  2. Created an app bundle:
    $ flutter build ipa --obfuscate --split-debug-info=v1.1.0+1
  3. When prompted with "codesign wants to access key "Apple Development: [my name] ([company name])" in your keychain.", I entered my MacMini user password and pressed "Always Allow"
  4. After process completed with message stating "Xcode archive done.", I confirmed the existence of:
    1. An Xcode build archive (.xcarchive file) in the project's "build/ios/archive/" directory
    2. An App Store app bundle (.ipa file) in the project's "build/ios/ipa" directory

Uploaded App Bundle To App Store Connect:

  1. Installed and opened the Apple Transport macOS app (https://apps.apple.com/us/app/transporter/id1450874784)
  2. From the Mac Finder, dragged-and-dropped the app bundle (.ipa file), from the project's "build/ios/ipa" directory, into the Apple Transport app.
  3. Status updated to "Active"
  4. Pressed "Deliver"
  5. Watched detailed log which concluded with "UPLOAD SUCCEEDED" message
  6. In App Store Connect, navigated to the TestFlight tab, confirmed app is now visible under section heading "Version 1.0.0"

Released App On TestFlight:

  1. Still on the TestFlight tab, of the app's application details page, on App Store Connect:
    1. Under "General Information", clicked on Test Information (showing warning icon w/test explanation that I needed to complete test information to submit a build for external testing)
      1. Wrote up Beta App Description text
      2. Defined Feedback Email
      3. In the Beta App Review Information section, entered my contact information (name, phone number, and email address)
      4. Pressed "Save"
    2. Under "Builds" >> iOS >> Version 1.0.0, Build 1 showed Missing Compliance:
      1. Clicked on "Manage"
      2. Prompted for Export Compliance Information
      3. Selected "None"
      4. Pressed "Save"
    3. Observed that Status changed to "Ready To Submit"
    4. Clicked on "1" under Build column
      On 1.0.0 (1) page, under Test Information:
      1. Wrote up Test Details text
      2. Clicked "+" next to Individual Testers
      3. Selected "Add New Testers"
      4. Entered individual testers' email addresses and names into modal
      5. Pressed "Next"
      6. On Test Information modal, unchecked "Sign-in required" and pressed "Next"
      7. On What to Test modal, left "Automatically notify testers" checked and testing guidance text as-is, and pressed "Submit for Review"
    5. Observed that Status changed to "Waiting for Review"

Whew! Still with me?! Because my testers are not internal, as defined by Apple (meaning they do not have Apple Developer Accounts tied to my business [account]), I needed to set them up as external testers, which necessitates a (minimal) app review by Apple, before testing can commence. So, having completed the steps listed above, I sat back and waited. I had done this during the weekend, so it was not surprising that it took until Monday for approval to come through. I received an email notifying me that my app had been approved at the same time that my testers received individual emails inviting them to install the app via TestFlight.

All Posts