Skip to main content

HealthShare Personal Community Mobile Application Guide




Document Controls

Personal Community Version Date of Last Update Version Status

2024.5

Friday, September 13, 2024

eg. 1.0
Commenced

1. Overview

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 .

2. Responsibility Matrix

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.
    • 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)
    • Manages relationships and accounts needed to publish the application to the app store.
    • Publishes the mobile application to the app stores.

3. Building the Personal Community Mobile Application with Capacitor

3.1. Environment Requirements

Version Dependencies

Building the mobile application for Personal Community requires specific versions of software.  Always ensure you are using the versions specified in this document, failure to due so may cause unexpected behavior in the application.

If you are building the application for iOS, your environment must be  macOS .

3.2. Installing NodeJS

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

Personal Community Version Node Version npm Version
2024.5 16.19.0 8.19.3

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 16.19.0
    nvm use 16.19.0
    
  4. On mac / Linux, run 
    nvm alias default 16.19.0
    
  5. Confirm your version of node.
    node --version
    # v16.19.0
    
  6. Confirm your version of npm.
    npm --version
    # v8.19.3
    
  7. If the npm version is not correct, install the correct version.
    1. On Mac/Linux
      npm install -g npm@8.19.3
      
    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 npm@8.19.3
        
      4. Verify the npm version
        npm --version
        # v8.19.3
        


3.3. Requirements for iOS

Building the mobile app for iOS requires macOS.  

Install the following dependencies:

3.3.1. Xcode

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

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. We need to install it 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. We 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.12.1

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. We can install Android Studio by going to the   Android Studio download page .
  2. An Android SDK installation

    1. Once Android Studio has been installed, we 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 22 or greater.
    3. In Android Studio, open   Settings , search for Android SKD .   from the menu and install the platform versions we would like to test with in the   SDK Platforms   tab.

3.5. Installing Base-Capacitor-Env

Personal Community makes a pre-configured repository available for creating the mobile application.  Contact the WRC to receive the repository and ReadMe file for installation.

Follow the steps in the ReadMe file to complete the following:

  1. Configuring Capacitor
  2. Running the Mobile App

4.  Publishing the App

For patients to be able to download and install the Personal Community mobile application, it must be published to an app store.  InterSystems has verified the process for publishing to Apple and Google Play.  Implementation should review the full documentation provided by each app store the customer wishes to publish with.

4.1. Required Information Needed

4.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

4.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.

4.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.

4.2. Building the App for Apple Distribution

The following steps are run within Xcode to build, sign, and publish the application.

4.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

4.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

4.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.

4.3. Building the App for Android Distribution

Publishing the app with Google Play Console requires a Google Developer account.  To publish, you can rely on Google to do the signing of the generated app bundle.

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

4.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.baseCapacitor,Env.app to set to your unique bundle identifier.
  3. Open the AndroidManifest
    1. Update the android:label to be the name of your application

4.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

4.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

4.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