1. Developing Applications with Oracle JET
  2. Packaging and Deploying Applications
  3. Packaging and Publishing Hybrid Mobile Applications

Packaging and Publishing Hybrid Mobile Applications

You can use the Oracle JET command line tooling to package your hybrid mobile app for publishing to Google Play, Windows Store, or Apple App Store.

Topics

About Packaging and Publishing Hybrid Mobile Applications

The steps to package your app for release are broadly the same, irrespective of the platform where your app is going to be installed.

You create a build configuration file that identifies the location of your digital certificate, and then use the build configuration file as an input parameter to the ojet build command in order to sign your app with the digital certificate.

Before you proceed to signing and packaging your app for each platform where it will be used, review the entries in your app’s config.xml file, as described in Review Your Application Settings in the config.xml File. Once you complete that task, proceed to the platform-specific instructions in the following sections.

Packaging a Hybrid Mobile App on Android

To prepare your app for distribution on Android devices, you need to sign it using a digital certificate and package it into an .APK file.

To sign an app that you want to release and publish through the Google Play Store or some other distribution mechanism, you need a unique key. Your organization may provide you with one, in which case you specify its location in the build configuration file that you use to sign and package your app. If you don’t have a key, you can create one that you use to sign your app. Subsequent updates to your app must be signed using the same key that you create. You can create a self-signed key using the JDK’s keytool utility or using the dialogs that Android Studio provides from its Build > Generate Signed APK menu. For more information about the latter option, see the “Generate a key and keystore” section in the Sign Your App page on the Android developer’s site.

Once you have generated your key, specify the location of its store, its alias, and its access credentials in your build configuration file, as shown by the following example.

{
  "android": {
    "release": {
      "keystore": "/home/pathTo/keystore/android.jks",
      "storePassword": "MyKeystorePassword",
      "alias": "myAndroidKey",
      "password" : "MyKeyPassword",
      "keystoreType": ""
    }
  }
}

You can now package your app into an .APK file (the installation file type for apps on Android devices).

At a terminal prompt, in your app’s top-level directory, enter the following command:

ojet build android --release --build-config=/pathTo/yourBuildConfig.json

On successful completion, the terminal window displays output similar to the following:

...

...
 Oracle JET CLI
Running "build:release" (build) task
Running "oraclejet-build:release" (oraclejet-build) task
 Oracle JET Grunt plugin
Processing Grunt command...
 Oracle JET Tooling
cleaning staging path.....
...
BUILD SUCCESSFUL

Total time: 4.376 secs

Built the following apk(s):
        /appRootDir/hybrid/platforms/android/build/outputs/apk/android-release.apk
Cordova compile finished....

Done.

The build command outputs the .APK file that packages your app to the following location:

/appRootDir/hybrid/platforms/android/build/outputs/apk/android-release.apk.

Use this file to release your app through a public app marketplace, such as Google Play, a private app store, or some other means. End users who install your app from a location other than Google Play need to configure their device to opt in to install the app from an unknown source. For information about all these options, see https://developer.android.com/studio/publish/index.html#publishing-release.

Packaging a Hybrid Mobile App on iOS

To prepare your app for distribution on iOS devices, you need to sign it and package it into an .IPA file.

Joining the Apple Developer Program is the first step to submit your iOS app to the Apple App Store, to distribute an in-house app, or to sign an app that you distribute outside the Apple App Store. As a member, you have access to the resources you need to configure app services and to submit new apps and updates. For more information on the Apple Developer Program, see Apple Developer Program in Apple’s documentation.

Code signing your app allows users to trust that your app has been created by a source known to Apple and that it hasn’t been tampered with. All apps must be code signed and provisioned to deploy to an iOS device, to use certain Apple services, to be distributed for testing on iOS devices, or to be uploaded to the Apple App Store.

Signing identities are used to sign your app or installer package. A signing identity consists of a public-private key pair that Apple issues. The public-private key pair is stored in your keychain, and is used by cryptographic functions to generate the signature. A certificate stored in your developer account contains the associated public key. An intermediate certificate is also required to be in your keychain to ensure that your certificate is issued by a certificate authority.

Code signing requires that you have both the signing identity and the intermediate certificate installed in your keychain. When you install Xcode, Apple’s intermediate certificates are added to your keychain for you.

There are different types of certificates. A development certificate identifies a person on your team and is used to run an app on a single device. A distribution certificate identifies the team and is used to submit your app to the Apple App store or to distribute it outside of the store. Within an enterprise (organization) distribution certificates can be shared by team members in order to deploy various apps to a number of different devices. Certificates are issued and authorized by Apple.

If you are a member of an organization membership in the Apple Developer Program, you should request your team agent to provide your required signing identifies and certificates. Otherwise, you can create all the types of certificates and signing identities you need using the Apple Developer portal at https://developer.apple.com/account.

For more information on managing signing identities and certificates, see Code Signing in Apple’s documentation.

When you code sign an app, a provisioning profile is installed into the package that associates one or more certificates and one or more devices with an application ID. Provisioning profiles are created using the Apple Developer portal and must be downloaded and installed into Xcode on your development machine.

An application ID is a two-part string used to identify one or more apps from a single development team. The string consists of a Team ID and a bundle ID search string, with a period (.) separating the two parts. The Team ID is supplied by Apple and is unique to a specific development team, while the bundle ID search string is supplied by you to match either the bundle ID of a single app or a set of bundle IDs for a group of your apps.

Application IDs and devices are registered with your team account using the Apple Developer portal.

For more information on managing application IDs, devices and provisioning profiles, see Apple’s documentation.

Once you have created and installed the necessary code signing artifacts, specify the details in your build configuration file, as shown in the following example:

{
  "ios": {
    "debug": {
      "provisioningProfile": "My Developer Provisioning Profile ID",
      "developmentTeam": "My Team ID",
      "codeSignIdentity": "iPhone Developer",
      "packageType": "development"
    },
    "release": {
      "provisioningProfile": "My Distribution Provisioning Profile ID",
      "developmentTeam": "My Team ID",
      "codeSignIdentity": "iPhone Distribution",
      "packageType": "enterprise"
    }
  }
}

You can now package your app into an .IPA file (the installation file type for apps on iOS devices).

At a terminal prompt, in your app’s top-level directory, enter the following command:

ojet build ios --device --release --build-config=/pathTo/yourBuildConfig.json

On successful completion, the terminal window displays output similar to the following:

...
** ARCHIVE SUCCEEDED **


Exported appName.xcarchive to: appDir/hybrid/platforms/ios/build/device

** EXPORT SUCCEEDED **


Cordova compile finished....

Done.

The resulting .IPA file will be located at: 

appDir/hybrid/platforms/ios/build/device/appName.ipa

This file can be deployed to an iOS device that matches the installed provisioning profile using iTunes, or you can release your app through the public marketplace, Apple App Store, a private app store, or some other means.  For information about submitting your app to the Apple App Store, see Distribute an app through the App Store in Apple’s documentation.

Packaging a Hybrid Mobile App on Windows

To prepare your app for distribution on Windows devices or submission to the Windows Store, you need to sign it and package it into an .APPX file.

To complete this task, you need access to a digital certificate (a .PFX file) to sign your app. You must also create a build configuration file (build.json) where you specify the location of the digital certificate and a number of other parameters. You use the build.json file as an input parameter to the ojet build command that JET uses to package your app for Windows.

How to Create the Build Configuration File to Package Your App on Windows

You need to create a build configuration file in JSON format that passes details, such as the location of your PFX file, to the ojet build command that JET uses to package your app for Windows.

The following example build configuration file shows sample entries that you can use to package an app in debug and release mode. 

{
    "windows": {
        "debug": {
            "packageCertificateKeyFile": "C:\\AppRootDir\hybrid\platforms\windows\CordovaApp_TemporaryKey.pfx"
        },
        "release": {
            "packageCertificateKeyFile": "c:\\path-to-key\\keycert.pfx",
            "packageThumbprint": "ABCABCABCABC123123123123",
            "publisherId": "CN=Doc Example,OU=JET,O=Oracle,C=US"
        }
    }
}

Create your build.json file using the previous example as a reference. For information about creating and installing a PFX file, see todo. Obtain the values for the packageThumbprint and the publisherID entries by running the following command in a PowerShell command window: 

Get-PfxCertificate -FilePath "c:\path-to-key\keycert.pfx"

PowerShell prompts you for the PFX file’s password if the file is password protected. Output similar to the following then appears:

Thumbprint                          	     Subject
----------                                 -------
702F25BA3FED453A3F8ADCC13900A6353703AB54   CN=Doc Example, OU=JET, O=Oracle, C=US

For more information about the Get-PfxCertificate command, see Microsoft’s documentation.

How to Build Your App for Windows

Execute the ojet build command with the release flag from your app’s top level directory to build the app.

You must specify the architecture that you want the app to target when you package the app for release, as demonstrated by the following example that targets the x64 and x86 architectures.

ojet build windows --release --platform-options="--archs=\"x64 x86\"" --build-config=pathTo\build.json

On successful completion, the following directory contains the application package and other resources for your app:

AppRootDir\hybrid\platforms\windows\AppPackages\

The AppPackages directory contains another directory (CordovaApp.Windows10_*_Test). The actual name of the directory depends on the version number of your app and the architecture that it targets. For example, a version 1 app that targets the x64 architecture will be named CordovaApp.Windows10_1.0.0.0_x64_Test.

Submit the application package (.appx) in the directory to the Windows App Store or distribute the contents to end users with Windows devices who want to install your app. The directory includes a PowerShell script (Add-AppDevPackage.ps1) that end users execute to install the application. In addition to the script, the directory contains dependent packages and the certificate that signed the application. The following example lists the contents: 

Add-AppDevPackage.ps1                                 
Add-AppDevPackage.resources
CordovaApp.Windows10_1.0.0.0_x64.appx
CordovaApp.Windows10_1.0.0.0_x64.cer

For information about how to submit your app to the Windows Store, see https://developer.microsoft.com/en-us/store/publish-apps.