From 11fc50b79c77be8c9f2cdfa1494128e55b18c322 Mon Sep 17 00:00:00 2001
From: Frieder Bluemle <frieder.bluemle@gmail.com>
Date: Wed, 15 Apr 2020 15:38:21 -0700
Subject: [PATCH] Update integration-with-existing-apps docs

---
 docs/_integration-with-exisiting-apps-java.md | 195 ++++++++----------
 1 file changed, 86 insertions(+), 109 deletions(-)

diff --git a/docs/_integration-with-exisiting-apps-java.md b/docs/_integration-with-exisiting-apps-java.md
index 32f08877423..dd0c83bd80f 100644
--- a/docs/_integration-with-exisiting-apps-java.md
+++ b/docs/_integration-with-exisiting-apps-java.md
@@ -26,22 +26,22 @@ Go to the root directory for your project and create a new `package.json` file w
   "version": "0.0.1",
   "private": true,
   "scripts": {
-    "start": "yarn react-native start"
+    "start": "react-native start"
   }
 }
 ```
 
-Next, make sure you have [installed the yarn package manager](https://yarnpkg.com/lang/en/docs/install/).
+Next, make sure you have [installed the Yarn package manager](https://yarnpkg.com/lang/en/docs/install/).
 
 Install the `react` and `react-native` packages. Open a terminal or command prompt, then navigate to the directory with your `package.json` file and run:
 
 ```shell
-$ yarn add react-native
+$ yarn add react-native --exact
 ```
 
 This will print a message similar to the following (scroll up in the yarn output to see it):
 
-> warning "react-native@0.52.2" has unmet peer dependency "react@16.2.0".
+> warning "react-native@0.63.4" has unmet peer dependency "react@16.13.1".
 
 This is OK, it means we also need to install React:
 
@@ -49,28 +49,15 @@ This is OK, it means we also need to install React:
 $ yarn add react@version_printed_above
 ```
 
-Yarn has created a new `/node_modules` folder. This folder stores all the JavaScript dependencies required to build your project.
+Yarn has created a new `node_modules/` folder. This folder stores all the JavaScript dependencies required to build your project.
 
 Add `node_modules/` to your `.gitignore` file.
 
 ## Adding React Native to your app
 
-### Configuring maven
+### Configuring Gradle build scripts
 
-Add the React Native and JSC dependency to your app's `build.gradle` file:
-
-```gradle
-dependencies {
-    implementation "com.android.support:appcompat-v7:27.1.1"
-    ...
-    implementation "com.facebook.react:react-native:+" // From node_modules
-    implementation "org.webkit:android-jsc:+"
-}
-```
-
-> If you want to ensure that you are always using a specific React Native version in your native build, replace `+` with an actual React Native version you've downloaded from `npm`.
-
-Add an entry for the local React Native and JSC maven directories to the top-level `build.gradle`. Be sure to add it to the “allprojects” block, above other maven repositories:
+Add entries for the local React Native and JSC maven directories to the top-level `build.gradle`. Be sure to add it to the `allprojects` block, above other entries:
 
 ```gradle
 allprojects {
@@ -81,31 +68,49 @@ allprojects {
         }
         maven {
             // Android JSC is installed from npm
-            url("$rootDir/../node_modules/jsc-android/dist")
+            url "$rootDir/../node_modules/jsc-android/dist"
         }
-        ...
+        // ...
+        google()
+        jcenter()
     }
-    ...
 }
 ```
 
-> Make sure that the path is correct! You shouldn’t run into any “Failed to resolve: com.facebook.react:react-native:0.x.x" errors after running Gradle sync in Android Studio.
+> Make sure that the path is correct! You shouldn’t run into any "Failed to resolve: com.facebook.react:react-native:0.x.x" errors after running Gradle sync in Android Studio.
 
-### Enable native modules autolinking
+Then, add the React Native and JSC dependencies to your app's `build.gradle` file:
+
+```gradle
+dependencies {
+    implementation 'androidx.appcompat:appcompat:1.2.0'
+    // ...
+    // noinspection GradleDynamicVersion
+    implementation 'com.facebook.react:react-native:+'  // From node_modules
+    // noinspection GradleDynamicVersion
+    implementation 'org.webkit:android-jsc:+'  // From node_modules
+}
+```
+
+> The dynamic version specifier (`+`) will always resolve to the specific version downloaded into `node_modules/`.
+
+#### Enable native modules autolinking
 
 To use the power of [autolinking](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md), we have to apply it a few places. First add the following entry to `settings.gradle`:
 
 ```gradle
-apply from: file("../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"); applyNativeModulesSettingsGradle(settings)
+apply from: "../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"; applyNativeModulesSettingsGradle(settings)
 ```
 
 Next add the following entry at the very bottom of the `app/build.gradle`:
 
 ```gradle
-apply from: file("../../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"); applyNativeModulesAppBuildGradle(project)
+apply from: "$rootDir/../node_modules/@react-native-community/cli-platform-android/native_modules.gradle"; applyNativeModulesAppBuildGradle(project)
 ```
 
-### Configuring permissions
+### Configuring AndroidManifest.xml
+
+#### Permissions
 
 Next, make sure you have the Internet permission in your `AndroidManifest.xml`:
 
@@ -117,11 +122,19 @@ If you need to access to the `DevSettingsActivity` add to your `AndroidManifest.
 
 This is only used in dev mode when reloading JavaScript from the development server, so you can strip this in release builds if you need to.
 
-### Cleartext Traffic (API level 28+)
+#### SYSTEM_ALERT_WINDOW for dev menu
+
+If your app is targeting Android `API level 23` or greater, make sure you have the `SYSTEM_ALERT_WINDOW` permission declared for the development build:
+
+    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
+
+This is required for certain features (e.g. "Perf Monitor") in the React Native dev menu to work correctly.
+
+#### Cleartext Traffic (API level 28+)
 
 > Starting with Android 9 (API level 28), cleartext traffic is disabled by default; this prevents your application from connecting to the [Metro bundler][metro]. The changes below allow cleartext traffic in debug builds.
 
-#### 1. Apply the `usesCleartextTraffic` option to your Debug `AndroidManifest.xml`
+Apply the `usesCleartextTraffic` option to your Debug `AndroidManifest.xml`:
 
 ```xml
 <!-- ... -->
@@ -142,17 +155,10 @@ Now we will actually modify the native Android application to integrate React Na
 
 #### The React Native component
 
-The first bit of code we will write is the actual React Native code for the new "High Score" screen that will be integrated into our application.
-
-##### 1. Create a `index.js` file
-
-First, create an empty `index.js` file in the root of your React Native project.
+The first bit of code we will write is the actual React Native code for a "Hello World" screen that will be integrated into our application.
 
-`index.js` is the starting point for React Native applications, and it is always required. It can be a small file that `require`s other file that are part of your React Native component or application, or it can contain all the code that is needed for it. In our case, we will put everything in `index.js`.
-
-##### 2. Add your React Native code
-
-In your `index.js`, create your component. In our sample here, we will add a `<Text>` component within a styled `<View>`:
+Create a file `index.js` in the root of your React Native project.
+`index.js` is the starting point for React Native applications, and it is always required. It can be a small file that `require`s other file that are part of your React Native component or application, or it can contain all the code that is needed for it. In our case, we will use a `<Text>` component within a styled `<View>`:
 
 ```jsx
 import React from 'react';
@@ -172,7 +178,8 @@ class HelloWorld extends React.Component {
     );
   }
 }
-var styles = StyleSheet.create({
+
+const styles = StyleSheet.create({
   container: {
     flex: 1,
     justifyContent: 'center'
@@ -190,48 +197,12 @@ AppRegistry.registerComponent(
 );
 ```
 
-##### 3. Configure permissions for development error overlay
-
-If your app is targeting the Android `API level 23` or greater, make sure you have the permission `android.permission.SYSTEM_ALERT_WINDOW` enabled for the development build. You can check this with `Settings.canDrawOverlays(this);`. This is required in dev builds because React Native development errors must be displayed above all the other windows. Due to the new permissions system introduced in the API level 23 (Android M), the user needs to approve it. This can be achieved by adding the following code to your Activity's in `onCreate()` method.
-
-```java
-private final int OVERLAY_PERMISSION_REQ_CODE = 1;  // Choose any value
-
-...
-
-if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
-    if (!Settings.canDrawOverlays(this)) {
-        Intent intent = new Intent(Settings.ACTION_MANAGE_OVERLAY_PERMISSION,
-                                   Uri.parse("package:" + getPackageName()));
-        startActivityForResult(intent, OVERLAY_PERMISSION_REQ_CODE);
-    }
-}
-```
-
-Finally, the `onActivityResult()` method (as shown in the code below) has to be overridden to handle the permission Accepted or Denied cases for consistent UX. Also, for integrating Native Modules which use `startActivityForResult`, we need to pass the result to the `onActivityResult` method of our `ReactInstanceManager` instance.
-
-```java
-@Override
-protected void onActivityResult(int requestCode, int resultCode, Intent data) {
-    if (requestCode == OVERLAY_PERMISSION_REQ_CODE) {
-        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
-            if (!Settings.canDrawOverlays(this)) {
-                // SYSTEM_ALERT_WINDOW permission not granted
-            }
-        }
-    }
-    mReactInstanceManager.onActivityResult( this, requestCode, resultCode, data );
-}
-```
-
 #### The Magic: `ReactRootView`
 
 Let's add some native code in order to start the React Native runtime and tell it to render our JS component. To do this, we're going to create an `Activity` that creates a `ReactRootView`, starts a React application inside it and sets it as the main content view.
 
-> If you are targeting Android version <5, use the `AppCompatActivity` class from the `com.android.support:appcompat` package instead of `Activity`.
-
 ```java
-public class MyReactActivity extends Activity implements DefaultHardwareBackBtnHandler {
+public class MyReactActivity extends AppCompatActivity implements DefaultHardwareBackBtnHandler {
     private ReactRootView mReactRootView;
     private ReactInstanceManager mReactInstanceManager;
 
@@ -246,15 +217,16 @@ public class MyReactActivity extends Activity implements DefaultHardwareBackBtnH
         // packages.add(new MyReactNativePackage());
         // Remember to include them in `settings.gradle` and `app/build.gradle` too.
 
-        mReactInstanceManager = ReactInstanceManager.builder()
-                .setApplication(getApplication())
-                .setCurrentActivity(this)
-                .setBundleAssetName("index.android.bundle")
-                .setJSMainModulePath("index")
-                .addPackages(packages)
-                .setUseDeveloperSupport(BuildConfig.DEBUG)
-                .setInitialLifecycleState(LifecycleState.RESUMED)
-                .build();
+        mReactInstanceManager =
+                ReactInstanceManager.builder()
+                        .setApplication(getApplication())
+                        .setCurrentActivity(this)
+                        .setBundleAssetName("index.android.bundle")
+                        .setJSMainModulePath("index")
+                        .addPackages(packages)
+                        .setUseDeveloperSupport(BuildConfig.DEBUG)
+                        .setInitialLifecycleState(LifecycleState.RESUMED)
+                        .build();
         // The string here (e.g. "MyReactNativeApp") has to match
         // the string in AppRegistry.registerComponent() in index.js
         mReactRootView.startReactApplication(mReactInstanceManager, "MyReactNativeApp", null);
@@ -269,9 +241,9 @@ public class MyReactActivity extends Activity implements DefaultHardwareBackBtnH
 }
 ```
 
-> If you are using a starter kit for React Native, replace the "HelloWorld" string with the one in your index.js file (it’s the first argument to the `AppRegistry.registerComponent()` method).
+> Make sure the module name in `startReactApplication` matches the app key used in your index.js file (it’s the first argument to the `AppRegistry.registerComponent()` method).
 
-Perform a “Sync Project files with Gradle” operation.
+Perform a "Sync Project files with Gradle" operation.
 
 If you are using Android Studio, use `Alt + Enter` to add all missing imports in your MyReactActivity class. Be careful to use your package’s `BuildConfig` and not the one from the `facebook` package.
 
@@ -279,10 +251,8 @@ We need set the theme of `MyReactActivity` to `Theme.AppCompat.Light.NoActionBar
 
 ```xml
 <activity
-  android:name=".MyReactActivity"
-  android:label="@string/app_name"
-  android:theme="@style/Theme.AppCompat.Light.NoActionBar">
-</activity>
+    android:name=".MyReactActivity"
+    android:theme="@style/Theme.AppCompat.Light.NoActionBar" />
 ```
 
 > A `ReactInstanceManager` can be shared by multiple activities and/or fragments. You will want to make your own `ReactFragment` or `ReactActivity` and have a singleton _holder_ that holds a `ReactInstanceManager`. When you need the `ReactInstanceManager` (e.g., to hook up the `ReactInstanceManager` to the lifecycle of those Activities or Fragments) use the one provided by the singleton.
@@ -291,33 +261,30 @@ Next, we need to pass some activity lifecycle callbacks to the `ReactInstanceMan
 
 ```java
 @Override
-protected void onPause() {
-    super.onPause();
-
+protected void onResume() {
+    super.onResume();
     if (mReactInstanceManager != null) {
-        mReactInstanceManager.onHostPause(this);
+        mReactInstanceManager.onHostResume(this, this);
     }
 }
 
 @Override
-protected void onResume() {
-    super.onResume();
-
+protected void onPause() {
     if (mReactInstanceManager != null) {
-        mReactInstanceManager.onHostResume(this, this);
+        mReactInstanceManager.onHostPause(this);
     }
+    super.onPause();
 }
 
 @Override
 protected void onDestroy() {
-    super.onDestroy();
-
     if (mReactInstanceManager != null) {
         mReactInstanceManager.onHostDestroy(this);
     }
     if (mReactRootView != null) {
         mReactRootView.unmountReactApplication();
     }
+    super.onDestroy();
 }
 ```
 
@@ -325,7 +292,7 @@ We also need to pass back button events to React Native:
 
 ```java
 @Override
- public void onBackPressed() {
+public void onBackPressed() {
     if (mReactInstanceManager != null) {
         mReactInstanceManager.onBackPressed();
     } else {
@@ -336,7 +303,17 @@ We also need to pass back button events to React Native:
 
 This allows JavaScript to control what happens when the user presses the hardware back button (e.g. to implement navigation). When JavaScript doesn't handle the back button press, your `invokeDefaultOnBackPressed` method will be called. By default this finishes your `Activity`.
 
-Finally, we need to hook up the dev menu. By default, this is activated by (rage) shaking the device, but this is not very useful in emulators. So we make it show when you press the hardware menu button (use `Ctrl + M` if you're using Android Studio emulator):
+Additionally, when integrating Native Modules which use `startActivityForResult`, your Activity needs to pass the result to the `onActivityResult` method of the `ReactInstanceManager` instance:
+
+```java
+@Override
+public void onActivityResult(int requestCode, int resultCode, Intent data) {
+    super.onActivityResult(requestCode, resultCode, data);
+    mReactInstanceManager.onActivityResult(this, requestCode, resultCode, data);
+}
+```
+
+Finally, we need to hook up the dev menu. On a device, this can be activated by shaking the device, or by pressing the hardware menu button (`Ctrl + M`/`Cmd + M` when using an Android emulator). For both devices and emulators, the dev menu can also be brought up by sending key event 82, which corresponds to the menu key: `adb shell input keyevent 82`.
 
 ```java
 @Override
@@ -355,7 +332,7 @@ Now your activity is ready to run some JavaScript code.
 
 You have now done all the basic steps to integrate React Native with your current application. Now we will start the [Metro bundler][metro] to build the `index.bundle` package and the server running on localhost to serve it.
 
-##### 1. Run the packager
+#### 1. Run the packager
 
 To run your app, you need to first start the development server. To do this, run the following command in the root directory of your React Native project:
 
@@ -363,7 +340,7 @@ To run your app, you need to first start the development server. To do this, run
 $ yarn start
 ```
 
-##### 2. Run the app
+#### 2. Run the app
 
 Now build and run your Android app as normal.
 
@@ -371,12 +348,12 @@ Once you reach your React-powered activity inside the app, it should load the Ja
 
 ![Screenshot](/docs/assets/EmbeddedAppAndroid.png)
 
-### Creating a release build in Android Studio
+#### Creating a release build in Android Studio
 
 You can use Android Studio to create your release builds too! It’s as quick as creating release builds of your previously-existing native Android app. There’s one additional step, which you’ll have to do before every release build. You need to execute the following to create a React Native bundle, which will be included with your native Android app:
 
 ```shell
-$ npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/com/your-company-name/app-package-name/src/main/assets/index.android.bundle --assets-dest android/com/your-company-name/app-package-name/src/main/res/
+$ yarn react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/app/src/main/assets/index.android.bundle --assets-dest android/app/src/main/res/
 ```
 
 > Don’t forget to replace the paths with correct ones and create the assets folder if it doesn’t exist.
