Skip to content

Commit

Permalink
Refine the Building, Publishing, & Updating content (#820)
Browse files Browse the repository at this point in the history 
Expand the content to focus on the concepts and point learners to the React Native docs for the “how.”
  • Loading branch information
@chasenlehara
chasenlehara authored May 28, 2024
1 parent e9ea12a commit c082281
Show file tree
Hide file tree
Showing 2 changed files with 140 additions and 86 deletions.
103 changes: 78 additions & 25 deletions src/react-native/20-building/building.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,70 +2,123 @@
@parent learn-react-native 20
@outline 3

@description Learn how to build Android App Bundles (AAB).
@description Learn how to build Android App Bundle (AAB) files.

@body

## Overview

In this section, you will:

- Create a build.
- Understand the difference between APK and AAB.
- Sign your app.
- Cover EAS production builds.
- Learn about the differences between APK and AAB files.
- Build an AAB file.

## Objective 1: Create a build and verify that the build (AAB) is generated
## Objective 1: Create an Android App Bundle (AAB)

### Creating a Build
When developing Android applications, understanding the different formats used for packaging and distributing your app is crucial.
Two primary formats you’ll encounter are the Android App Bundle (AAB) and the Android Package (APK).

To create an Android build of our React Native app, we can run the `react-native build-android --mode=release` command to generate an Android App Bundle (AAB) file. You are able to create an AAB with or without signing it. However, if you want to upload the AAB to the Google Play store, you must sign it using an upload key keystore.
Each serves distinct purposes and offers unique benefits.
Let’s dive into what these formats are and why they matter.

### APK vs AAB
### What is an APK?

An Android Package (APK) is the traditional format used to distribute and install Android apps. It is a zip file that contains all the necessary files for the app to run on an Android device. APKs can be directly installed onto devices or through app stores like Google Play. However, APKs are not optimized and contain all resources for every device configuration, leading to larger file sizes.
An Android Package (APK) is the traditional file format used to distribute and install applications on Android devices.
Essentially, an APK is a compressed archive that contains all the necessary components for an app to run, including the compiled code, resources, assets, and manifest file.
When you download an app from the Google Play Store or another source, it typically comes in the form of an APK.

On the other hand, an Android App Bundle (AAB) is a publishing format that includes all the compiled code and resources of an app, but does not create a final APK. Instead, it allows the Google Play store to generate an APK for each different device configuration: different screen densities, CPU architectures, and languages. Users cannot directly install AABs and they must be uploaded to the Google Play Store for distribution. Because the Play Store generates optimized APKs for each device, AABs are smaller in size which results in faster downloads, reduced storage space, and better performance.
Key features of an APK:

### Signing
- **Direct installation:** APK files can be installed directly onto Android devices, either through the Play Store or by sideloading.
- **Universal packaging:** An APK contains all resources and code required for every possible device configuration, such as different screen sizes, densities, and CPU architectures.
- **Larger file size:** Because it includes resources for all configurations, an APK file can be quite large and may include unnecessary data for a particular device.

Android requires that apps be signed with a certificate before they can be installed on a device. This is to ensure that the app has not been tampered with and that it is safe to run. The signing process involves generating an upload key, instructions for which can be found in the [React Native documentation](https://reactnative.dev/docs/signed-apk-android#generating-an-upload-key), and using the upload key to sign the app.
### What is an AAB?

Once the private key has been generated, you must update your Gradle variables and config before building the app using the `npx react-native build-android --mode="release"` command.
An Android App Bundle (AAB) is a more modern and efficient format introduced by Google.
Unlike an APK, an AAB is not a final package that can be installed on a device.
Instead, it contains all the compiled code and resources of an app, but in a way that allows Google Play to generate optimized APKs specifically tailored for each device configuration.

The signed AAB can be found under `android/app/build/outputs/bundle/release/app-release.aab` and can now be uploaded to the Google Play store.
Key features of an AAB:

### Getting build onto device
- **Optimized distribution:** When you upload an AAB to the Google Play Store, the Play Store automatically generates and serves optimized APKs for each user’s device. This means the downloaded app will only contain the resources needed for that specific device, resulting in smaller download sizes and improved performance.
- **Mandatory for Play Store:** Starting in 2021, Google Play requires new apps to be published using the AAB format.
- **Efficient updates:** By using AAB, incremental updates can be more efficient as only the necessary changes are downloaded, reducing the update size.

If you would like to test the release build on a device, you can run the `npm run android -- --mode="release"` command. However, this will only work if you followed the signing instructions that were mentioned earlier.
### Building an AAB

Keep in mind that when you sign an AAB locally it will change the signature of the app. The Google Sign-In API relies on the app's signature to verify the app's identity, so the newly signed app will not be able to use Google Sign-In API.
AAB files can be built by using this command provided by React Native:

### EAS Production Build
```shell
react-native build-android --mode=release
```

The AAB will be in this location:

```
android/app/build/outputs/bundle/release/app-release.aab
```

EAS, or Expo Application Services, is a service provided by Expo to help streamline the process of building and deploying React Native applications. It is a cloud-based solution that allows us to create production builds, submit them to the app stores, and manage OTA (over-the-air) updates.
You are able to create an AAB with or without signing it. However, if you want to upload the AAB to the Google Play store, you must sign it using an upload key keystore.

### Setup 1

✏️ Update **package.json** to be:

@diff ../../../exercises/react-native/19-performance/01-solution/package.json ../../../exercises/react-native/20-building/01-solution/package.json only

### Verify 1

The build logs will look something like this (but much, much longer):

```
npm run android:build
> [email protected] android:build
> react-native build-android --mode=release
info Building the app...
> Task :app:createBundleReleaseJsAndAssets
debug Reading Metro config from /Users/bitovi/PlaceMyOrder/metro.config.js
warning: the transform cache was reset.
Welcome to Metro v0.80.9
Fast - Scalable - Integrated
# Many lines later…
> Task :react-native-gesture-handler:compileReleaseKotlin
w: file:///Users/bitovi/PlaceMyOrder/node_modules/react-native-gesture-handler/android/src/main/java/com/swmansion/gesturehandler/RNGestureHandlerPackage.kt:69:42 'constructor ReactModuleInfo(String!, String!, Boolean, Boolean, Boolean, Boolean, Boolean)' is deprecated. Deprecated in Java
w: file:///Users/bitovi/PlaceMyOrder/node_modules/react-native-gesture-handler/android/src/main/java/com/swmansion/gesturehandler/core/FlingGestureHandler.kt:25:26 Parameter 'event' is never used
> Task :react-native-screens:compileReleaseJavaWithJavac
Note: /Users/bitovi/PlaceMyOrder/node_modules/react-native-screens/android/src/paper/java/com/swmansion/rnscreens/NativeScreensModuleSpec.java uses or overrides a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
BUILD SUCCESSFUL in 30s
216 actionable tasks: 211 executed, 5 up-to-date
```

@highlight 1, 24, only

### Exercise 1

✏️ Run to generate AAB file:
✏️ Run the script to generate the AAB file:

```bash
```shell
npm run android:build
```

### Solution 1

If there is a successful build, the file **android/app/build/outputs/bundle/release/app-release.aab** will be created.
After the build runs successfully, you can find the AAB in your project:

TODO: What happens if there isn’t a successful build? 😅
```
android/app/build/outputs/bundle/release/app-release.aab
```

TODO: Can the AAB be run in the emulator? If so, we should instruct them to do that.
Since the `aab` file is really a `zip` in disguise, change the filename to `app-release.zip` and open it.
What can you find?

## Next steps

Expand Down
123 changes: 62 additions & 61 deletions src/react-native/21-publishing-and-updating/publishing-and-updating.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,81 +8,82 @@

## Overview

In this section, you will:
In this section, you will learn the best practices of how to:

- Generate an upload key.
- Configure Gradle to use the upload key.
- Sign your AAB with the upload key.
- Discuss OTA vs AAB updates.
- How to test new releases.
- Set up Gradle variables.
- Add signing config to your app’s Gradle config.
- Generate the release AAB.
- Test the release build of your app.

## Objective 1: Uploading AAB to Google Play Store
## Objective 1: Publishing the application to the Google Play Store

The [React Native docs on publishing to the Google Play Store](https://reactnative.dev/docs/signed-apk-android) are great for following the steps required to meet each requirement.

In this section, we will give you a brief overview of the “what” and “why” of these steps.

### Generating an upload key

As mentioned in the previous section, if we want to upload an AAB (Android App Bundle) to the Google Play Store, we need to generate an upload key and use it to sign the AAB. The React Native documentation provides [instructions for generating an upload key](https://reactnative.dev/docs/signed-apk-android#generating-an-upload-key) for both Windows and macOS.

### Configuring Gradle

Now that we’ve generated an upload key, we need to configure Gradle to use it. First thing we will do is move the upload key keystore file to the `android/app` directory of our project. Next, we will update the `~/.gradle/gradle.properties` or `android/gradle.properties` to add the following:

```
MYAPP_UPLOAD_STORE_FILE=my-upload-key.keystore # Replace with the name of your keystore file
MYAPP_UPLOAD_KEY_ALIAS=my-key-alias # Replace with the alias you set
MYAPP_UPLOAD_STORE_PASSWORD=your-keystore-password # Replace with the keystore password you set
MYAPP_UPLOAD_KEY_PASSWORD=your-key-password # Replace with the key password you set
```

Lastly, we will upadte the `android/app/build.gradle` file to add the following:

```gradle
...
android {
...
defaultConfig { ... }
signingConfigs {
release {
if (project.hasProperty('MYAPP_UPLOAD_STORE_FILE')) {
storeFile file(MYAPP_UPLOAD_STORE_FILE)
storePassword MYAPP_UPLOAD_STORE_PASSWORD
keyAlias MYAPP_UPLOAD_KEY_ALIAS
keyPassword MYAPP_UPLOAD_KEY_PASSWORD
}
}
}
buildTypes {
release {
...
signingConfig signingConfigs.release
}
}
}
...
```

Now that we’ve generated an upload key and configured Gradle to use it, we can generate an AAB file and upload it to the Google Play Store.

Check out the [React Native Android guide](https://reactnative.dev/docs/signed-apk-android) for more information.

```bash
npx react-native build-android --mode="release"
```

## Objective 2: App updates and versioning
An upload key is essential for signing your app on Android.
It acts as a digital signature that verifies the authenticity of your app and ensures it hasn’t been tampered with.
When you generate an upload key, you create a private key used to sign your app’s Android App Bundle (AAB), maintaining the integrity and security of your app on the Google Play Store.

### Releasing updates
### Setting up Gradle variables

To use your upload key for signing your app, Gradle needs configuration.
This involves defining key properties like the keystore file location, key alias, and passwords in a `gradle.properties` file.
This file securely manages sensitive information, making it easy to reference in your Gradle build scripts.

### Adding signing config to your app’s Gradle config

With your Gradle variables set up, the next step is to add the signing configuration to your app’s `build.gradle` file.
This step involves specifying the signing configuration in the Gradle build script, linking it to the previously defined variables.
This configuration instructs Gradle to use your upload key to sign the app during the build process.

### Generating the release AAB

As we went through in the previous module, generating a release Android App Bundle (AAB) is a crucial step in preparing your app for publication.

The release AAB is a compiled version of your app, including all necessary code and resources, optimized for distribution on the Google Play Store.
The AAB format allows Google Play to generate optimized APKs for various device configurations, reducing download sizes and improving performance.

The two main ways to release updates to your app are to either upload a new AAB to the Google Play Store or to create a new OTA (over-the-air) update.
### Testing the release build of your app

OTA updates allow us to update our app without requiring the user to install a new version from the app store. OTA updates are great for quick deployment for bug fixes or small changes. However, they are limited to JavaScript changes only. The overhead of implementing an OTA process is higher than simply uploading a new AAB to the app store.
Before submitting your app to the Google Play Store, thoroughly testing the release build is essential.
This step ensures that your app performs well across different devices and configurations and that no critical bugs or issues affect the user experience.

Deploying a new AAB to the Google Play Store is more suited for updates beyond small bug fixes or changes. With a new AAB we can update native code. Users are familiar with the update process, so deploying a new AAB with a changelog can provide a better user experience when doing major updates.
Testing can be done on physical devices or using emulators to simulate different environments.
This helps identify and fix problems, verify that all features work as expected, and ensure your app meets quality standards.

Both OTA and AAB updates have their place in the app update process. It’s up to you to decide whether one or the other, or a mix of both, is best for your app.
## Objective 2: Updating and versioning the application

### Releasing updates

Releasing updates is a critical aspect of maintaining and improving your app.

Here are some best practices to follow when releasing updates:

- **Plan and document:** Before releasing an update, plan the changes and document them clearly. This includes listing bug fixes, new features, and any improvements.
- **Incremental updates:** Make updates incremental rather than large, sweeping changes. This makes it easier to manage and test each release.
- **Testing:** Thoroughly test each update before release. Use both automated tests and manual testing on various devices to ensure compatibility and performance.
- **Staged rollouts:** Consider using staged rollouts to release the update to a small percentage of users first. This allows you to catch any potential issues before the update reaches all users.
- **User communication:** Communicate with your users about the updates. Use clear and concise release notes to inform them of what has changed and any new features or fixes included in the update.
- **Monitor feedback:** After releasing an update, monitor user feedback closely. Be prepared to address any issues that arise quickly.

### Testing new releases

Both the Google Play Store and the Apple App Store allow you to test new releases before making them available to the public. This is a great way to ensure that your app is working as expected before releasing it to the public. To learn about testing new releases with the Google Play Store, check out [Internal Testing](https://play.google.com/console/about/internal-testing/). If you are releasing your app on the Apple App Store, you can use [TestFlight](https://developer.apple.com/testflight/).
Before making updates available to the public, it’s essential to test them thoroughly. Both the Google Play Store and the Apple App Store offer tools for testing new releases:

- **Google Play Store:** Use [Internal Testing](https://play.google.com/console/about/internal-testing/) to release your app to a select group of users for testing. This helps identify issues in a controlled environment before a wider release.
- **Apple App Store:** Use [TestFlight](https://developer.apple.com/testflight/) to invite users to test your app. TestFlight allows you to gather valuable feedback and ensure that your app is functioning correctly on different devices and operating systems.

### Best practices

- **Semantic versioning:** Follow semantic versioning (e.g., 1.0.0) to clearly communicate the type and impact of updates. Use major version increments for significant changes, minor version increments for new features, and patch increments for bug fixes.
- **Changelogs:** Maintain detailed changelogs for each release. This practice helps users understand what changes have been made and provides transparency.
- **Automated testing:** Implement automated testing to catch issues early in the development process. Automated tests help ensure consistent quality and reduce the risk of introducing new bugs.

By following these best practices, you can effectively manage versioning and releases, ensuring a smooth and reliable experience for your app users.

## Next steps

Expand Down

0 comments on commit c082281

Please sign in to comment.