Building Native Hybrid Apps 

Since version 2.0, it is possible to create Apple Xcode Project and Android Studio projects ready to be compiled.

Thorium will generate the code and create an optimized version of the existing PWA for native use. All unnecessary features will be automatically removed from your existing projects (SEO, Service Worker….) In order to create a lightweight version, optimized for native use, but in the meantime, all PWA features will still be available for the PWA version of your project . Note that since the last Xcode 12, it is even possible to create a Compiled App for Mac Desktop, so your App can exist in 4 versions: PWA, Native iOS, Native Android and Native MacOS.

Requirements

When your mobile project is ready, it is possible to create a native application for iOS and for Android, but you must first make sure of the following points:

• MacOS version: Make sure your Mac is up to date, we recommend MacOS 10.15.x or higher

• iOS projects: you need to download and install the latest version of XCode: https://developer.apple.com/download/  https://developer.apple.com/download/

  Note

  Xcode is free and will allow you to compile your app and run it on the Apple Simulator, but if you want to install and run an app on a physical device or submit an app to the Apple App Store, you will need to subscribe. to the Apple Developer Program ($99/year). 
  You can sign up for the Apple Developer Program here: https://developer.apple.com/programs/enroll/
  

• Android projects: you need to download and install the latest version of Android Studio, it can be downloaded here: https://developer.android.com/studio
  Unlike Xcode, Android Studio will allow you to install and run your app on a physical device, but if you want to submit your app to the Google Play Store, you will need to register for the Google Play Console ( $25 Developer Registration Fee)
  

Server Requirements

A Native App embeds its own local web server, so in most cases your App can be available in stores without having to be hosted on a server as much.
There are a few important exceptions that you should be aware about:

• If you want your Application to be available in Native mode but also in PWA mode, then the entire App must be hosted on a server.

• If you are using Database Express (Thorium Projects with SQLite), then the Database part must be hosted on a server.
  When Thorium generates a project including an SQLite database, it generates an additional folder called "Server" in the folder where the xCode and Android studio projects are created  that you must upload to your Hosting.
  In this case, you must also define the server address in the project settings (General tab)

  

Getting Started

Once your environment is ready, you will have access to the native application generation menu available in the Project menu:

The following dialog box opens:

If Xcode and Android Studio are correctly installed in the Application folder of your Mac, the 2 options will then be activated (you can even create iOS and Android applications simultaneously)

From this step, you need to set the following parameters:

• Export Folder. the folder on your Mac where you want to export the projects. Use the button on the right of the screen to change it.
  

• App Name. the name that will be displayed when the application is installed on a physical device. (Default filled with the name of your project)
  

• Company Name the name of your Company that will be used for calculating the Package name / Bundle ID.
  

• Package Name (bundle ID) bundle ID/Package is a unique identifier calculated from your application and your company name.
  This name is constructed from the reverse DNS syntax: com.companyname.appname
  This ID must be unique if you want your app to be accepted in stores (there are not 2 apps in stores with the same bundle ID/Package).
  This identifier must contain only Latin characters and must be written in lowercase (abcdef….)
  

• Launch xCode/Android Studio if selected, then Thorium will automatically start Xcode and Android Studio after the App generation.
  

Starting Generation

Clicking on the Next button will start the Native App Project generation:

The log list will show all executed operations, if there are any warnings / errors, they will be displayed with an orange / red dot. In our example the icons have not been set, so there is a warning that the default icon will be used.

The build process will create the Xcode and Android Studio projects based on the capacitor.js template.
Thorium will choose the required items in the PWA project and automatically add the required dependencies.
For more advanced needs (Capacitor plugins …) , please read the Capacitor documentation at: https://capacitorjs.com/docs

Once the Xcode project is generated and Xcode launched, you will see the following screen:

Select the App item from the list on the left

By Clicking on the Header, you can build/run your app on different devices: simulators or real device:

Xcode Project Settings

At this step, it is still time to adjust basic parameters:

• Display Name: the App name on the Mobile Phone

• Bundle Identifier: the unique identifier for your App

• Version and Build: the Version number and build number for your Ap

• iPhone, iPad and Mac: the targets for your App, you can build an App for iPhone only or for iPhone and iPad. 

  Note

  Since Xcode version 12, it is possible to create a compiled App for the Mac, select the Mac checkbox if you want to try it.
  

• Device Orientation: select here the orientation allowed for your App. Choosing only “portrait” will make your life easier as you won’t have to take care about orientation changes in your App Design.

Running your App

If you don’t have subscribed to the Apple Developer Program, then you can only run the App on the Mobile simulator, click on the Run button to launch it:

If your App is compiled successfully but doesn’t start, Select the Xcode Menu Products=>Scheme=>Edit Scheme , and check if App is well Selected in the Executable list: 

Running your App on your iPhone

If you're a subscriber to the Apple Developer Program, connect your iPhone to your Mac with a cable (use the cable that came with your iPhone, plug one end into the phone, and the other into a USB port on your Mac.)

Unlock your iPhone, it should appear in the Xcode device list:

Because you have selected a real physical device, Xcode will refuse to run the App until you have selected your Development Team Certificate:

Select your Development Profile from this list and click on the Run button: the App will be installed on your mobile phone and will be executed!

Make sure you are using a recent version of Android studio (4.0 and greater)

Once the Android project is generated and Android Studio launched, you will see the following screen:

Select the item App from the list on the left side, select a and click on the Run button.

Select a device, and click on the Run button.

Running the App on your physical device

Connect your Mobile to your Mac with a Cable (use the cable that came with your Mobile, plug one end into the phone and the other into a USB port on your Mac.)

Select your Phone from the device list, and click on the Run button:

Your App will be installed and executed on your mobile phone!