|
| 1 | +--- |
| 2 | +title: Publishing to the App Store |
| 3 | +--- |
| 4 | + |
| 5 | +import useBaseUrl from '@docusaurus/useBaseUrl'; |
| 6 | + |
| 7 | +At this point, you've at least made some minor adjustments to the Lexicon Mobile App, and are ready to publish it so that your users can download it. |
| 8 | + |
| 9 | +In this page, we'll cover the process of publishing it on iOS. |
| 10 | + |
| 11 | +## Prerequisites |
| 12 | + |
| 13 | +- An Apple Developer account |
| 14 | +- An Expo account |
| 15 | +- XCode is installed on your development machine |
| 16 | +- EAS CLI 2.6.0 or newer |
| 17 | +- The [Lexicon Discourse plugin](./discourse-plugin.md) is already installed on your Discourse instance |
| 18 | + |
| 19 | +To get started with TestFlight and publishing your app, you'll need an **Apple Developer account**. |
| 20 | + |
| 21 | +This will enable you to interact with Apple as you go through the process of submitting to TestFlight and, eventually, the App Store. |
| 22 | + |
| 23 | +You'll also need an [Expo account](https://expo.dev/signup) so you can build your app, download it, and upload it to Apple's servers. |
| 24 | + |
| 25 | +Finally, you'll want to have already downloaded and installed [Xcode](https://developer.apple.com/xcode/), which is what you'll use to upload your built app to Apple's servers. |
| 26 | + |
| 27 | +:::note |
| 28 | +If you don't yet have an account with Apple, you'll need to enroll in the [Apple Developer Program](https://developer.apple.com/programs/enroll/) first. Note that there is an annual cost associated with this. |
| 29 | + |
| 30 | +Additionally, you'll want to make sure you have an account with [Expo](https://expo.dev/signup) so you can use features like [EAS Submit](https://docs.expo.dev/submit/introduction/). |
| 31 | +::: |
| 32 | + |
| 33 | +## Register a new Bundle ID |
| 34 | + |
| 35 | +Each app in Apple's App Store has a unique **Bundle Identifier**, or Bundle ID. |
| 36 | + |
| 37 | +In order to publish the app anywhere, including to TestFlight, you'll need to have a Bundle ID registered for your app with Apple. |
| 38 | + |
| 39 | +Typically, this uses the format of `com.<yourcompany>.<yourappname>`. |
| 40 | + |
| 41 | +For example, if your company is named Expo, and your app is named Expo Go, your Bundle ID could be: |
| 42 | + |
| 43 | +``` |
| 44 | +com.expo.expogo |
| 45 | +``` |
| 46 | + |
| 47 | +You can follow these instructions to get one. |
| 48 | + |
| 49 | +- Go to [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/bundleId/add/bundle). |
| 50 | +- Fill in the following fields, and then click `Continue` |
| 51 | + <img alt="Regsiter App" width="900" src={useBaseUrl('/img/guides/testFlight/register-app-id.png')}/> |
| 52 | + |
| 53 | + - **Description**: You can insert the app name as its description. |
| 54 | + |
| 55 | + - **Bundle ID**: Select `Explicit`, and then insert then insert your bundle ID in the input field. |
| 56 | + |
| 57 | +- Capabilities |
| 58 | + |
| 59 | + - You can leave this section empty. |
| 60 | + |
| 61 | +## Add a New App in App Store Connect |
| 62 | + |
| 63 | +Steps: |
| 64 | + |
| 65 | +- Sign in to your [App Store Connect](https://appstoreconnect.apple.com/) account. |
| 66 | +- Click on `My Apps`. |
| 67 | + <img alt="App Connect" width="900" src={useBaseUrl('/img/guides/testFlight/app-connect.png')}/> |
| 68 | +- Click on the `+` button to add new app. |
| 69 | + <img alt="Add New App" width="900" src={useBaseUrl('/img/guides/testFlight/add-app.png')}/> |
| 70 | +- Fill out the requested information about your app, and then click `Create`. |
| 71 | + <img alt="Add New App" width="900" src={useBaseUrl('/img/guides/testFlight/new-app.png')}/> |
| 72 | + |
| 73 | + - **Platforms**: Select `iOS`. |
| 74 | + - **Name**: The name of your app, as it will appear on the App Store and user's devices. |
| 75 | + - **Primary Language**: The primary language that will be used if localized app information is not available. |
| 76 | + - **Bundle ID**: Choose the Bundle ID you created above. |
| 77 | + - **Note**: double-check that it's correct, because you can not change it afterwards. |
| 78 | + - **SKU (Stock Keeping Unit)**: A unique ID to differentiate your app from the others, similar to a product ID. |
| 79 | + - **User Access**: Full access means all users will have access to the app, while limited access means that the app can only be accessed by certain roles defined within App Store Connect. |
| 80 | + |
| 81 | +## Configuration |
| 82 | + |
| 83 | +After creating the app in App Store Connect, you'll want to jump back over to the codebase and make some adjustments. |
| 84 | + |
| 85 | +### Build Config |
| 86 | + |
| 87 | +:::note |
| 88 | +If you haven't yet installed the EAS CLI, follow the instructions in the [tutorial](tutorial/setup#install-the-eas-cli). |
| 89 | +::: |
| 90 | + |
| 91 | +First, you'll need to ensure you've set your app name and slug in `frontend/app.json`. The [slug](https://docs.expo.dev/workflow/glossary-of-terms/#slug) is used as part of the URL for your app on Expo's web services, so it is recommended to use kebab-case (e.g., `my-lexicon-app`). |
| 92 | + |
| 93 | +Replace these placeholders with your desired values: |
| 94 | + |
| 95 | +:::info |
| 96 | +Note below that `scheme` is included. If you want [email deep linking](./email-deep-linking/intro.md) support in your app, **you must specify a scheme**, and then configure the Lexicon Discourse plugin with the same scheme. |
| 97 | +::: |
| 98 | + |
| 99 | +```json |
| 100 | +"name": "<your app name>", |
| 101 | +"slug": "<your app slug>", |
| 102 | +"scheme": "<your app scheme>", |
| 103 | +``` |
| 104 | + |
| 105 | +Next, configure EAS Build by running this command from the `frontend/` directory: |
| 106 | + |
| 107 | +```bash |
| 108 | +eas build:configure |
| 109 | +``` |
| 110 | + |
| 111 | +The EAS CLI will prompt you to specify `android.package` and `ios.bundleIdentifier` if those values are not already provided in `app.json`. You'll want to add the bundle ID you just registered in App Store Connect as the `bundleIdentifier`. |
| 112 | + |
| 113 | +Then you can see that the value has been updated in the `ios` section of `frontend/app.json` file. |
| 114 | + |
| 115 | +```json |
| 116 | + "ios": { |
| 117 | + "supportsTablet": false, |
| 118 | + "buildNumber": "1.0.0", |
| 119 | + "bundleIdentifier": "<your bundle ID>", |
| 120 | + "config": { |
| 121 | + "usesNonExemptEncryption" : false |
| 122 | + } |
| 123 | + }, |
| 124 | +``` |
| 125 | + |
| 126 | +:::note |
| 127 | +We set `usesNonExemptEncryption` to `false` because Lexicon doesn't leverage that feature. |
| 128 | + |
| 129 | +For further details, please take a look at [this link](https://developer.apple.com/documentation/bundleresources/information_property_list/itsappusesnonexemptencryption) from Apple's documentation. |
| 130 | +::: |
| 131 | + |
| 132 | +### Setup Config Values |
| 133 | + |
| 134 | +:::info |
| 135 | +When publishing your app, you must deploy your Discourse server to a publicly accessible location. Refer to the [documentation](tutorial/setup-discourse.md#setup-discourse-in-the-cloud) for guidance on deploying Discourse if you haven't done so already. |
| 136 | +::: |
| 137 | + |
| 138 | +Next, configure the **Discourse URL** for your build in `Config.ts`. You can set a different URL for each build channel. |
| 139 | + |
| 140 | +:::note |
| 141 | +In the initial release of Lexicon, connecting to a Discourse site required setting up Prose and configuring the Prose URL in the mobile app. However, with recent updates, the mobile app now connects directly to Discourse without needing Prose. |
| 142 | +::: |
| 143 | + |
| 144 | +```ts |
| 145 | +const config = { |
| 146 | + // ... |
| 147 | + buildChannels: { |
| 148 | + preview: { |
| 149 | + discourseUrl: 'http://PLACEHOLDER.change.this.to.your.discourse.url', |
| 150 | + }, |
| 151 | + production: { |
| 152 | + discourseUrl: 'http://PLACEHOLDER.change.this.to.your.discourse.url', |
| 153 | + }, |
| 154 | + }, |
| 155 | +}; |
| 156 | +``` |
| 157 | + |
| 158 | +### Setup Apple Dveloper Account |
| 159 | + |
| 160 | +Lastly, please adjust these fields in `eas.json` with your account information to submit the app: |
| 161 | + |
| 162 | +```json |
| 163 | + "base": { |
| 164 | + "ios": { |
| 165 | + "appleId": "<your apple ID>", |
| 166 | + "ascAppId": "<your App Store connect ID>", |
| 167 | + "appleTeamId": "<your apple team ID>" |
| 168 | + }, |
| 169 | + ... |
| 170 | + }, |
| 171 | +``` |
| 172 | + |
| 173 | +- **appleId**: your apple ID (e.g., `john@gmail.com`). |
| 174 | +- **ascAppId**: your App Store Connect app ID. Find your ascAppID by following [this guide](https://github.com/expo/fyi/blob/main/asc-app-id.md) (e.g., `1234567890`). |
| 175 | +- **appleTeamId**: You can check your apple team ID [here](https://developer.apple.com/account/) (e.g., `12LE34XI45`). |
| 176 | + |
| 177 | +## Build your App for iOS |
| 178 | + |
| 179 | +Before publishing, you'll need to build your app by instructing Expo to generate an iOS build. |
| 180 | + |
| 181 | +It is recommended to build your app with the `preview` profile before releasing to verify that it works as expected. See [this tutorial](tutorial/building) to learn more about build profiles. |
| 182 | + |
| 183 | +Run this command: |
| 184 | + |
| 185 | +```bash |
| 186 | +eas build --platform ios --profile preview |
| 187 | +``` |
| 188 | + |
| 189 | +When you run the above command, Expo will prompt you for your Apple ID and password. |
| 190 | + |
| 191 | +Once the above step has been completed, login to your account on [Expo](https://expo.dev) and download your newly built app. |
| 192 | + |
| 193 | +Navigate to your project in the [Expo web console](https://expo.dev), then click on the **Builds** menu located on the left-hand side of the screen. |
| 194 | + |
| 195 | +- Click on the project you want to install. |
| 196 | + <img alt="Builds" width="900" src={useBaseUrl('/img/guides/testFlight/builds.png')}/> |
| 197 | + |
| 198 | +- Download the iOS build by pressing the `Download` button in the `Build Artifact` section. |
| 199 | + <img alt="Build Artifact" width="900" src={useBaseUrl('/img/guides/testFlight/build-artifact.png')}/> |
| 200 | + |
| 201 | +This will download a tar file containing your app. Extract the file, then drag it to your simulator to install it. See [this section](tutorial/building#1-preview) of the tutorial to learn about running the app on real devices. |
| 202 | + |
| 203 | +Once you have verified that the app runs as expected, you can proceed to build it for release: |
| 204 | + |
| 205 | +```bash |
| 206 | +eas build --platform ios --profile production |
| 207 | +``` |
| 208 | + |
| 209 | +The approach for a production build is similar to the one used for generating a preview build. However, unlike a preview build, you won't be able to launch the production build in the iOS simulator—it is intended solely for publishing to the App Store. |
| 210 | + |
| 211 | +Once this process is completed, you can proceed with submitting it to Apple. This process typically involves Apple's TestFlight service. |
| 212 | + |
| 213 | +## Submit to TestFlight |
| 214 | + |
| 215 | +TestFlight is a key aspect of Apple's Developer Program, which enables developers to provide beta users with access to their app under less restrictive review requirements. |
| 216 | + |
| 217 | +With TestFlight, you're able to invite users to test your app and collect their feedback before releasing it to the public on the App Store. You can learn more about TestFlight [here](https://developer.apple.com/testflight/). |
| 218 | + |
| 219 | +Submitting an iOS app is much easier with EAS Submit. This is covered in more detail in the [tutorial](tutorial/publishing). |
| 220 | + |
| 221 | +Run the following command to start publishing the app to TestFlight: |
| 222 | + |
| 223 | +```bash |
| 224 | +eas submit --platform ios --profile production |
| 225 | +``` |
| 226 | + |
| 227 | +Once the process has completed successfully, we can check the build in App Store Connect. |
| 228 | + |
| 229 | +In App Store Connect, click on the TestFlight Tab. |
| 230 | + |
| 231 | +You'll see the [status](https://help.apple.com/app-store-connect/#/dev3d6869aff) of your built version. |
| 232 | + |
| 233 | +- **Red** indicates that you need to perform some action. |
| 234 | +- **Yellow** indicates that some aspect of the process is pending—either from you, or from Apple. |
| 235 | +- **Green** indicates that the build is being tested in TestFlight, or is ready to be submitted for review. |
| 236 | + |
| 237 | +You won't be able to begin beta testing with TestFlight until an official tester from Apple verifies your app. |
| 238 | + |
| 239 | +In order to allow Apple to properly test your Lexicon-powered app, they'll need to have credentials to login your Discourse site. |
| 240 | + |
| 241 | +Before submitting your app, you'll need to create those credentials in Discourse and specify them in App Store Connect. |
| 242 | + |
| 243 | +- In App Store Connect, click on your app. |
| 244 | +- Click on TestFlight App. |
| 245 | +- Click on Test Information in the sidebar on the left-hand side. |
| 246 | +- Fill the required fields, then check the `Sign in required` checkbox, and enter the credentials. |
| 247 | + <img alt="Review Information Sign In" width="900" src={useBaseUrl('/img/guides/testFlight/review-signin.png')}/> |
| 248 | +- Please also provide information for a person to contact if the review team needs additional information. |
| 249 | + <img alt="Review Information Contact" width="900" src={useBaseUrl('/img/guides/testFlight/review-contact.png')}/> |
| 250 | + |
| 251 | +### Specify Users for Beta Testing |
| 252 | + |
| 253 | +Beta Test Users can belong to an Internal Group or an External Group. |
| 254 | + |
| 255 | +You can specify internal users by going to the Internal Group section, and clicking on **App Store Connect Users**. |
| 256 | + |
| 257 | +Similarly, you can specify external users by selecting External Groups, and clicking on **Add External Testers**. |
| 258 | + |
| 259 | +#### More Information |
| 260 | + |
| 261 | +TestFlight and App Store Connect are sophisticated tools to help with the process of submitting, testing, and publishing your app. |
| 262 | + |
| 263 | +If you have further questions or just want to learn more, we'd recommend that you make use of Apple's documentation, which is very high quality. |
| 264 | + |
| 265 | +For more information about TestFlight in general, read the [documentation](https://developer.apple.com/testflight/). |
| 266 | + |
| 267 | +Similarly, for specific information about beta testing with TestFlight, check out [Testing Apps with TestFlight](https://testflight.apple.com/). |
| 268 | + |
| 269 | +## Publish to the App Store |
| 270 | + |
| 271 | +Once you've successfully passed Apple's review process and have received enough feedback from your beta testers, you're ready to publish to the App Store and go live! :tada: |
| 272 | + |
| 273 | +As a few final reminders, double-check that... |
| 274 | + |
| 275 | +- Your Discourse instance is online, reachable, and functioning correctly. |
| 276 | +- The built version of your app is configured to point at the correct Discourse instance. |
| 277 | + |
| 278 | +Next, we'll guide you through the process of publishing your app for Android devices on the Google Play Store. |
0 commit comments