Releasing to the Apple App Store

This guide walks through releasing a Code Push app to the Apple App Store and applying a patch to that release.

The app used in this guide is Shorebird Clock, a demo Code Push app. (source)

Prerequisites

To follow along with this guide, you will need the following:

1. An existing Shorebird app. If you don’t have one, you can create one by following the Code Push quickstart guide.
2. Access to hardware running macOS. This is required to build iOS apps.
3. A valid Apple Developer account. This is required to release iOS apps.
4. An app in App Store Connect. See the official documentation for more information about how to create one.
5. An iOS Distribution certificate. You can create one at https://developer.apple.com/account/resources/certificates/add.
6. An iOS App Store provisioning profile. See the official documentation for instructions on how to create one.

Specify a development team in Xcode

To build an iOS app for distribution, a development team needs to be specified in Xcode. Open ios/Runner.xcworkspace in Xcode and select the Runner target:

Creating a release

Determine the release version

Navigate to your app on the Shorebird console to see the current set of releases. For this example app, the latest release version is 1.0.3+1, so the version of the next release will be 1.0.4+1.

Create a release in App Store Connect

Because the App Store does not include the build number (the +1 part of 1.0.4+1) in app versions, this will show up in the App Store as 1.0.4. Follow the instructions in the official documentation to create a new version in App Store Connect.

Update the version in pubspec.yaml

Update the version in pubspec.yaml to 1.0.4+1:

 name: shorebird_clock
 description: A demo app for Shorebird
- version: 1.0.3+1
+ version: 1.0.4+1

Create a Shorebird release

Create a Shorebird release by running the shorebird release ios command:

$ shorebird release ios
✓ Fetching apps (0.1s)
✓ Building release (56.2s)
✓ Getting release version (37ms)
✓ Fetching releases (0.1s)
🚀 Ready to create a new release!
📱 App: time_shift (f2184ee6-9a85-498c-bfeb-114d638c462e)
📦 Release Version: 1.0.4+1
🕹️ Platform: ios

Would you like to continue? (y/N) Yes
✓ Fetching Flutter revision (36ms)
✓ Creating release (0.2s)
✓ Creating artifacts (8.0s)
✓ Updating release status (57ms)

✅ Published Release!

Your next step is to upload your app to App Store Connect.

To upload to the App Store, do one of the following:
    1. Open build/ios/archive/Runner.xcarchive in Xcode and use the "Distribute App" flow.
    2. Drag and drop the build/ios/ipa/time_shift.ipa bundle into the Apple Transporter macOS app (https://apps.apple.com/us/app/transporter/id1450874784).
    3. Run xcrun altool --upload-app --type ios -f build/ios/ipa/time_shift.ipa --apiKey your_api_key --apiIssuer your_issuer_id.
       See "man altool" for details about how to authenticate with the App Store Connect API key.

Note

If you perform your own code signing and do not want Shorebird to codesign your app, you can pass the --no-codesign flag to the shorebird release ios command. Because only signed code can be run on iOS devices, releases created this way will not be previewable using the shorebird preview command. You can still download and run these releases through TestFlight.

Note

Shorebird uses the Release configuration to package your app. If you need to provide custom settings for archiving your app (e.g., provisioning profiles), you can do this by providing an exportOptions.plist file to the release command using the --export-options-plist flag.

To view a list of settings that can be controlled by an exportOptions.plist, run xcodebuild --help and look under the Available keys for -exportOptionsPlist heading.

Upload to the App Store

Open the .xcarchive in Xcode and use the “Distribute App” flow:

As of Xcode 15, you will make the following choices:

1. “Custom” as the distribution method.

   

2. “App Store Connect” as the distribution method.

   

3. “Upload” as the destination.

   

4. A few distribution options that are up to you. Importantly, Manage Version and Build Number must be unchecked for Shorebird to work.

   If Xcode is allowed to manage the version and build number, it will automatically increment the build number during upload (e.g. from 1.0.4+1 to 1.0.4+2). Since Shorebird’s release was created targeting 1.0.4+1, this mismatch in binary metadata prevents the client updater from finding or applying patches.

   

5. Automatically manage signing or manually manage signing. This is up to you. If you choose to manually manage signing, you will need to select the appropriate development team, provisioning profile, and signing certificate for your app.

6. Confirm the upload.

Xcode will upload your archive, and if no issues are found, will show a message telling you that the upload was successful:

After a short delay (usually a minute or two), you will see the build listed as “Processing” in App Store Connect:

Once the app has finished processing, it can be added to the release:

Submit the app for review

When you attempt to submit the app for review, App Store Connect will list the issues that need to be resolved before the app can be submitted:

After the release is approved

Once the release has been approved, you will be able to download it from the App Store.

Creating a patch

Patches can be pushed to fix bugs in the App Store release without requiring a new submission to the App Store.

Make code changes

For the purposes of this guide, the default clock face will be changed to generative in lib/main.dart:

     (clock) => clock.name == clockName,
-    orElse: () => ClockFace.particle,
+    orElse: () => ClockFace.generative,
   );

Create a Shorebird patch

To make this patch available to your users, run shorebird patch ios.

$ shorebird patch ios
✓ Fetching apps (0.4s)
✓ Building release (61.5s)
✓ Detected release version 1.0.4+1 (44ms)
✓ Fetching releases (0.1s)
✓ Fetching Flutter revision (23ms)

🚀 Ready to publish a new patch!

📱 App: time_shift (f2184ee6-9a85-498c-bfeb-114d638c462e)
📦 Release Version: 1.0.4+1
📺 Channel: stable
🕹️ Platform: ios [aarch64 (4.17 MB)]

Would you like to continue? (y/N) Yes
✓ Creating patch (72ms)
✓ Uploading artifacts (0.5s)
✓ Fetching channels (58ms)
✓ Promoting patch to stable (61ms)

✅ Published Patch!