5: Building the IOS App

2022-08-09

This topic is under construction.

5.1 Introduction

This topic covers how to set up the FDA MyStudies iOS app and install and run it on an iPhone. This is section 5 of the overall setup process covered in: FDA MyStudies: Technical Setup Document

5.2 Requirements

5.2.1 IDE

Xcode 11 and above can be used to run application. You can install Xcode from the Mac App Store.

5.2.2 iOS

The application is supported only on iOS 13 and above versions.

5.3 Xcode Setup

After successful installation of xcode follow below steps:

a. Setup Developer Credentials

  • Open Xcode and go to Preferences.
  • Click on Accounts on top menu.
  • Click on the icon and Choose Apple ID.
  • Sign In with Apple developer account.
b. Change Bundle Identifier
  • Enter a new bundle identifier for your application.
  • Choose Code Signing to “Automatically manage signing” and Xcode will take care of registering the bundle identifier.
c. Enable for Push Notification Note: To learn more about Xcode and above setup, refer to Apple's official guide to Xcode Setup

5.4 How to Open Project in Xcode

  • Download the project from GitHub or clone.
  • To open a project in Xcode go to the project location on your Mac Machine and look for the file named “HPHC.xcworkspace” and double-tap on it.

5.5 How to Change Server URLs

Note: Once your registration is complete and the WCP & Response Server are set up, please follow the below steps.

5.5.1 Set up study and API configuration

After the application is set up on the WCP server and after creating the study (REFER SECTION: 8), you will need to add the following settings in "Default.xcconfig", shown in the image below.

  1. WCP_URL
  2. RESPONSE_URL
  3. REGISTRATION_URL
  4. APPLICATION_ID
  5. ORGANIZATION_ID
  6. STANDALONE_STUDY_ID
  7. USERNAME_KEY: This is ios.bundleid (Refer to section: 3.2.3)
  8. PASSWORD_VALUE: This is ios.apptoken (Refer to section: 3.2.3)

5.6 How to Build and Run

The application can be run on an iPhone Simulator OR iPhone Device.

5.6.1 Run on Simulator

To run on the simulator, select a simulator from the simulator listing and click on the Play button.

5.6.2 Run on Device

To build and run the application on your iPhone device, connect your phone with a power cable to the Mac machine.

The iPhone name will be listed under Device. Select 'iPhone' and click on the Play button.

5.7 How to Set Up a Standalone Study App

Note: You need to create the standalone study on the WCP server first & get the studyID. Once the standalone study setup is finished (REFER SECTION: 8) please follow the steps below:

1. Open the project workspace in Xcode.

2. Replace the StandaloneStudyId value with studyID in Info.plist

3. Make sure OrganizationID & ApplicationID is same in the Info.plist from the same WCP server.

4. Go to main target build settings & look for “standalone”

5. Under User-Defined, set the “IS_STANDALONE_STUDY” value to true for both debug and release.

6. Build and run the project.

5.8 Apply Your Branding

  • AppIcon & Launch Image
    • Replace your AppIcon and launch Images into Assets.xcassets under the AppIcon & LaunchImage respectively.
  • Change Display Information
    • There are some informational content items that can be directly changed at file level and are not required to be changed at the code level.
    • Look for file Branding.plist and change information appropriate to your application.
  • App Introduction Changes
    • App Introduction screen can also be changed at file level.
    • Look for GatewayOverview.plist file and change information appropriate to your application.

5.9 Next Steps

Continue with set up in the main document.

Appendix: Build at the Command Line

It may be desirable to build your MyStudies iOS app at the command line (rather than in the GUI of Xcode) as with CI/CD or other automation. This next section will serve as a brief overview and basic example of building and testing the iOS app using the Xcode CLI tool "xcodebuild". Refer to Github Actions configuration (.github/workflows/Build-iOS.yml) in the repo when configuring similar CI/CD automation on other platforms.

For the purposes of code validation, valid iOS code-signing is not necessary. Building with valid code-signing falls outside the scope of this guide.

These instructions assume Xcode 11 is being used from /Applications/Xcode_11.X.app.

Appendix.1 Set Xcode Code-Signing Environment Variables

The primary purpose of these is to disable code-signing:

export CODE_SIGN_IDENTITY=''
export CODE_SIGNING_REQUIRED='NO'

Appendix.2 Set Xcode Architecture Environment Variable

The following environment varaible limits the code to being compiled only for the CPU architecture of the machine running Xcode and is desirable to avoid building for iOS device architectures for the purposes of code validation:

export ONLY_ACTIVE_ARCH='YES'

Appendix.3 Change to the "HPHC" Directory Within the Repo

Some steps of the build process assume that you are in the "HPHC" directory, which is a sub-directory of the root of the repo:

cd HPHC

Appendix.4 Build

To build, use xcodebuild from the HPHC directory. You may need the full path to xcodebuild, and must substitute your platform, OS, and name settings in the -destination argument:

/Applications/Xcode_11.7.app/Contents/Developer/usr/bin/xcodebuild clean build -workspace HPHC.xcworkspace -scheme HPHC -destination "platform=iOS Simulator,OS=13.7,name=iPhone 11"

If you are using a GitHub Actions config instead of including the specific versions in the command string you could define a "matrix.destination" such as:

strategy:
matrix:
destination: ["platform=iOS Simulator,OS=13.7,name=iPhone 11"]

Then run, using syntax like:

xcodebuild clean build 
  -workspace HPHC.xcworkspace 
  -scheme HPHC 
  -destination "${{ matrix.destination }}"

Appendix.5 Test

xcodebuild test 
            -workspace HPHC.xcworkspace 
            -scheme HPHC 
            -destination "${{ matrix.destination }}"

References

Related Topics