• Select Role
  • English
  • Login

Build Cordova Android and iOS Apps Using GitHub Actions

Customization and Building

Manual Customization

Fork GitHub Project

  1. Fork the Cordova Custom Mobile project into your own GitHub repository.
  2. NOTE: A forked public repository is also public. To make it private, either import the repository, duplicate the repository, or contact GitHub support to request to detach the fork. 

Customize App Configuration

  1. Update config.xml to replace the package name, ID, version, name, description, and author details as required:
    config.xml
     
    <widget android-activityName="CustomMobile" android-packageName="com.example.custom.mobile" android-versionCode="10000" id="com.example.custom.mobile" ios-CFBundleVersion="1.0.0" version="1.0.0" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0" xmlns:android="http://schemas.android.com/apk/res/android">

<name>Custom Mobile</name>
<description>Custom Mobile</description>
<author email="info@example.com" href="http://www.example.com">Example Inc</author>
…
        <config-file target="AndroidManifest.xml" parent="/manifest/application">
            <provider
                android:name="androidx.core.content.FileProvider"
                android:authorities="com.example.custom.mobile.provider"

Customize Title and About Dialog

  1. Update the title in www/index.html as required:

    www/index.html 
    <title>Custom Mobile</title>
…
<div id="cover" class="row p-2 h-25">
    <div class="col-10">
        <h6 class="p-2 mb-5 text-light">Custom Mobile</h6>
    </div>
    <div class="col p-2">
        <a href="#" class="m-2 my-0 float-end text-light" data-bs-toggle="modal" data-bs-target="#about-dialog"><i class="fa fa-circle-info"></span></i></a>
    </div>
</div>
…
     

  2. Update the About dialog in www/index.html as required:

    www/index.html
    <div class="modal-content">
    <div class="modal-header">
        <h5 class="modal-title" id="about-dialog-long-title">About</h5>
        <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
    </div>
    <div class="modal-body">
        <h7>Custom Mobile</h7>
        <div id="version">
            https://www.example.com
            <br />
            info@example.com
            <br />
            <br />
            VERSION 1.0.0
        </div>
    </div>
    <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
    </div>
</div>
     

Customize Images and CSS

  1. Replace the app logo:

    www/logo.png

  2. Replace the cover image:

    www/cover.jpg

  3. The app UI utilizes the Bootstrap CSS framework. The height of the cover image can be increased by setting the Bootstrap sizing class in the div with id “cover” e.g. change the class to h-50 for 50% vertical height: 

    …
<div id="cover" class="row p-2 h-50">
    <div class="col-10">
        <h6 class="p-2 mb-5 text-light">Custom Mobile</h6>
    </div>

  4. Customize the CSS colors in www/mobile.css:

    www/mobile.css
    h6.p-2.mb-5.text-light {
    color: #ffffff !important;
}
button {
    background: teal !important;
}
#profile-buttons a {
    color: teal;
}
input.form-check-input:checked {
    background-color: teal !important;
    border-color: teal !important;
}
     
  5. Optionally, update the Bootstrap CSS as required using SASS.

    a. Edit variables in bootstrap-custom.scss e.g. set the primary color to “teal”:

    bootstrap-custom.scss
    $primary: teal;
@import "bootstrap/scss/bootstrap";
     

    b. Generate the custom CSS by running:

    npm install -g sass
sass bootstrap-custom.scss bootstrap-custom.css
  6. By default, the app displays a navigation bar (appears at the top of Android and at the bottom of iOS). To display a floating button on the bottom left, set MobileApp.floatingButton to true in www/index.html 
    MobileApp.floatingButton = true;

 

MobileApp.floatingButton = false;

Customize Home URL

  1. By default, the mobile app allows a user to add or remove multiple profiles to connect to multiple Joget server URLs. Optionally, set a Joget URL to disable profiles and hardcode a single connection profile for the app in www/index.html e.g.: 

    www/index.html
    <script><font></font>
    $(function() {<font></font>
        var homeUrl = "https://joget.example.com/jw";<font></font>
        MobileApp.init(homeUrl);<font></font>
    });<font></font>
</script>

     

Customize Icons

  1. Replace the app icons:
  • res/AppIcon40x40.png
  • res/icon.png
  • res/logo_76x76.png
  • res/logo_120x120.png
  • res/logo_152x152.png
  • res/logo_167x167.png
  • res/logo_512x512.png
  • res/logo_1024x1024.png

Customize Splash Screens

  1. Replace the splash screens and screenshots:
  • res/splash_640x1136.png
  • res/splash_white_640x1136.png
  • res/screen/ios/Default@2x~universal~anyany.png
  • res/screen/ios/Default@2x~universal~comany.png
  • res/screen/ios/Default@2x~universal~comcom.png
  • res/screen/ios/Default@3x~universal~anyany.png
  • res/screen/ios/Default@3x~universal~anycom.png
  • res/screen/ios/Default@3x~universal~comany.png

Access Cordova Native Features

  1. Due to the cross-origin security restrictions on IFRAMEs and AJAX requests, Joget web apps need to be launched within Cordova's InAppBrowser.
  2. The Cordova app automatically inserts a JavaScript function cordovaAction(action, message) into the Joget web app, and this function can be called from the Joget web app to invoke actions in the Cordova app. 
  3. For the list of available actions, refer to MobileApp.cordovaAction in www/mobile.js. 
  4. Some examples of Cordova native features:
    1. Camera: Option to capture image directly from camera is automatically integrated to the file upload field.
    2. Offline: Offline and background sync functionality is automatically handled by the Joget PWA web app. Recent tests indicate offline support in the latest Android and iOS 15 versions.
    3. Geolocation: Call cordovaAction("geolocation") to prompt the app to ask for the user’s permission to access geolocation information.
    4. Vibration: Call cordovaAction("vibration") to vibrate the mobile device.
    5. Alerts: Call cordovaAction("alert", "message") to display a native alert message.
    6. Biometric: Biometric authentication supporting both fingerprint and Face ID available in the app using the cordova-plugin-fingerprint-aio plugin. 

 

Configure Mobile Push Settings

  1. Download and import the Joget Mobile Server app to your Joget server: https://github.com/jogetoss/mobile-push-plugin/blob/main/APP_jms.jwa.

  2. Update the Firebase project number (project_number in android-google-services.json), and mobile server URL in www/push.js:

    www/push.js
    CONFIG_SENDER_ID: "151651598697", // project_number from google-services.json
CONFIG_PUSH_SERVER_URL: "https://custom.mobile.example.com/jw/web/json/app/jms/plugin/org.joget.mobile.MobilePushPlugin/service",

Commit and Push GitHub Project

  1. Once all the customizations are complete, commit and push the changes to the GitHub project.

Building

To build the project, GitHub Encrypted Secrets are used for confidential information and files like the keys, certificates and passwords.

Enable GitHub Actions

  1. If you do not see an Actions tab in your GitHub repository, enable GitHub Actions in the repository Settings. 


Build Android App Using GitHub Actions

  1. In the GitHub project, add the following secrets:

    • ANDROID_KEYSTORE_BASE64 (convert android.keystore into base64 e.g. using the command: base64 android.keystore)
    • ANDROID_GOOGLE_SERVICES_JSON_BASE64 (convert the android-google-services.json into base64 e.g. using the command: base64 android-google-services.json)
    • ANDROID_KEYSTORE_ALIAS
    • ANDROID_KEYSTORE_PASSWORD
  2. In the GitHub project, go to Actions > Build Android > Run workflow.
  3. The Android build takes about 5 minutes.
  4. When the workflow run is completed, the APK and App Bundle will be available in the android-app-release.zip artifact.

Build iOS App Using GitHub Actions

  1. Edit the environment variables in .github/workflow/build-ios.yml to match your environment:

env:
  TEAM_ID: CQHX8VZ8F7
  PROVISIONING_PROFILE: Custom Mobile App Store
  IPA_FILE: Custom Mobile.ipa

      2. In the GitHub project, set the following secrets:

  • IOS_CERTIFICATE_BASE64 (convert the ios-certificate.p12 into base64 e.g. using the command: base64 ios-certificate.p12)
  • IOS_PROVISION_PROFILE_BASE64 (convert the ios-appstore.mobileprovision into base64 e.g. using the command: base64 ios-appstore.mobileprovision)
  • IOS_P12_PASSWORD
    • IOS_GOOGLESERVICE_PLIST_BASE64 (convert the ios-GoogleService-info.plist into base64 e.g. using the command: base64 ios-GoogleService-info.plist)

    3. In the GitHub project, go to Actions > Build iOS > Run workflow.

    4. The iOS build takes about 20 minutes.

    5. When the workflow run is completed, the IPA will be available in the ios-app-release.zip artifact, and the source XCode workspace in the xcworkspace.zip artifact.

Publishing

Publish Android App to Google Play Store

  1. Refer to the following resources to publish an Android app to the Google Play Store:

Note: From August 2021, new apps are required to publish with the Android App Bundle on Google Play.

Publish iOS App to Apple App Store

  1. Refer to the following resources to publish an iOS app to the Apple App Store:

Debugging

Debug Android App from Command Line

  1. Prerequisites: Java 11, Android SDK, Cordova

  2. To build and debug the Android app from the command line, run the following commands :

    Linux
    export ANDROID_SDK_ROOT=/path/to/Android/Sdk
export JAVA_HOME=/path/to/java-11-openjdk-amd64
PATH="$JAVA_HOME/bin:$ANDROID_SDK_ROOT/emulator/:$ANDROID_SDK_ROOT/cmdline-tools/latest/bin:$PATH"
cordova platform add android@10.1.2
cordova plugin add cordova-plugin-device@2.1.0
cordova plugin add @havesource/cordova-plugin-push@3.0.1
cordova plugin add cordova-plugin-splashscreen@6.0.1
cordova plugin add ./cordova-plugin-inappbrowser-download
cordova emulate android
     
    Windows
    setx ANDROID_SDK_ROOT "C:\path\to\Android\Sdk"
setx JAVA_HOME "C:\path\to\java-11-openjdk-amd64"
setx PATH "%JAVA_HOME%\bin;%ANDROID_SDK_ROOT%\emulator;%ANDROID_SDK_ROOT%\cmdline-tools\latest\bin;%PATH%"
cordova platform add android@10.1.2
cordova plugin add cordova-plugin-device@2.1.0
cordova plugin add @havesource/cordova-plugin-push@3.0.1
cordova plugin add cordova-plugin-splashscreen@6.0.1
cordova plugin add ./cordova-plugin-inappbrowser-download
cordova emulate android

Debug iOS App from Command Line

  1. Prerequisites: macOS, CocoaPods, Cordova

  2. To build and debug the iOS app from the command line, run the following commands (only macOS supported for iOS builds): 

    macOS
    cordova platform add ios@6.2.0
cordova plugin add cordova-plugin-inappbrowser@5.0.0
cordova plugin add cordova-plugin-device@2.1.0
cordova plugin add @havesource/cordova-plugin-push@3.0.1
cordova plugin add cordova-plugin-statusbar@3.0.0
cordova plugin add cordova-plugin-media-capture@4.0.0
cordova emulate ios
Created by Damian Last modified by Aadrian on Nov 19, 2024
Tags:
Previous Custom Mobile App Publishing