Personal Community is designed as a fully responsive web application. Additionally, organizations can deploy Personal Community as a mobile application available on various app stores.

This guide outlines how to leverage the mobile application framework to build and deploy the hybrid mobile application. Hybrid mobile apps are developed using web technologies such as HTML, CSS, and JavaScript but are wrapped in a native container, allowing them to be installed on mobile devices and accessed through app stores.

Personal Community uses Capacitor to create the hybrid mobile application. Capacitor is a cross-platform app runtime that provides a native bridge for web apps, enabling you to build and deploy mobile applications using web technologies. Capacitor allows you to:

• Access native device features using a simple API.
• Deploy your application as a native app on multiple platforms, including iOS and Android.

To learn more about Capacitor, visit the official Capacitor documentation .

Ownership of the mobile application is shared across three parties:

• Core Personal Community Development
  • Ensures the application functions as intended when deployed to iOS or Android devices.
  • Conducts yearly reviews of the application with Apple and Google to ensure it meets their publishing guidelines.
• Implementation
  • Deploys the mobile application for each customer using Capacitor.
  • If implementing push notifications, creation and management of Firebase project for push notification support. 
  • Manages the deployment of the mobile application as part of Personal Community upgrades.
  • Publishes the mobile application to the app stores (this may be handled by the customer).
• Customer (if not handled by implementation)
  • If implementing push notifications, creation and management of Firebase project for push notification support. 
  • Manages relationships and accounts needed to publish the application to the app store.
  • Publishes the mobile application to the app stores.

3.2. Installing NodeJS

Ensure you are using the correct version of NodeJS for the version of Personal Community you are using.  

Use the following steps to install:

1. Uninstall any other versions of node that are currently on the system.
2. Download and install node version manager (nvm) and use it to install the appropriate node version.
   1. On Mac/Linux, download and install nvm from:  https://github.com/creationix/nvm
   2. On Windows, download and install nvm from  https://github.com/coreybutler/nvm-windows/releases/download/1.1.7/nvm-setup.zip
3. Using the terminal of your choice, install node.

   nvm install 22
   nvm use 22
   

4. On mac / Linux, run 

   nvm alias default 22
   

5. Confirm your version of node.

   node --version
   # v22.x.x
   

6. Confirm your version of npm.

   npm --version
   # v10.9.8
   

7. If the npm version is not correct, install the correct version.
   1. On Mac/Linux

      npm install -g [email protected]
      

   2. On Windows
      1. Delete the following files from the nvm\[node version]   folder (e.g. C:\Users\[user name]\AppData\Roaming\nvm\10.15.1)

         C:\Users\[user name]\AppData\Roaming\nvm\[node version]\npm
         C:\Users\[user name]\AppData\Roaming\nvm\[node version]\npm.cmd
         C:\Users\[user name]\AppData\Roaming\nvm\[node version]\npx
         C:\Users\[user name]\AppData\Roaming\nvm\[node version]\npx.cmd
         

      2. Rename the underlying node_modules\npm folder to npm2

         C:\Users\[user name]\AppData\Roaming\nvm\[node version]\node_modules\npm2
         

      3. Open any console with admin rights, and type the following commands

         cd C:\Users\[user name]\AppData\Roaming\nvm\[node version]\node_modules\npm2\bin
         node npm-cli.js i -g [email protected]
         

      4. Verify the npm version

         npm --version
         # v10.9.8
         

3.3. Requirements for iOS

Building the mobile app for iOS requires macOS.  

Install the following dependencies:

3.3.1. Xcode Version and Minimum OS Version

Xcode is Apple's IDE for creating native macOS, iOS, and iPadOS applications. Install Xcode by using the Apple App Store on your Mac.

For Personal Community versions with a minimum OS version defined below, the minimum version should not be modified in Xcode. 

3.3.2. XCode Command Line Tools

The Xcode command line tools are additional tools not included with the core of Xcode that are required for building and testing our application. Once Xcode has been installed,  install the Xcode Command Line Tools by running the following command in the terminal:

xcode-select --install

V erify that the tools are installed.

xcode-select -p
# /Applications/Xcode.app/Contents/Developer

3.3.3. Homebrew

Homebrew is a package manager for macOS packages. It is needed in order to install CocoaPods. To install Homebrew, run the following bash command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3.3.4. Cocoapods

Cocoapods is an iOS dependency manager that Capacitor uses to install and manage native dependencies for the iOS project. You can install   CocoaPods   by running the following command in the terminal:

brew install cocoapods

V erify that CocoaPods has installed correctly by running the following command :

pod --version
# 1.16.2

3.4. Requirements for Android

Install the following dependencies to build the mobile application for Android:

1. Android Studio

   1. Android Studio is Google's IDE for creating native Android applications. You can install Android Studio by going to the   Android Studio download page .
   2. After upgrading Android Studio, run Tools → AGP Upgrade Assistant

2. An Android SDK installation

   1. Once Android Studio has been installed, you need to install an Android SDK package.
   2. Developing Android apps requires some Android SDK packages to be installed. Make sure to install the Android SDK Tools, and a version of the Android SDK Platforms for API 23 or greater.
   3. In Android Studio, open   Settings , search for Android SKD .   from the menu and install the platform versions you would like to test with in the   SDK Platforms   tab.

The following limitations apply to push notification support:

• Two-factor authentication – Push notifications are not supported for 2FA. Verification codes can only be delivered by email or SMS.
• Deep links – Push notifications do not support deep links or navigation to specific pages within the application.
• Urgent notifications – Push notifications cannot bypass device settings such as Silent mode, Do Not Disturb, or Focus modes.
• In-app notifications – Notifications are delivered through the device's push notification service only. In-app notifications are not supported.
• Shared devices – Push notifications are intended for devices used by a single patient. Multiple patients sharing the same device are not supported.

4.2. Prerequisites

Before you begin, ensure you have:

• Created a Firebase project .
• A paid Apple Developer account (required for iOS).
• Installed and have access to the base-capacitor-env project.

4.3. Configure Base-Capacitor-Env and Firebase Project for Push Notifications

4.3.1. Android

1. In the Firebase Console, register the Android application .
   1. Select Android to add the Android app.
   2. Use the application's package name ( appId in capacitor.config.json ) as your Android package name .
   3. Select Register app . 
2. Download the google-services.json configuration file. 
3. Copy google-services.json into the application's app directory under android/app/ .

4.3.2. iOS

1. In the Firebase Console, register the iOS application .
   1. Select iOS within Add App to add the iOS app. 
   2. Use the app's bundle id ( appId in capacitor.config.json ) as the iOS bundle ID . 
   3. Select Register app . 
2. Download the GoogleService-Info.plist configuration file.

   This is not the same file used for the Android app. 

   1. Open the project in Xcode:

      npx cap open ios
      

   2. Drag GoogleService-Info.plist into the Xcode project   as instructed by Firebase, ensuring to add it to all targets.

      Add the file using Xcode. Do not copy the file into the project directory.

4.3.2.1. Configure Apple Push Notifications (iOS)

A paid Apple Developer account is required to configure push notifications for iOS.

1. In the Apple Developer Portal:
   • Update the required development and production certificates and provisioning profiles   to support push notifications.
   • Create an  APNs Authentication Key .
2. Enable Push Notifications in Xcode:
   1. Open the application in Xcode.
   2. Select the application target and enable the  Push Notifications capability . 
      1. Ensure the   Push Notifications   capability is enabled for at least the   Release   configuration. Xcode allows you to enable the   Push Notifications   capability for   Debug ,   Release , or both.
3. Upload the APNs Authentication Key :
   1. In the Firebase Console, navigate to the iOS application →  Settings page → Cloud Messaging.
   2. Under the iOS app configuration , upload the APNs Authentication Key or APNs Certificate.

4.3.3. Enable Push Notification Code

1. Locate all optional push notification code by searching for the PUSH_OPTIONAL marker: 

   rg "PUSH_OPTIONAL"
   

2. Uncomment the PUSH_OPTIONAL blocks
3. Ensure the following files are changed:

   File	Required Change
   AndroidManifest.xml	Uncomment the POST_NOTIFICATIONS permission.
   AppDelegate.swift	Uncomment the Firebase imports, FirebaseApp.configure() , and the APNs delegate callback implementations.

4. Sync after uncommenting the above code:

   npx cap sync
   

A set of interoperability credentials for your Firebase project must be created for configuration in the Personal Community production. 

First, generate a private key in your Firebase project:

1. Navigate to the Firebase console for your Firebase project.
2. In the Firebase project, go to Settings → General → Service Accounts .
3. Select Generate a new private key .
4. Using a text editor (e.g. VSCode), open the private key file and modify it so it is only on one line.

Next, register your Firebase interoperability credentials:

1. Logon to the Management Portal as a user with the  %EnsRole_Adminstrator  role.
2. Change to the Personal Community namespace. (This uses the   Switch  link, which is at the top of the Portal.)
3. Navigate to  Interoperability > Configure > Credentials.  This displays the  Credentials Viewer  on the right.
4. In the  Credentials Viewer , enter the following values for the fields:
   • ID  - Enter "FCM"
   • User Name  - Enter "Service_Account"
   • Password  - Enter the content of the private key you modified to be only one line.
   • Business Partner  - This field is not relevant. Do not enter any value here.
5. Select  Save   to save these credentials.

To create an SSL/TLS configuration on your instance of Personal Community:

1. Log into the Management Portal for Personal Community as a user with the   %EnsRole_Administrator   role and switch to the Personal Community namespace.

2. Go to the   SSL/TLS Configurations   page ( System Administration   >   Security   >   SSL/TLS Configurations ) and select   Create New Configuration .

3. Enter a name of your choice for the configuration.

4. Make sure that the configuration is enabled: the   Enabled   checkbox should already be selected.

5. For   Type , make sure that   Client   is selected.

6. For   Server certificate verification , make sure that   None   is selected.

7. For   Protocols , make sure that   TLSv1.1   and   TLSv1.2   are selected.

8. Select the   Save   button to save the new configuration.

To enable push notification delivery, you must configure the business process and business operation responsible for routing notifications to Firebase Cloud Messaging (FCM).

To configure your Personal Community production for push notifications:

1. Log on to the Management Portal for Personal Community as a user with the %EnsRole_Administrator role.
2. In your Personal Community namespace, go to the Production Configuration page. Specifically:
   1. Go to your Personal Community namespace by selecting Switch from the title bar and choosing its name in the namespace chooser.
   2. From the Management Portal, select Interoperability > Configure > Production .
3. Set up the business operation:
   1. Under   Operations , select the   +   icon, to add a new business operation. This displays the   Business Operation Wizard .

   2. Select the HSPortal.Production.Operation.PushNotificationOperation   item in the page and do the following:

      1. Fill in the Operation Name field with the following: HSPortal_PushNotificationOperation .

      2. Select the  Enabled  check box and then select the  Apply  button to enable the component

   3. After you add the operation, set its property values as follows:

      1. Under  Basic Settings :

         1. FCMCredential – Select the Firebase credentials configured in the previous section.
         2. LockTimeout – The timeout used to coordinate OAuth access token refresh operations. By default this timeout is 5 seconds. Adjust this based on your testing of the timing to receive the OAuth response from FCM.
         3. SSLConfig – Specify the SSL/TLS configuration used to establish secure communication with Firebase Cloud Messaging. This should be set to a  valid SSL configuration that allows outbound HTTPS communication with FCM.
         4. ReplyCodeActions – Set this property to E*Retry=R,E=F .
         5. Select OK to save the business operation.
4. Set up the business process:
   1. Under   Processes , select the   +   icon, to add a new business process. This displays the   Business Process Wizard .

   2. Select the HSPortal.Production.Process.PushNotificationProcess item in the page and do the following:

      1. Fill in the Process Name field with the following: HSPortal_PushNotificationProcess .

      2. Select the  Enabled  check box and then select the  Apply  button to enable the component

   3. Modify its property values as follows:
      1. SubmissionTarget – Select HSPortal_PushNotificationOperation .
      2. TokenStalenessDays – The number of days a device registration token can remain inactive before it is considered stale and automatically deactivated. By default this is 30 days.
      3. Select OK to save the business process.

For every notification process that should be able to trigger a push notification, you must configure your Push Notification Operation as the target:

1. Select each of the following processes if they are configured for use in your environment:
   1. HSPortal_ActivationNotificationProcess (classname: HSPortal.Production.Process.ActivationNotificationProcess) – Provides notification of the account activation workflow to the patient. 
   2. HSPortal_InvitationsNotificationProcess (classname: HSPortal.Production.Process.InvitationsNotificationProcess) – Provides invitation to enroll to the patient.
   3. HSPortal_MessageNotificationProcess (classname: HSPortal.Production.Process.MessageNotificationProcess) – Provides notification of new messages to the patient. 
   4. HSPortal_PasswordNotificationProcess (classname: HSPortal.Production.Process.PasswordNotificationProcess) – Provides notification of forgotten or expired credentials to the patient. 
   5. HSPortal_SelfEnrollmentNotificationProcess (classname: HSPortal.Production.Process.SelfEnrollmentNotificationProcess) – Provides notification of the self-enrollment process to the patient.
   6. HSPortal_TaskNotificationProcess (classname: HSPortal.Production.Process.TaskNotificationProcess) – Provides notification of new tasks to the patient.
2. For each of the above processes, modify their property values as follows:
   1. PushNotificationTarget – Select HSPortal_PushNotificationOperation .
   2. Select OK to save the business process.

To ensure reliable push notification delivery and ongoing maintenance of device registration tokens, configure the scheduled tasks described below.

4.4.6.1. Configure the OAuth Warm-up Task

The OAuth Warm-up Task periodically refreshes the Firebase Cloud Messaging (FCM) OAuth access token. Keeping the token cached minimizes authentication overhead and avoids delays when notifications are sent.

It is recommended that this task runs every  15 to 30 minutes .

To configure the OAuth Warm-up Task:

1. Log into the Management Portal as a user who has a role with the %Admin_Operate:Use privilege.

2. Go to the  Task Scheduler Wizard  page ( System Operation  >  Task Manager  >  New Task )

3. On the  Task Scheduler Wizard  page, specify values for the fields as follows:

   1. Task Name  — Specify the name that you wish the task to have.

   2. Namespace to run task in — Select the namespace that your instance of Personal Community is using. If you have followed the example of the installation guide, this is HSPC.

   3. Task Type  — Select OAuth Warm-up Task.

4. Once you have completed the fields on this page, select  Next . This displays the page of the wizard for specifying how frequently the task runs.

5. On this page, specify how often the Task Manager runs the task, as well as other scheduling constraints.

6. Select  Finish . This adds the task to those scheduled to run, and displays the  Task Schedule  page, where the task is now listed. (To go directly to the  Task Schedule  page, select  System Operation  >  Task Manager  >  Task Schedule .)

4.4.6.2. Configure the Stale Token Cleanup Task

The Stale Token Cleanup Task periodically reviews registered device tokens and deactivates tokens that have not been refreshed within the configured inactivity period.

It is recommended that this task runs once daily during off-peak hours.

To configure the Stale Token Cleanup Task:

1. Log into the Management Portal as a user who has a role with the %Admin_Operate:Use privilege.

2. Go to the  Task Scheduler Wizard  page ( System Operation  >  Task Manager  >  New Task )

3. On the  Task Scheduler Wizard  page, specify values for the fields as follows:

   1. Task Name  — Specify the name that you wish the task to have.

   2. Namespace to run task in — Select the namespace that your instance of Personal Community is using. If you have followed the example of the installation guide, this is HSPC.

   3. Task Type — Select Stale Token Cleanup Task .

      1. Selecting this task displays the following field:
         1. TokenStalenessDays – The inactivity period, in days, that is used to deactivate tokens that have not been refreshed. If no value is provided here, the default value of 30 will be used.

4. Once you have completed the fields on this page, select  Next . This displays the page of the wizard for specifying how frequently the task runs.

5. On this page, specify how often the Task Manager runs the task, as well as other scheduling constraints.

6. Select  Finish . This adds the task to those scheduled to run, and displays the  Task Schedule  page, where the task is now listed. (To go directly to the  Task Schedule  page, select  System Operation  >  Task Manager  >  Task Schedule .)

Complete the following steps to set the following global:

1. Make the following terminal call in your Personal Community namespace:

   Set ^HSPortal.ConfigD("MobileAppOAuthRedirectURL") = "iscinternal.basecapacitorenv.app://oauth/callback"
   

   1. Replace " iscinternal.basecapacitorenv.app " with your   app bundle ID of base-capacitor-env repo in all lowercase .

6.1.1. Application Items Need Prior to Building a Release

Prior to building the application for release, the following information will be needed:

• Unique name for the application on the app store (bundle id)
• Display name for the application 
• App Icons for the application → customers may provide implementation with one PNG and online tools can be used to create
• Account access for implementation to assist with publishing

6.1.2. Marketing Materials 

Publishing to the app store requires designing and providing the information needed to create a store listing.  This includes:

• A minimum of 3 screenshots of the application.  These will need to be captured at different sizes to fulfill both the Apple and Google Store requirements
• Feature Graphic - This is required for the Google Play store.

6.1.3. Privacy and Security Materials 

Both Apple and Google require a set of attestations and privacy policies in order to publish the application.  Implementation should review what is needed for the desired stores and ensure the customer provides the appropriate links and materials well in advance of publishing.  This includes, but is not limited to:

• Privacy policy URL
• Content Rating
• Target Audience
• Data safety attestation
• Digital Services Act Attestation (Apple)

Both Apple and Google walk the user through completing all the information needed to publish the app to their store.

6.2.1. Setting the Application Name and Version in Xcode

In Xcode, navigate to the General setting.  In Identity, set the following:

1. Display Name → Display name for your application
2. Bundle Identifier → The unique identifier for this app on the app store
3. Version → The major version of the published app
4. Build → the minor version of the published app

Select the Info file in your App project.  On the Information Property List, set the following:

1. Bundle display name → Display name for your application

6.2.2. Setting your App Icons

These steps assume you have created the appropriate assets catalog for your app icon.

From Xcode:

1. Select your project from the left
2. Right click → Add new file → choose Asset Catalog
   1. Upload your asset catalog
3. Confirm all app icons are present

6.2.3. Publishing the App to App Connect

In XCode, run the following to publish the app to App Connect

1. Select Project → Archive
2. When this completes, you have the option to Validate App or Distribute App
3. Select Distribute App and choose a distribution model.

From App Connect, you can now see this build of the application and can initiate testing, the review process, or publishing.

The Google Play Console will only take apps that meet the following requirements:

1. Are serving API requests of HTTPS → ensure you are configured to use an HTTPs endpoint
2. Is built using the release variant

6.3.1. Setting the Application Name and Version

In Visual Studio we will set the name and the version of the app.

1. In your project, navigate to android/app/build.gradle
   1. set versionCode as appropriate → This will need to be updated on every release published to the console
   2. set versionName as appropriate
2. Execute a find and replace for iscinternal.baseCapacitorEnv.app to set to your unique bundle identifier.
3. Open the AndroidManifest
   1. Update the android:label to be the name of your application

6.3.2. Setting your App Icons

In Android Studio, navigate to your app/res directory.  To add icons:

1. Right click
2. Select New → Image Asset
3. From the editor, change the file path to the path of your app icons

6.3.3. Building and Signing the App

In Android Studio:

1. Sync gradle files (File → Sync Project with Gradle Files)
2. Open the Build Variants tool bar
   1. View → Tool Windows → Build variants
   2. Set Active Build Variant to release
3. Build the app bundle
   1. Build → Generate Signed App Bundle / APK
   2. Follow the prompts to sign the application

6.3.4. Google Play Console

Once you've built your bundle you can upload to the Google Play Console for internal, closed, open testing, and to publish for release.

1. Configure the testing group for your test
2. Create a new release of your application → Choose the option to let Google sign the release
3. Upload your app-release bundle
4. Assign your testers