PHP, Web and Mobile development

How to make your Ionic Cordova App to Run under Windows Phone 8.1 and Desktop

Indice della pagina

I was very upset the day that i remotely built my first Ionic mobile application using “Phonegap build” and then i figured out, after compiling the Windows version, that its was only compatible with the 8.0 platform that today is totally useless.

I had to take a long road to make everything at work (compile, run and debug) with Windows 8.1 with the APPX format. I will explain you here how i did it.

Building Environment

To build for windows 8.1 platform you need to install:

  • a windows 8.1 virtual machine;
  • all the windows 8.1 system upgrades;
  • the Windows Phone 8.1 SDK;
  • the visual studio community edition.

The latest version of visual studio will install nodejs and cordova for you.

When you’ve finished then you’re ready to tweak your cordova project files for windows.

I assume you’ve already have the sources of a working cordova application for Android or IOS.

Config.XML tweaks

First of all add your locale to the widget tag: <widget .... defaultlocale="it-IT">

Don’t touch the ID attribute or your app: if you do so then it will not be compatible with android and IOS; instead, the latest GIT version (or at least the version 4.1.0) has support for an additional setting that will work for windows store apps only:

<preference name="WindowsStoreIdentityName" value="MYcompany.MY_WINDOWS_STORE_APP_ID"/>

Since 4 september 2015, you can also use the attribute windows-packageVersion to specify a different version of the app for the windows package.

Also don’t forget you need lots of icons and splash version for windows, as minimum you need:

<platform name="windows">
<icon height="99" src="resources/icon/windows/ApplicationIcon.png" width="99"/>
<icon height="150" src="resources/icon/windows/logo.png" width="150"/>
<icon height="30" src="resources/icon/windows/smalllogo.png" width="30"/>
<icon height="50" src="resources/icon/windows/storelogo.png" width="50"/>
<icon height="106" src="resources/icon/windows/lumia630.png" width="106"/>
<icon src="resources/icon/windows/Wide310x150Logo.scale-100.png" width="310" height="150" />
<icon src="resources/icon/windows/Square71x71Logo.scale-240.png" width="170" height="170" />
<icon src="resources/icon/windows/Wide310x150Logo.scale-240.png" width="744" height="360" />
<icon src="resources/icon/windows/Square150x150Logo.scale-240.png" width="360" height="360" />
<icon src="resources/icon/windows/Square71x71Logo.scale-100.png" width="71" height="71" />
<icon src="resources/icon/windows/Square44x44Logo.scale-100.png" width="44" height="44" />
<icon src="resources/icon/windows/StoreLogo.scale-240.png" width="120" height="120" />
<icon src="resources/icon/windows/Square70x70Logo.scale-100.png" width="70" height="70" />
<icon src="resources/icon/windows/Square310x310Logo.scale-100.png" width="310" height="310" />
<splash height="1280" src="resources/screen/windows/SplashScreenImage.png" width="768"/>
<splash height="300" src="resources/screen/windows/SplashScreen.png" width="620"/>
<splash height="1920" src="resources/screen/windows/SplashScreenPhone.scale-240.png" width="1152"/>
</platform>

i use a simple script that uses ImageMagick to convert and resize all the icons and splashscreens into the correct formas from a single icon.png and splash.png file.

Cordova platform tweaks

After installing the windows platform in cordova with:

cordova platform add windows

If you have version older of 4.1.0 please update from the latest GIT or to 4.1.0 since the defaultlocale attribute and the WindowsStoreIdentityName preference are not available in older versions.

To upgrade using the latest GIT:

call cordova platform update --usegit windows@master

To upgrade from older version:

call cordova platform update windows@4.1.0

When you’re done you can execute:

call cordova prepare windows

Source code tweaking

To make your ionic or AngularJS app to execute correctly in windows 8.1 you need to include this extra javascript library from MSDN into the index.html file: https://github.com/MSOpenTech/winstore-jscompat

In your app.config, maybe, it will be necessary to add some more protocol to the sanitization urls list. I use this line of code to make Imgcache.js work:

$compileProvider.imgSrcSanitizationWhitelist(/^\s*(https?|http?|local|file|filesystem|blob|cdvfile|data):/);

Remember that on the windows platform you cannot use window.alert() to trigger any dialog box, you have to replace that with the cordova’s notification plugin function: navigator.notification.alert()

To detect if you’re app is running under windows (both phone and desktop) please use:

ionic.Platform.isWindowsPhone() || (ionic.Platform.platform() == 'win64')

since Ionic has no native function to detect the desktop version.

CSS fixes

I had issues using tabs in the footer displayed on a windows tablets.

Ionic say they does not support the window platform officially (yet). However i found this fix myself:

.platform-windowsphone .tab-item, .platform-windows .tab-item{
   max-width:none;
}

Plugin tweaking and making IMGcache.js to work

I was able to use successfully almost all my common plugins: cordova-plugin-console, cordova-plugin-device, cordova-plugin-dialogs, cordova-plugin-network-information, cordova-plugin-splashscreen, cordova-plugin-file, cordova-plugin-file-transfer.

Unlucky the plugin that i use for Google Analytics and Paypal does not have support for the windows platform.

Other libraries like localForage and angular-localforage works perfectly.

IMGcache.js does not works out of the box, because it fails to detect the window environment, then you have to fix the library yourself.

The guilty function is Helpers.isCordovaWindowsPhone. A quick fix will be returning the value like:
return (Helpers.isCordova() && device && device.platform && (  (device.platform.toLowerCase().indexOf('win32nt') >= 0) || (device.platform.toLowerCase().indexOf('windows') >= 0) ) );

I’ve send this suggestion on their github: https://github.com/chrisben/imgcache.js/issues/132 and it has been committed on october 2015.

Building

You can compile app to run on your device or for the Windows Store directly from cordova. You can skip using Visual Studio GUI and create batch files to compile the app from the command line. This means that you can also create your own private server to remotely build the app.

To build an APPX for a windows 8.1 phone, execute:

cordova build --debug windows --  --phone --appx=8.1-phone  --buildConfig build.json

To run the app:

cordova run --debug windows --device  -- --phone --appx=8.1-phone --buildConfig build.json

To build and run on a desktop just replace:

  1. --phone with --win
  2. --appx=8.1-phone with --appx=8.1-win

Don’t forget you can change also --debug with --release if you wish.

Remember that in order to run your APP onto the connected USB device it must be first unlocked with the tool provided by the Windows phone SDK.

Unlock the Windows Phone

So to run your app you need a few prerequisites:

  • you need a Microsoft account (hotmail, live, etc.);
  • you need a Developer Account (14€ personal, 75€ company) connected to it;
  • you need the phone connected via USB to the PC where the Windows 8.1 togheter with the windows phone SDK is installed;

then finally you can execute the Windows Phone Registration tool to unlock the device.

Build.Json

The build.json config file is necessary to inject the corrects attributes into the visual studio project in order your app to be accepted by the Windows store.

My build.json is this way:

{
   "windows": {
      "debug": {
         "packageCertificateKeyFile": "symantec2.pfx",
         "packageThumbprint": "9FE5E7F93E503D42A2432ABBCF9E558A831F853A",
         "publisherId": "OID.0.9.2343.19200300.100.1.1=10969218, CN=Bad Penguin, OU=Bad Penguin"
      },
      "release": {
         "publisherId": "CN=FE439BF5-00F4-4C61-9910-1E13B49EED16"
      }
   }
}

If i use the --debug switch it will use a symantec mobile certificate to sign the app so i can use it on “company” unlocked devices.

If i use the --release switch it will build and sign the app so that i can submit it to the windows store.

To use the build.json file add this command line switch to your compilation script: --buildConfig win.dist\build.json.

The published ID is available one you have payed for a developer account in your dashboard into the developer portal.

Debugging

Debugging is possible just opening with Visual Studio one of the projects available in the platforms/windows/ directory.

I tried to open the solutions instead of the project but i got some crash, maybe it has been fixed meanwhile.

In the project window i strongly suggest you to check the manifest file to see if all the icons and splash screens are correctly set.

More Hard More Fun

If you need more help or development, just contact me for a job or a quote.

Have fun, Antonio.

    ↑