A React Native project for Android and iOS Beyond Finance mobile applications.

Note: This section should be read in conjunction with the Installing Dependencies section of React Native's Environment Setup guide for more information.

Visit the link above and click the tab for React Native CLI Quickstart before you begin (we're opting into the more flexible direct native experience as opposed to the more limited, curated Expo framework).

To get started, you will need the following dependencies installed:

• Node < v.17
• Watchman
• rbenv (or your preferred Ruby version manager)
• The Ruby version listed in .ruby-version.

For iOS development:

• Xcode: current supported version 12.5.

For Android development:

• The JDK (brew tap AdoptOpenJDK/openjdk && brew install --cask adoptopenjdk8)
• Android Studio.

On macOS, these will usually be installed via Homebrew. On the React Native web site, follow the instructions for Target OS for both Android and iOS. iOS is a little easier, so you may want to start with that first.

On macOS using M1 Chips, follow these two steps for XCode and Ruby:

Xcode - If you have Xcode downloaded in your Applications folder for example, you just need to:

• Open Terminal

• Open Applications folder in Finder

• Drag the Xcode app into Terminal so it gets its path

• then add this next to it: /Contents/MacOS/Xcode, so the full command will be something like /Applications/Xcode-12.5.1.app/Contents/MacOS/Xcode

• Press enter to run the command

Now you should be able to run it. You will note that when you open this version of Xcode, the Terminal will open too, but don't close Terminal because it will close the Xcode too.

Ruby - base installation, common bug fix.

Next, clone the repo run the app setup script from the root of the project tree:

cd BeyondMobile
bin/setup

(Note: It's safe to run bin/setup regularly to ensure your local dependencies are up to date. If you don't want to be prompted to copy .env every time, you can run the command touch .skipenv from the project root to always skip this step.)

This will install any additional dependencies and make sure the iOS and Android projects are ready for development.

There are a few extra things to note for each environment below.

Android setup is a bit more cumbersome, with a need to manually set some environment variables in your shell.

Android Studio, as mentioned, is the critical software, providing emulator and library support. This guide is a bit out-of-date, but has useful steps for Android setup with a little more detail. The current version of Android Studio has some of the steps mentioned there now preconfigured, so feel free to follow the Android installation section of the guide and just confirm that the details are correct. You may get some of it done for free now.

Finally, in order to build and run the Android application, you'll have to accept the license. Assuming you're in a shell where you have configured your environment variables as instructed by setup, run:

$ANDROID_HOME/tools/bin/sdkmanager --licenses

After setting up your emulators, you should be able to build and run your code targeting either or both environments from yarn scripts configured in package.json.

yarn start

Runs the local React Native javascript environment, which executes the code back end for any device build running in an emulator. Any number of emulators may connect to the same run-time. If the React Native environment is not running when a particular device target is started, the start script will run first and be available for any subsequent builds for any device environment.

By default, the app will point at https://www.beyondfinance.com for API requests and rendering browser content. You may use an environment variable to update the site target by setting BEYOND_URL or the enviroment (production, development, or staging) with BEYOND_ENV, and you should make sure to clear the cache with the build, in order to override any previous value.

eg, to run pointing at a specific Beyond instance url execute as:

BEYOND_URL=https://for-example-your-named-computer-host.com:3000 yarn start --reset-cache

eg, to run versus staging environment execute as:

BEYOND_ENV=staging yarn start --reset-cache

With the environment variable to indicate development, the site target will correctly toggle between localhost and the Android emulator ip alias for localhost on Macs; ie, BEYOND_ENV=development yarn start --reset-cache

yarn android

Builds the Android bundle, starts the React Native run-time if not already running, and runs the application bundle in the target Android emulator. Some documentation implies that the emulator should be running before executing the script, but the current build of Android Studio seems to be able to automatically open the emulator like the iOS side does, if it is not already running.

yarn ios

Builds the iOS bundle, starts the React Native run-time if not already running, and runs the application bundle in the target iOS simulator.

Code should automatically update for local changes to any running emulator, but the React Native script offers keystroke control. The r key reloads the React Native code, which will reset and reload any currently running emulators connected to it.

Note that if you add new packages, particularly packages with native dependencies, you may need to restart the React Native environment entirely.

See Performance.

Open core-api.yml in the beyond-finance repo and comment out the localhost:5000 ENV variables under the development section so it points to core-api staging data URLs instead. Core-api.yml will look like:

development:
  <<: *default
  # core_api_url: <%= ENV.fetch('CORE_API_URL', 'http://localhost:5000/servicing/graphql') %>
  # servicing_url: <%= ENV.fetch('CORE_API_URL', 'http://localhost:5000/servicing/graphql') %>
  # origination_url: <%= ENV.fetch('CORE_API_URL', 'http://localhost:5000/origination/graphql') %>

Next, in .env for the BeyondMobile repo change the following values of BEYOND_ENV, BEYOND_SERVICE_NAME, and BEYOND_URL to

BEYOND_ENV=development
BEYOND_SERVICE_NAME=localhost:3000
BEYOND_URL=http://localhost:3000

Once both steps are completed, you should just have to fire up both repos and you'll see the beyond-finance terminal populating with output as you go through the mobile app.

The react-native-dotenv provides a Babel plugin that reads environment variables at build time and makes them available as JavaScript constants in the @env pseudo-module. For example:

import {BEYOND_ENV} from '@env';

const logEnvironment = () => {
  console.log(`Environment is '${BEYOND_ENV}'`);
};

In practice, the src/env module defines all known environment variables. Instead of using @env directly, use the getenv function:

// src/cool-module.ts
import {getEnv} from './env';

const coolFunction = () => {
  if (getEnv('BEYOND_ENV') === 'production') {
    // do production things
  }
};

getEnv throws an error if the requested environment variable is undefined.

Default values will be loaded from a .env file at the root of the repository. This file is ignored by Git, but bin/setup automatically creates one for you based on the .env.sample file. On CI, the values are always read from the environment, instead of .env.

Whenever you make changes to your environment variables or update .env, the Metro cache will need to be reset. Use this command to reset the cache:

yarn start --reset-cache

The app reports activity to our Heap accounts, which are configured to environments (production, staging, and development) for the Beyond site.

The prestart package script automatically updates heap.config.json based on the build time environment.

It's desirable to keep the versions in sync across the application deployments, which means keeping js package, Android project, and Xcode project versions consistent.

We use react-native-version in order to manage this a bit more easily; run the npm version command in the shell, and all environments should receive the update.

npm version [<version>|patch|minor|major]

A linting script is available via yarn as well, run yarn lint to see output and yarn lint --fix to automatically accept any fixes that can be addressed programmatically.

It's a good idea to use the linting script because it incorporates some rubocop-style rules specifically targeted to the React framework, which can catch suspect code structures and scope/closure hazards, beyond simple stylistic issues.

Builds will automatically deploy to the Staging store for iOS and Android. To release the build to Apple and Android stores, follow the steps below

1. To go to production you must login to CircleCI and approve the hold-prod-deploy job.
2. After build apps look good via internal testing. Approve both hold-release-android and hold-release-ios jobs to go to in review status with developer on hold release.
3. This is an automated step: after both builds are successful and push to the store, git-post-release-actions job will run and the job will tag the current release and then bump the version number to the next minor version.
4. After the apps have been approve by both stores, you must login to the Google Play Console and Apple Store and manually approve those builds.

Make sure the site root url defined in src/utils.jsx is pointing at the correct instance of the web application. For a draft build, this is likely to be the mobile staging environment. For a release candidate, it should be the production web application domain. During local development, it you may wish to set this to be direct localhost entries, or the ip/hostname allowing access to your app via your local network.

In order to build an Android App Bundle for release, you will need to acquire and set up some assets not included in the repository, including:

• the beyond-upload-key.keystore file. Place the file in the android/app directory.
• the password for the keystore; when you have the password,
  • open the Applications > Utilities > Keychain Access application
  • click the + button to add a new item
  • enter:
    • Keychain Item Name: android_keystore
    • Account Name: Beyond Finance
    • Password: the password

The build-time keystore password is now defined in an environment variable KEY_STORE_PASSWORD e.g.

export KEY_STORE_PASSWORD=foo

To build the release, navigate into the android directory and execute ./gradlew bundleRelease. The .aab will be built to the android/app/build/outputs/bundle/release directory, and may be uploaded to the Google Play account.

You may also build the release to your emulator via yarn android --variant=release in order to see how the application behaves with the javascript running on the emulator rather than via the metro server on your machine. Note that if you have previously run debug versions of the app, you will need to uninstall them/wipe your emulator data, or a signing collision will occur and the new context will not install.

Useful resources:

• https://reactnative.dev/docs/signed-apk-android
• and using the keychain for more secure keystore: https://pilloxa.gitlab.io/posts/safer-passwords-in-gradle/