Difference between revisions of "Step By Step Guide"

Latest revision as of 13:10, 7 August 2023

Introduction

Expected result

By following this guide you will build your own mobile app (iOS, Android or both) with all Ethora engine features (alternatively you may choose to disable / limit some features via Config file).

In the process you will specify your own name and do a basic branding (logo, colours).

How long does it take?

A) It takes just 0.5h for a React Native engineer experienced with Ethora engine to produce a new app build.

B) A React Native engineer without previous Ethora experience should be able to complete it within around 1 work day.

C) You may need a 2-3 work days if you have done some software development but you don't have much experience with React Native.

In any case, it would take not less than 4-6 months for a team of experienced software engineers to develop a new app for your project with similar qualities and a feature set of Ethora engine. So irrespective of the option above, you are going to be saving a ton of time and investment by building on top of it.

Note: whilst Ethora can be called a "no-code" or a "low-code" product and we encourage you to use the product as is, some projects would opt for an advanced customization. Such as adding new screens, features, custom backend integrations or chat bots etc. You might need to allocate 1-2 months or more if you plan to add new functionality on top of Ethora engine, depending on the extent of additional functionalities and modifications.

Make sure to check the Config file first to see if the changes you want are not covered by parameters and switches there.

Pre-requisites

You are expected to have your system set up already for React Native development for either iOS or Android, or both.

If you don't have that setup yet, you will need to install the required packages, such as:

Android Studio
Node.js
XCode
Yarn or NPM
React Native environment (https://reactnative.dev/docs/environment-setup)

Note for vscode users: if you use Visual Studio Code, we personally recommend installing the following extensions to make your life better/easier:
React native snippet

Gitlens

Color highlight

Prettier

Steps to build white-labelled Android app using Ethora

mkdir [your_app_name]: This command creates a new directory (folder) with the name [your_app_name]. Replace [your_app_name] with the desired name of your app.

cd [your_app_name]: This command navigates into the newly created directory, making it the current working directory.

git clone https://github.com/dappros/ethora.git: This command clones the Ethora GitHub repository into your newly created [your_app_name] directory. It downloads all the code and files from the repository to your local machine.

cd ethora/client-reactnative/: This command moves into the client-reactnative directory within the cloned repository. This is the root directory of the React Native application.

npm i react-native-rename: This installs the react-native-rename package, which is used to rename the React Native app easily. The package will be installed locally in the project directory.

npx [/cdn-cgi/l/email-protection [email protected]] "your_app_name" -b "com.yourappname": This renames the React Native app to [your_app_name] and changes the package name (bundle identifier) to "com.yourappname". You should replace [your_app_name] with your desired app name and update "com.yourappname" to a unique identifier for your app. The package name is an important identifier for Android apps, and it should be unique to avoid conflicts when publishing the app to the Google Play Store.

yarn: This command installs the project dependencies using Yarn. It reads the package.json file and installs all the required packages for the React Native project.

find and replace com.ethora with com.yourappname throughout the entire project directory: This step involves manually searching for the string "com.ethora" in the entire project directory and replacing it with "com.yourappname". This is necessary because some files may contain the old package name, and it needs to be updated to the new one.

yarn android / npm run android: This command builds the Android app and runs it on an Android device or emulator. It bundles the JavaScript code and compiles the native code required for the Android platform. Once the build is successful, it deploys the app to the connected Android device or emulator.

These steps allow you to create a white-labeled version of the Ethora React Native app, with a new name and package name that can be used for branding and distribution as a separate app. Keep in mind that while the steps provided are generally applicable, specific issues or variations may arise depending on the complexity of the project, version of dependencies, or the system you are working on.

Video Guide: Build Android app using Ethora engine

You'll find all the options for the modification in the docs/config.ts for you to continue building your own product with ethora engine. NOTE: If you're not using M1 chipset mac machine then remove the line __apply_Xcode_12_5_M1_post_install_workaround(installer) from Podfile.

Steps to build white-labelled iOS app using Ethora

mkdir [your_app_name]: This command creates a new directory (folder) with the name [your_app_name]. Replace [your_app_name] with the desired name of your app.

cd [your_app_name]: This command navigates into the newly created directory, making it the current working directory.

git clone https://github.com/dappros/ethora.git: This command clones the Ethora GitHub repository into your newly created [your_app_name] directory. It downloads all the code and files from the repository to your local machine.

cd ethora/client-reactnative/: This command moves into the client-reactnative directory within the cloned repository. This is the root directory of the React Native application.

npm i react-native-rename: This installs the react-native-rename package, which is used to rename the React Native app easily. The package will be installed locally in the project directory.

npx [/cdn-cgi/l/email-protection [email protected]] "your_app_name" -b "com.yourappname": This renames the React Native app to [your_app_name] and changes the package name (bundle identifier) to "com.yourappname". You should replace [your_app_name] with your desired app name and update "com.yourappname" to a unique identifier for your app. The bundle identifier is a unique identifier for iOS apps, and it needs to be changed to avoid conflicts when distributing the app on the App Store.

cd ios: This command moves into the ios directory, which contains iOS-specific files and configuration for the React Native app.

pod install: This command installs the CocoaPods dependencies for the iOS project. CocoaPods is a dependency manager for iOS projects, and it is used to install and manage native dependencies for React Native projects.

cd ..: This command goes back to the previous directory (/ethora/client-reactnative/) from the ios directory.

open xcode and choose "Open existing project"; select the ios folder located in /[your_app_name]/ethora/client-reactnative/: This step opens Xcode and allows you to open the iOS project of your React Native app. Navigate to the ios folder within your [your_app_name] directory, and select the Xcode project file (with a .xcodeproj extension) to open it.

Navigate to ios/[your_app_name]/AppDelegate.mm and search for the keyword "ethora": In this step, you need to modify the AppDelegate.mm file in Xcode. Search for the keyword "ethora" and replace it with your actual app name in the following line of code: UIView *rootView = RCTAppSetupDefaultRootView(bridge, @"your_app_name", nil);

Click on "Build" button; iOS emulator will run once the build is finished, and in the terminal, Metro Bundler will start bundling. NOTE: This step mentions that the process will likely fail, and it recommends running "npm start" from your previous terminal or directly from the code editor's terminal at /ethora/client-reactnative/ directory to avoid any failures. Running "npm start" launches the Metro Bundler, which is responsible for bundling JavaScript code for the React Native app. By following these steps, you will be able to create a white-labeled version of the Ethora React Native app with a new name and bundle identifier, suitable for running on iOS devices and potentially distributing through the App Store. Please note that specific issues or variations may occur based on the complexity of the project, version of dependencies, or the Xcode environment you are using.

Video Guide: Build iOS app using Ethora engine

Troubleshooting: Android

Can't run the build on the physical device

Enable the "Developer options" menu by going to Settings → About phone → Software information and then tapping the Build number row at the bottom seven times. You can then go back to Settings → Developer options to enable "USB debugging".

Note: enabling "Developer options" may vary across devices / OS versions. Google the instructions for yours.

Note: sometimes you need to enable multiple options, for example in my case I needed to enable these 3:

USB debugging
Install via USB
USB debugging (Security settings)

Things don't update

If you changed some asset like a logo or background image, launch and see the old one (or see image is gone) the culprit could be the cache. To troubleshoot:

Kill the node server (just close your terminal tab where node/metro is running)
Open a new terminal (in vs code or a new terminal window in the same project folder) and run this command: yarn start --reset-cache
Build again ("yarn android").

@@ Line 1: / Line 1: @@
 == Introduction ==
+=== Expected result ===
-=== What is the expected result? ===
 By following this guide you will build your own mobile app (iOS, Android or both) with all Ethora engine features (alternatively you may choose to disable / limit some features via Config file).
 In the process you will specify your own name and do a basic branding (logo, colours).
 === How long does it take? ===
 A) It takes just '''0.5h''' for a React Native engineer experienced with Ethora engine to produce a new app build.
@@ Line 11: / Line 9: @@
 B) A React Native engineer without previous Ethora experience should be able to complete it within around '''1 work day'''.
-C) You may need a '''couple work days''' or more if you have done some software development but you don't have much experience with React Native.
+C) You may need a '''2-3 work days''' if you have done some software development but you don't have much experience with React Native.
 In any case, it would take not less than 4-6 months for a team of experienced software engineers to develop a new app for your project with similar qualities and a feature set of Ethora engine. So irrespective of the option above, you are going to be saving a ton of time and investment by building on top of it.
 Note: whilst Ethora can be called a "no-code" or a "low-code" product and we encourage you to use the product as is, some projects would opt for an advanced customization. Such as adding new screens, features, custom backend integrations or chat bots etc. You might need to allocate '''1-2 months''' or more if you plan to add new functionality on top of Ethora engine, depending on the extent of additional functionalities and modifications.
 Make sure to check the Config file first to see if the changes you want are not covered by parameters and switches there.
+== Pre-requisites ==
+You are expected to have your system set up already for React Native development for either iOS or Android, or both.
-== Steps to build ==
+If you don't have that setup yet, you will need to install the required packages, such as:
+* Android Studio
-=== Step 1 - create a new React Native project ===
+* Node.js
-Open the terminal at your project directory and create your new project <code>npx react-native init [proj_name]</code>
+*XCode
+* Yarn or NPM
-It will download the react-native template and install cocoapods dependencies. This may take few minutes depending on your network speed.
+*React Native environment (https://reactnative.dev/docs/environment-setup)
+<blockquote>Note for vscode users: if you use Visual Studio Code, we personally recommend installing the following extensions to make your life better/easier:
-=== Step 2 - activate Yarn ===
+* React native snippet
-Now we need to go inside the project folder to execute further commands
+* Gitlens
+* Color highlight
-<code>cd [proj_name]</code>
+* Prettier
+</blockquote>
-<code>yarn</code>
+== Steps to build white-labelled Android app using Ethora ==
+<blockquote>
-=== Step 3 - retrieve and set up the repository ===
+# <code>'''mkdir [your_app_name]'''</code>: This command creates a new directory (folder) with the name <code>[your_app_name]</code>. Replace <code>[your_app_name]</code> with the desired name of your app.
-Now download/clone the code from GitHub repo and update the folder structure as instructed below.
+# <code>'''cd [your_app_name]'''</code>: This command navigates into the newly created directory, making it the current working directory.
+# <code>'''git clone <nowiki>https://github.com/dappros/ethora.git</nowiki>'''</code>: This command clones the Ethora GitHub repository into your newly created <code>[your_app_name]</code> directory. It downloads all the code and files from the repository to your local machine.
-Locate "src" and "docs" folder in Ethora project directory and copy both the folders
+# <code>'''cd ethora/client-reactnative/'''</code>: This command moves into the <code>client-reactnative</code> directory within the cloned repository. This is the root directory of the React Native application.
+# <code>'''npm i react-native-rename'''</code>: This installs the <code>react-native-rename</code> package, which is used to rename the React Native app easily. The package will be installed locally in the project directory.
-Paste them in your project directory
+# <code>'''npx [/cdn-cgi/l/email-protection <nowiki>[email protected]</nowiki>] "your_app_name" -b "com.yourappname"'''</code>: This renames the React Native app to <code>[your_app_name]</code> and changes the package name (bundle identifier) to <code>"com.yourappname"</code>. You should replace <code>[your_app_name]</code> with your desired app name and update <code>"com.yourappname"</code> to a unique identifier for your app. The package name is an important identifier for Android apps, and it should be unique to avoid conflicts when publishing the app to the Google Play Store.
+# <code>'''yarn'''</code>: This command installs the project dependencies using Yarn. It reads the <code>package.json</code> file and installs all the required packages for the React Native project.
-Now open both the projects in your code editor side by side.
+# <code>'''find and replace com.ethora with com.yourappname throughout the entire project directory'''</code>: This step involves manually searching for the string <code>"com.ethora"</code> in the entire project directory and replacing it with <code>"com.yourappname"</code>. This is necessary because some files may contain the old package name, and it needs to be updated to the new one.
+# <code>'''yarn android / npm run android'''</code>: This command builds the Android app and runs it on an Android device or emulator. It bundles the JavaScript code and compiles the native code required for the Android platform. Once the build is successful, it deploys the app to the connected Android device or emulator.
-Navigate to package.json and replace dependencies, devDependencies and jest from package.json of Ethora to your project's package.json
+</blockquote>These steps allow you to create a white-labeled version of the Ethora React Native app, with a new name and package name that can be used for branding and distribution as a separate app. Keep in mind that while the steps provided are generally applicable, specific issues or variations may arise depending on the complexity of the project, version of dependencies, or the system you are working on.
+=== Video Guide: Build Android app using Ethora engine ===
-Navigate to <code>index.js</code>
+<youtube>wKDVV_Ly0Pg</youtube>
-Now we need to change the import from default app.js to app.js from inside the src folder
-In order to do this, change <code>import App from './App';</code> to <code>import App from './src/App';</code>
-Go to your terminal again and execute <code>yarn</code> command in your project directory because the package.json is now updated.
-This will install all the required packages.
-=== Step 4 - build for iOS ===
-Now in your project folder execute the following commands.
-<code>cd ios</code>
-<code>pod install</code>
-resolve the errors then in your project directory execute <code>yarn ios</code>
-This will build the app.
-=== Step 5 - configure & brand ===
-Dismiss the notice and navigate to "docs" folder in your project directory.
-Open config.js
-You can now set the appTitle to your project name and add your own logo for rebranding.
-You'll find all the options for the modification in this config.js for you to continue building your own product with ethora engine.
-'''NOTE''': If you're not using M1 chipset mac machine then remove the line <code>__apply_Xcode_12_5_M1_post_install_workaround(installer)</code> from '''Podfile.'''
+You'll find all the options for the modification in the <code>'''docs/config.ts'''</code> for you to continue building your own product with ethora engine.
+'''NOTE''': If you're not using M1 chipset mac machine then remove the line <code>'''__apply_Xcode_12_5_M1_post_install_workaround(installer)'''</code> from '''Podfile.'''
+== Steps to build white-labelled iOS app using Ethora ==
+<blockquote>
+# <code>'''mkdir [your_app_name]'''</code>: This command creates a new directory (folder) with the name <code>[your_app_name]</code>. Replace <code>[your_app_name]</code> with the desired name of your app.
+# <code>'''cd [your_app_name]'''</code>: This command navigates into the newly created directory, making it the current working directory.
+# <code>'''git clone <nowiki>https://github.com/dappros/ethora.git</nowiki>'''</code>: This command clones the Ethora GitHub repository into your newly created <code>[your_app_name]</code> directory. It downloads all the code and files from the repository to your local machine.
+# <code>'''cd ethora/client-reactnative/'''</code>: This command moves into the <code>client-reactnative</code> directory within the cloned repository. This is the root directory of the React Native application.
+# <code>'''npm i react-native-rename'''</code>: This installs the <code>react-native-rename</code> package, which is used to rename the React Native app easily. The package will be installed locally in the project directory.
+# <code>'''npx [/cdn-cgi/l/email-protection <nowiki>[email protected]</nowiki>] "your_app_name" -b "com.yourappname"'''</code>: This renames the React Native app to <code>[your_app_name]</code> and changes the package name (bundle identifier) to <code>"com.yourappname"</code>. You should replace <code>[your_app_name]</code> with your desired app name and update <code>"com.yourappname"</code> to a unique identifier for your app. The bundle identifier is a unique identifier for iOS apps, and it needs to be changed to avoid conflicts when distributing the app on the App Store.
+# <code>'''cd ios'''</code>: This command moves into the <code>ios</code> directory, which contains iOS-specific files and configuration for the React Native app.
+# <code>'''pod install'''</code>: This command installs the CocoaPods dependencies for the iOS project. CocoaPods is a dependency manager for iOS projects, and it is used to install and manage native dependencies for React Native projects.
+# <code>'''cd ..'''</code>: This command goes back to the previous directory (<code>/ethora/client-reactnative/</code>) from the <code>ios</code> directory.
+# <code>'''open xcode and choose "Open existing project"; select the ios folder located in /[your_app_name]/ethora/client-reactnative/'''</code>: This step opens Xcode and allows you to open the iOS project of your React Native app. Navigate to the <code>ios</code> folder within your <code>[your_app_name]</code> directory, and select the Xcode project file (with a .xcodeproj extension) to open it.
+# <code>'''Navigate to ios/[your_app_name]/AppDelegate.mm and search for the keyword "ethora"'''</code>: In this step, you need to modify the <code>AppDelegate.mm</code> file in Xcode. Search for the keyword "ethora" and replace it with your actual app name in the following line of code: <code>UIView *rootView = RCTAppSetupDefaultRootView(bridge, @"your_app_name", nil);</code>
+# '''Click on "Build" button'''; iOS emulator will run once the build is finished, and in the terminal, Metro Bundler will start bundling. '''NOTE''': This step mentions that the process will likely fail, and it recommends running "npm start" from your previous terminal or directly from the code editor's terminal at /ethora/client-reactnative/ directory to avoid any failures. Running "npm start" launches the Metro Bundler, which is responsible for bundling JavaScript code for the React Native app. By following these steps, you will be able to create a white-labeled version of the Ethora React Native app with a new name and bundle identifier, suitable for running on iOS devices and potentially distributing through the App Store. Please note that specific issues or variations may occur based on the complexity of the project, version of dependencies, or the Xcode environment you are using.
+</blockquote>
+=== Video Guide: Build iOS app using Ethora engine ===
+<youtube>Mm8MBWRXACU</youtube>
+== Troubleshooting: Android ==
+=== Can't run the build on the physical device ===
+Enable the "Developer options" menu by going to Settings → About phone → Software information and then tapping the <code>Build number</code> row at the bottom seven times. You can then go back to Settings → Developer options to enable "USB debugging".
-Please check out the video for more details regarding the setup of Ethora.
+Note: enabling "Developer options" may vary across devices / OS versions. Google the instructions for yours.
-[https://youtu.be/vX9XbVwyrVc Ethora setup video tutorial]
+Note: sometimes you need to enable multiple options, for example in my case I needed to enable these 3:
+* USB debugging
+* Install via USB
+* USB debugging (Security settings)
+=== Things don't update ===
+If you changed some asset like a logo or background image, launch and see the old one (or see image is gone) the culprit could be the cache. To troubleshoot:
+# Kill the node server (just close your terminal tab where node/metro is running)
+# Open a new terminal (in vs code or a new terminal window in the same project folder) and run this command: yarn start --reset-cache
+# Build again ("yarn android").