|
| 1 | +# Distributing beta builds |
| 2 | + |
| 3 | +Developers love writing React Native code but no one likes deploying React Native app or distributing beta builds. |
| 4 | + |
| 5 | +All your headaches will disappear with this documentation and the amazing [Fastlane](https://fastlane.tools/) tool :) |
| 6 | + |
| 7 | +## Before you start |
| 8 | + |
| 9 | +You need a Mac. I'm sorry, but if you are a Windows user, you can stop reading right now. |
| 10 | +Fastlane will not work on Windows PC. But in all cases, if you need to deploy your app on IOS, you must have a Mac. |
| 11 | + |
| 12 | +Let's explain which tools we are using to distribute beta builds: |
| 13 | +* [Fastlane](https://fastlane.tools/), the easiest way to automate beta deployments and releases for your iOS and Android apps. It handles all tedious tasks like generating screenshots, dealing with code signing and releasing your application. |
| 14 | +* [TestFlight](https://developer.apple.com/testflight/), part of App Store Connect, let you build your iOS app and invite internal or external users to test it |
| 15 | +* [Google Play](https://support.google.com/googleplay/android-developer/answer/3131213?hl=fr), which does the same job as TestFlight for Android apps |
| 16 | + |
| 17 | +## Installing Fastlane |
| 18 | + |
| 19 | +First you need to install Fastlane on your Mac. Follow these steps: |
| 20 | + |
| 21 | +1. Install the latest Xcode command line tools: |
| 22 | +``` |
| 23 | +xcode-select --install |
| 24 | +``` |
| 25 | +2. Install Ruby using [Homebrew](https://brew.sh/): |
| 26 | +``` |
| 27 | +brew install ruby |
| 28 | +``` |
| 29 | +3. Install Fastlane with RubyGems: |
| 30 | +``` |
| 31 | +sudo gem install fastlane -NV |
| 32 | +``` |
| 33 | + |
| 34 | + You are now ready to set up Fastlane for iOS and Android :rocket: |
| 35 | + |
| 36 | +## iOS |
| 37 | + |
| 38 | +### Prerequisites |
| 39 | + |
| 40 | +Before continuing make sure you have: |
| 41 | + |
| 42 | +- [ ] Xcode 9 or higher |
| 43 | +- [ ] Choose the [bundle identifier](https://cocoacasts.com/what-are-app-ids-and-bundle-identifiers/) of your app (for example `com.tcm.boilerplate`) |
| 44 | +- [ ] An Apple ID with an admin user, with its username (email, for example `[email protected]`) and password |
| 45 | +- [ ] Your app name, if not already created on the Developer Portal (for example `TCM React Native Boilerplate`). Fastlane can create applications in the Developer Portal and App Store Connect, so it's recommended to let Fastlane do the job for you. |
| 46 | +- [ ] Use the right [.gitignore](ios/.gitignore) file inside the `ios` directory |
| 47 | + |
| 48 | +Open your Xcode project and modify some information: |
| 49 | + |
| 50 | +- [ ] In the `General` tab, `Identity` section, change the `Bundle Identifier` to your identifier |
| 51 | +- [ ] In the `General` tab, `Signing` section, disable `Automatically manage signing` |
| 52 | +- [ ] In the `Build Settings` tab, under `Signing`, set `Don't Code Sign` as the `debug` codesigning identity and `iOS Distribution` as the `release` codesigning identity (for both `Debug`/`Release` and `Any iOS SDK`). |
| 53 | + |
| 54 | +### Setting up |
| 55 | + |
| 56 | +First you need to set up Fastlane for your iOS project: |
| 57 | +``` |
| 58 | +cd my-project/ios |
| 59 | +fastlane init |
| 60 | +``` |
| 61 | + |
| 62 | +Fastlane will automatically detect your project and ask for any missing information. |
| 63 | + |
| 64 | +The following questions will be asked: |
| 65 | +* `What would you like to use fastlane for?` |
| 66 | + * For this tutorial a good answer is `2 - Automate beta distribution to TestFlight` |
| 67 | +* `Select Scheme:` |
| 68 | + * Here we will select the scheme without `-tvOS` suffix |
| 69 | +* `Apple ID Username:` |
| 70 | + * If you don't know, you didn't read the "Prerequisites" step :) |
| 71 | + |
| 72 | +* `Password (for Apple ID Username):` |
| 73 | + * If you don't know, you didn't read the "Prerequisites" step :) |
| 74 | + Our answer is `keep it secret` |
| 75 | + |
| 76 | +At this step, you may have the following issue: |
| 77 | +``` |
| 78 | +fastlane init failed |
| 79 | +["The request could not be completed because:", "Could not receive latest API key from App Store Connect, this might be a server issue."] |
| 80 | +Something failed while running `fastlane init` |
| 81 | +Tried using Apple ID with email '[email protected]' |
| 82 | +You can either retry, or fallback to manual setup which will create a basic Fastfile |
| 83 | +Would you like to fallback to a manual Fastfile? (y/n) |
| 84 | +``` |
| 85 | +Answer `n`, and retry previous steps with a correct Apple ID and password. |
| 86 | +Make sure you are connected to internet. |
| 87 | + |
| 88 | +* If your account has multiple teams in the App Store Connect, you may have this question: `Multiple App Store Connect teams found, please enter the number of the team you want to use:` |
| 89 | + * Select the right team |
| 90 | +* If your account has multiple teams in the Developer Portal, you may have this question: `Multiple teams found on the Developer Portal, please enter the number of the team you want to use:` |
| 91 | + * Select the right team |
| 92 | +* If you havent't already created the App on the Developer Portal or App Store Connect, Fastlane can do it for you! (else you must have a message `Your app 'com.tcm.boilerplate' is available in your Apple Developer Portal / App Store Connect`) |
| 93 | + * It will ask `Do you want fastlane to create the App ID for you on the Apple Developer Portal / App Store Connect? (y/n)` |
| 94 | + * Type `y` |
| 95 | + * `App Name`: |
| 96 | + * `TCM React Native Boilerplate` |
| 97 | + |
| 98 | +Fastlane will then give you some information about git, the files it will create, etc. Just type `enter` to continue. |
| 99 | + |
| 100 | +Congrats! Fastlane has created some files. |
| 101 | +If you are using Git, commit all generated files. |
| 102 | + |
| 103 | +Once the setup has finished you can see a new folder inside the `ios` folder: |
| 104 | +``` |
| 105 | + - fastlane/ |
| 106 | + - Appfile |
| 107 | + - Fastfile |
| 108 | +``` |
| 109 | + |
| 110 | +`Appfile` contains identifiers used to connect to the Developer Portal and App Store Connect. |
| 111 | +You can read more about this file [here](https://docs.fastlane.tools/advanced/#appfile). |
| 112 | + |
| 113 | +`Fastfile` contains all actions you can launch. |
| 114 | +You can read more about this file [here](https://docs.fastlane.tools/actions). |
| 115 | +Because we previously chose `Automate beta distribution to TestFlight` on set up, a `beta` [lane](https://docs.fastlane.tools/advanced/lanes/) is available by default. |
| 116 | +This `lane` contains 3 actions: |
| 117 | +* increment the build number of your app |
| 118 | +* build your app |
| 119 | +* upload to TestFlight |
| 120 | + |
| 121 | +### Code signing |
| 122 | + |
| 123 | +Signing your app assures users that it is from a known source and the app hasn’t been modified since it was last signed. Before your app can integrate app services, be installed on a device, or be submitted to the App Store, it must be signed with a certificate issued by Apple. |
| 124 | + |
| 125 | +A full guide is available on the fastlane doc, describing the best approaches for your [code signing process](https://docs.fastlane.tools/codesigning/getting-started/). |
| 126 | + |
| 127 | +Using `match` is probably [the best solution](https://codesigning.guide/). |
| 128 | +Because we don't want to revoke our existing certificates, but still want an automated setup, we will use [cert and sigh](https://docs.fastlane.tools/codesigning/getting-started/#using-cert-and-sigh). |
| 129 | + |
| 130 | +Add the following to your `Fastfile`, just after the `increment_build_number` function and before `build_app`: |
| 131 | +``` |
| 132 | + get_certificates( # Create or get certificate, and install it |
| 133 | + output_path: "./builds" # Download certificate in the build folder (you don't need to create the folder) |
| 134 | + ) |
| 135 | + get_provisioning_profile( # Create or get provisioning profile |
| 136 | + output_path: "./builds", # Download provisioning profile in the build folder |
| 137 | + filename: "provisioning.mobileprovision" # Rename the local provisioning profile |
| 138 | + ) |
| 139 | + update_project_provisioning( # Set the project provisioning profile (related in Xcode to the General > Signing Release section) |
| 140 | + xcodeproj: "Boilerplate.xcodeproj", |
| 141 | + target_filter: "Boilerplate", # Name of your project |
| 142 | + profile: "./builds/provisioning.mobileprovision", |
| 143 | + build_configuration: "Release" |
| 144 | + ) |
| 145 | + update_project_team( # Set the right team on your project |
| 146 | + teamid: CredentialsManager::AppfileConfig.try_fetch_value(:team_id) |
| 147 | + ) |
| 148 | +``` |
| 149 | + |
| 150 | +Then, we need to configure the provisioning profile for the build step. |
| 151 | + |
| 152 | +Add the following to your `Fastfile`, inside the `build_app` function, just after the `scheme` parameter: |
| 153 | +``` |
| 154 | + clean: true, |
| 155 | + export_method: "app-store", |
| 156 | + export_options: { |
| 157 | + provisioningProfiles: { |
| 158 | + CredentialsManager::AppfileConfig.try_fetch_value(:app_identifier) => CredentialsManager::AppfileConfig.try_fetch_value(:app_identifier) + " AppStore" # Value of this parameter is the name of the Provisioning Profile. By default, it will be "{bundleId} AppStore" |
| 159 | + } |
| 160 | + }, |
| 161 | + build_path: "./builds", |
| 162 | + output_directory: "./builds" |
| 163 | +``` |
| 164 | +Make sure you have a `,` after the `scheme` parameter. |
| 165 | + |
| 166 | +Thanks to this the Certificates and Provisioning Profile will be automatically created when you will create a beta build! |
| 167 | +:rocket: You are now ready to create your first beta build. |
| 168 | + |
| 169 | + |
| 170 | +### Creating a beta build |
| 171 | + |
| 172 | +Creating a beta build and uploading it on TestFlight is now really easy. |
| 173 | +Just type the following: |
| 174 | + |
| 175 | +``` |
| 176 | +cd my-project/ios |
| 177 | +fastlane beta |
| 178 | +``` |
| 179 | + |
| 180 | + |
| 181 | +## Android |
| 182 | + |
| 183 | +### Prerequisites |
| 184 | + |
| 185 | +Before continuing make sure you have: |
| 186 | + |
| 187 | +- [ ] This thing |
| 188 | +- [ ] This thing |
| 189 | + |
| 190 | + |
| 191 | +## Troubleshooting |
| 192 | + |
| 193 | +### Stuck at `bundle install` running `fastlane init` |
| 194 | + |
| 195 | +If the `fastlane init` process is stuck when running `bundle install` it may mean that `bundle install` is asking for root permissions. |
| 196 | +You can stop the process and retry again with `sudo fastlane init`, however you will need to change back ownership of the generated files to your user when it finishes (`sudo chown <your-user> <files>`). |
0 commit comments