Chapter 3. Windows

3.1. Deploying an App on Windows Phone 8

Different deployment options are available depending on the types of the Windows Phone 8 apps.

3.1.1. Non-company Windows Phone 8 Apps

Unless an app binary is signed by a Windows Phone company certificate, the app will be non-company app. Non-company Windows Phone 8 apps cannot be OTA installed on to devices directly.

3.1.1.1. Building

  • Using Visual Studio

    In Visual Studio, if no signing options are specified, the final binary will be a non-company app.

  • Using the App Studio

    When using the App Studio to build for Windows Phone, if the "Don’t sign the binary" option is selected, the final app binary won’t be signed and it will be a non-company app.

    image

3.1.1.2. Distribution & Deployment

Normally you will have two options to distribute and deploy this type of apps:

3.1.2. Company Windows Phone 8 Apps

A non-company app will become a company app once it’s been signed by a Windows Phone Enterprise Certificate. Company apps can be OTA installed on to devices directly and bypassing the app store completely.

To build company apps using the App Studio, you should follow these steps:

3.1.2.1. Acquiring the enterprise certificate

Following these steps to get your enterprise certificate:

  • Follow the steps in the Publish Windows apps guide to create a company Windows Phone developer account. Make sure the account type is "Company". This will cost $99 per year. It may take a few days to process as your company information will be validated.
  • Once your developer account is setup, visit the Enterprise Mobile Code Signing Certificate to apply for the certificate file. Specify the "Publisher ID" field as provided by your Windows Phone developer account. This will cost $299 per year.

  • Once the process is completed, Symantec will deliver a certificate that can be imported into the certificate store on a computer. See Certificate install instructions.

    Tip

    Use the same computer when requesting and picking up the certificate from Symantec.

  • Finally, you should export the certificate with its private key as a PFX file and protect it with a password. See the Export a Certificate with the Private Key guide for instructions.

Check out the Company app distribution for Windows Phone guide for more details.

3.1.2.2. Generating the application enrollment token (AET)

Only the phones enrolled in your company account can OTA install apps signed by your enterprise certificate. To enroll devices, you need to generate the application enrollment token (AET) and install it on those devices.

You can follow the steps in the How to generate an application enrollment token for Windows Phone guide to generate the AET file manually.

Alternatively, the App Studio can generate the AET file for you during the next step.

To install the AET file on to devices, the easiest way is to store the AET on a web server and ask your users to download it using their devices' web browser. The App Studio can help with that as you will see in the next few steps.

3.1.2.3. Creating a credential bundle for Windows Phone

Once the certificate is available, you can create a new credential bundle in the App Studio.

wp create credential bundle

As you can see in the screenshot, the App Studio can generate the AET file for you. However, if you have the AET file already, you can choose to upload it instead. If you choose to manage the AET file yourself, make sure the AET file is installed on your users' devices.

3.1.2.4. Build the app and sign it with the credential bundle

When building an app for Windows Phone in the App Studio, you will have the options to sign the app binary with the credential bundles you just uploaded.

image

3.1.2.5. Distribution & Deployment

Once the app finishes building, there will be OTA link and QR code on the download page to easily install it to the users' devices. If the AET file is available as part of the credential bundle, there will be download link & QR code for it as well.

image

3.2. Support for Windows Platforms

Red Hat Mobile Application Platfrom (RHMAP) supports the development of Client Apps for Windows-based devices. For a detailed tutorial, see Developing Forms Apps and Cordova Apps for Windows.

3.2.1. Supported Platforms

The current version of RHMAP targets Windows Phone version 8 and higher. Workarounds for platform-specific issues are provided further in this guide.

  • Windows 10 Universal Apps (Phone, Tablet and Desktop):

    • Full support, except:

      • Apps can’t be built in the RHMAP and must be built locally

  • Windows 8.1 Universal Apps (Phone, Tablet and Desktop):

    • Full support, except:

      • Apps can’t be built in the RHMAP and must be built locally
      • Cordova apps need a small workaround to enable support for dynamic content

  • Windows Phone 8.1:

    • Full support
  • Windows Phone 7,7.5 and older,
  • Windows 8 Pro for Tablets,
  • Windows 8 RT for Tablets,

3.2.2. Building Windows Apps Locally

Due to changes in Microsoft’s licensing of its development tools, it is currently not possible to build Apps for Windows 8.1 and Windows 10 directly in RHMAP. RHMAP apps for the affected platforms have to be built manually in your local development environment.

  1. First, clone the repository of your Client App. 

    git clone <Git_URL>
  2. Locate the solution file (.sln) in the project folder and open it in Visual Studio.
  3. In Visual Studio, select a solution configuration and platform and build the project by pressing the F7 key. For more details, see the official documentation: Building a Windows Phone app in Visual Studio.
  4. Once the build is finished, a binary with a .xap or .appx extension will be located at <project_name>/<solution_name>/Bin/<solution_configuration>. The binary file can be deployed to Windows devices or uploaded to the RHMAP App Store.

3.2.3. Enabling Dynamic Content in Cordova on Windows 8.1

On Windows 8.1, security restrictions are in place that prevent apps from using properties such as innerHTML and outerHTML. This in turn prevents any dynamic content to be injected and most JavaScript frameworks will therefore fail to function properly. This also prevents Cordova apps and RHMAP drag and drop apps from functioning.

A workaround for this issue is to reference a single JavaScript file provided by Microsoft, which relaxes the security restriction:

  1. Download the winstore-jscompat.js file: https://raw.githubusercontent.com/MSOpenTech/winstore-jscompat/master/winstore-jscompat.js.
  2. Copy the winstore-jscompat.js file into the www folder of your project

  3. Reference the file from any HTML that requires dynamic content manipulation. winstore-jscompat.js must be referenced before any other JavaScript framework including cordova.js or feedhenry.js. 

    <!-- above feedhenry.js or cordova.js-->
<script src="winstore-jscompat.js" type="text/javascript"></script>

For more information about this workaround, see the description in the MSOpenTech/winstore-jscompat repository.

3.3. Developing Forms Apps and Cordova Apps for Windows

Overview

This tutorial shows you how to create a Forms app targeting the Windows platform using Red Hat Mobile Application Platform Hosted (RHMAP). The same steps as demonstrated in this tutorial also apply to any Cordova app, not just Forms apps.

Currently, there are several issues preventing support for the Windows platform equivalent to the other platforms, as described in Support for Windows Platforms. Specifically, native Windows 8.1 and Windows 10 apps can’t be built by the Platform and have to be built manually. Also, Cordova apps need a small workaround to work properly in Windows 8.1.

Tip

This tutorial is also available as a quick video walkthrough.

Requirements

3.3.1. Steps

3.3.1.1. Initial Setup

  1. Download and install Node.js: https://nodejs.org/en/download/.

    There’s an installer available which guides you through the setup. Make sure to include the npm package manager in the installation. It’s a core component which will also be required further in this guide.

  2. Download and install a git client: https://git-scm.com/download/win/.
    Aside from the git executable itself, the installer of Git for Windows also provides an emulated Bash shell (called Git Bash) and a set of command-line tools in order to provide a familiar development environment. To learn more about the Git for Windows project, see the official website of Git for Windows.

    Note

    Most steps in this guide involving the use of command line can use cmd or PowerShell, unless otherwise noted. However, we suggest using the Git Bash command line installed in this step for all the steps.

  3. Install the Cordova package. 

    npm install -g cordova

    This installs the Cordova package including a cordova executable globally and thus makes it available to all Node.js applications.

  4. Clone the repository of your app from the Platform.

    Clone the repository of your app: 

    git clone <git-ssh-clone-url-of-your-app>

    The Git SSH Clone URL of your app can be found in the App Details.

3.3.1.2. Cordova Setup

Normally, Cordova projects are automatically created for your Cordova apps during build in the Platform and the Cordova-specific files and folders are not available in the app’s repository. However, when building manually, the Cordova files need to be created and command invoked manually.

Forms apps are based on Cordova and as such they need the same procedure for building as Cordova apps.

  1. Create a Cordova project.

    We use the name winforms in this example, but it can be an arbitrary name. 

    cordova create winforms --copy-from <location-of-forms-app>\www

    This creates a new Cordova project and copies the assets from the www directory into the newly created project’s www directory.

  2. Windows 8.1 only: Apply workaround for dynamic content manipulation in Cordova apps.

    See Enabling Dynamic Content in Cordova on Windows 8.1 for more information. 

    git clone https://github.com/MSOpenTech/winstore-jscompat.git
copy winstore-jscompat\winstore-jscompat.js forms\www

    The winstore-jscompat.js must be included in every HTML file in your Cordova app which does dynamic content manipulation. 

    <meta name="format-detection" content="telephone=no">
<!-- these three js files should be included exactly in this order -->
<script src="winstore-jscompat.js" type="text/javascript"></script>
<script src="cordova.js" type="text/javascript"></script>
<script src="feedhenry.js" type="text/javascript"></script>

  3. Add the windows platform to the Cordova project. 

    cd winforms
cordova platform add windows

    This creates all the source files necessary to build the binary, including a Solution File (.sln) which can be used to import the project into Visual Studio.

  4. Add the default Cordova plugins. 

    cordova plugin add \
    cordova-plugin-file \
    cordova-plugin-camera \
    cordova-plugin-file-transfer \
    cordova-plugin-device \
    cordova-plugin-network-information \
    cordova-plugin-battery-status \
    cordova-plugin-device-motion \
    cordova-plugin-device-orientation \
    cordova-plugin-geolocation \
    cordova-plugin-media \
    cordova-plugin-media-capture \
    cordova-plugin-dialogs \
    cordova-plugin-vibration \
    cordova-plugin-contacts \
    cordova-plugin-globalization \
    cordova-plugin-inappbrowser \
    cordova-plugin-console \
    https://github.com/fheng/fh-cordova-plugins-api.git

3.3.1.3. Building the Binary

The app binary can be built from the command line using Cordova or from Visual Studio and supports both Windows 8.1 and Windows 10.

To build using Cordova: 

cordova build

To build using Visual Studio, import the solution file (.sln) created in previous step into Visual Studio and build the solution. See Building Windows Apps Locally for details.

Cordova also provides the ability to start an emulator to quickly see the app running: 

cordova emulate