OMA Native PWA Wrappers

The OMA Progressive Web Application (PWA) provides a good user experience using common web technologies that can run on any platform supporting standards compliant browsers including PCs, tablets, and mobile devices. However, there are some usability features not yet supported with PWA technology such as running in the background, deep link interaction with third party apps, local device notifications, ability to bring itself to the foreground, ability to install or update using Device Management systems, and more. The OMA Native Wrappers is our solution to fill in the gap and provide these features. Use of OMA Native wrappers is optional and only required if one or more of the above gap items are important to your implementation.

OMA native PWA wrappers are supported on Android and iOS devices. A Windows wrapper is not available currently. The wrappers are small simple native applications built using native development tools requiring no additional third-party software. For the OMA PWA wrapper on Android, you will need an Android Studio development environment. For the OMA PWA on iOS, you will need a MacOS system with XCode and an Apple Development License.

The OMA PWA Wrappers are released as source code templates (OMAAndroidWrapper.zip and OMAiOSWrapper.zip) and located in the Oracle Utilities Network Management System Software Development Kit (SDK) $NMS_BASE/sdk directory.

PWA wrappers do not contain the OMA application, but instead are built with a configuration pointing to the OMA PWA server. When the wrapper is installed and initially launched, it will go the to OMA PWA server and download the latest version of OMA PWA into the wrapper's storage. Once the OMA PWAA is installed in the wrapper's storage, OMA PWA will be able to start and run while the device is off-line. If you have different versions on OMA PWA (for example, production, development, and test), you will need to build a wrapper for each of the locations where OMA PWA is served from. If you use the same OMA PWA to connect to different NMS instances (for example, production north, production west, and production south), you can configure OMA PWA to connect to each of these instances at login time; in other words, there is no need to have a different wrapper for each NMS instance. Once OMA PWA is installed in the wrapper's storage, on each subsequent launch of the wrapper, OMA will check for new versions of the OMA PWA and download them to the device so there is no need to rebuild/reinstall the wrapper to get OMA PWA updates.

Building and Deploying the OMA PWA Wrapper for Android

Follow these steps to build and deploy the wrapper:

1. Install the Android Studio software to your chosen development system. Android Studio is available for Windows, Mac, and Linux systems and can be downloaded from this website: https://developer.android.com/studio. The template is using Android Studio Flamingo (2022.1) and Gradle 8.0.

2. Copy the OMA PWA Wrapper for Android from the $NMS_BASE/sdk/OMAAndroidWrapper.zip file and unzip it on your development system.

3. Launch Android Studio and open the wrapper project (OMAAndroidNativeApp).

4. Configure the following in the wrapper template:

a. In the app/src/main/res/values/strings.xml file:

• Update the app_name. This is the name the app will have on the device including under the launch icon. If you are only going to have multiple wrappers printing to different OMA PWA servers, this should be unique (for example, OMA Production or OMA Development).

• Update the pwa_address to reference your OMA PWA server.

• Update the wrapper_version. This will appear on the About screens in OMA.

• Change channel_name and channel_description to be unique. These are used to setup the local device notification scheme.

b. If you want to change the icon for the app used in the launch icon or the notification icon, update the icons in the app/src/main/res/mip-map directories. Use instructions in the Android Studio "Create App Icons" section or use one of many online tools (for example, https://www.appicon.co/).

c. In the app/src/main/java/MainActivity.java file:

• Update the CHANNEL_ID and GROUP_NAME. These are used to setup the local device notification channel. If you are only going to have multiple wrappers printing to different OMA PWA servers, these should be unique for each wrapper.

d. In the app/src/main/AdroidManifest.xml file:

• If you are going to have multiple wrappers installed at the at the same on a device, you will need unique deep link schema names. Change android:schema name from nmsoma to something unique for each wrapper.

5. Build the wrapper by selecting Make Project from the Build menu.

6. Build the APK file by selecting Build Bundle(s)/APK(s) and then Build APK(s) from the Build menu. The generated APK (app-debug.apk) will be in the OMAAndroidWrapper\OMAAndroidNativeApp\app\build\outputs\apk\debug directory; use this to distribute your app. If you want to do more sophisticated APK generation (such as signing your app), refer to the Android Studio documentation.

7. To deploy your wrapper, you have many options. Here are some examples, you are not limited to these

a. Copy the APK to a web server and share a link to the APK with the users to click on and install on their device. Be sure the web server has the following mimetype.assign including: ".apk" => "application/vnd.android.package-archive".

b. Give the APK to your Device Management team to deploy to users.

c. Plug your Android device into your Android Studio Development environment and tap the Run/Run App menu option with your device selected in the app/device drop‑down list on the menu bar. This will install and run the app on your device.

Building and Deploying the OMA PWA Wrapper for iOS

Follow these steps to build and deploy the wrapper:

1. Install the XCode software to your MacOS development system. The template is using MacOS Monterey 12.6.3 and XCode 14.2.

2. Install your Apple Developer Credentials and provisioning files in XCode. Refer to Apple Developer and XCode documentation.

3. Copy the OMA PWA Wrapper for iOS from the $NMS_BASE/sdk/OMAiOSWrapper.zip file and unzip it on your development system.

4. Launch XCode and open the wrapper project by selecting Open… from the File menu, navigating to the unzip location, and opening the OMA_IOS_Wrapper.xcodeproj XCode project.

5. Configure the following in the wrapper template:

a. In the Info file:

• Expand the WKAppBoundDomains. Change the "item 0" value from oraclevcn.com to the domain name where your OMA PWA is served from. If the OMA PWA is served from https://systema.mouse.cat.animals.com, you need to at least include animals.com in this value. Refer to the Apple Developers documentation for more details.

• Expand the URL Types. If you would like to change the deep link used by OMA from "nmsoma://" to something else.. change the URL Identifier value and the URL Schemas/Item 0 value to what you want to use.

b. Assets: If you would like to change the icons used by the wrapper (launch icon, notices icon, …), update the Assets/AppIcons.

Refer to the Apple Developer documentation for more details. There are many free icon generator tools on line to help generate all the variants needed (https://www.appicon.co/).

c. ViewController: There are two locations where the OMA PWA URL needs to be specified, replace the template URL (https://ugbu...) with your URL. Be sure you keep the ?runInBrowser=true and ?runFromWrapper=true from the template URL.

6. Build the wrapper by selecting Build from the Product menu.

7. Build the ipa file:

a. Select Archive from the Product menu.

b. When the archiving is complete, an archives list will be displayed. From the list, select the latest archive and then click the Distribute App button. Select the method of distribution matching your Apple Developers License level (Enterprise), then click Next, and, on the distribution options panel, set App Thinning to None.

If you would like to use over-the-air method of installation, select the corresponding box, click Next, then fill in the over-the-air parameters for your installation website page, and click Next.

If you are not using the over-the-air method of installation, do not select the box and click Next. On the next panel, enter the signing method you would like to use and finish the rest of the dialog boxes. Finally, export the ipa package using the export button when it appears.

For more details, refer to the Apple Developers documentation.

8. You have many options to deploy your wrapper. Some examples include:

a. Copy the ipa file and over-the-air configuration to a web server as specified when creating the export. Users can then install the app by navigating to that URL.

b. Give the ipa file to your Device Management team to deploy to the users.

c. Plug your iOS device into your XCode Development environment and select Run from the Product menu to install and run the app on your device.

How to Issue a Local Notification from OMA When Using the PWA Wrapper

The OMA wrappers (iOS and Android) both support local notification functionality using the window.Android.notification API:

window.Android.notification ( id, title, text[, tap-deep-link])

where:

• id: index number to be used for the notification. For OMA, the store.js has a function to generate these: getNotificationId()

• title: Text string to use for the notification title

• text: Body text to use for the notification, supports \n's

• tap-deep-link: An optional deep link to call if the user taps the notification. For example, 'nmsoma://mainpage?page=tasks' would focus OMA on the task list page.