Hands on the Apache Cordova plugin “Multi-Device Hybrid Apps” integrated in Visual Studio 2013 Update 2

The last April 2014 at Build 2014, beside the announcement of Xamarin support in Visual Studio, MicroSoft announced another extension that looks promising, the called “Multi-Device Hybrid Apps” which is a plugin for Visual Studio 2013 Update 2. Multi-Device Hybrid Apps with Visual Studio 2013

“Multi-Device Hybrid Apps” allows you to develop for multiple devices with the same source (HTML/JS/CSS) using Visual Studio as your IDE.

 

Note: We’re going to use the CTP 1.1. version of the plugin for the scope of this post, you can download the plugin here, (there’s a lot of broken links for this resource but this one is working today June 16, 2014).

Installation

Steps for installation:

  1. Windows 8.1
  2. You need Visual Studio 2013 Update 2 — You’ll really need the Update 2, if not you’ll be blocked like in the following image:                                                                  blocked
  3.    Download the plugin from here.
  4. Install the “Tools for Mantaining Store apps for Windows 8” and “Windows Phone 8.0 SDK” (if you don’t have it, like me, it will take more than a couple of minutes to download and install).                                     Selection                                                                                                                                                                                                    Yeah you will need to install those two items that you always skip : P, bad news: the Windows Phone 8.0 images will take a lot of time to download.
  5. After you have all the requirements, its time to install the plugin, piece of cake.
  6. 6- The instalation will ask you to install a lot of Third Party Dependencies like Joyent Node.js (that you need in order to use the Apache Cordova CLI), Java JDK, iTunes and other stuff that you may need in order to take full advantage of the plugin (or at least that’s what the documentation says, but yeah, I almost have everything installed because of my previous Cordova apps, it’s really nice that this installer does all the dirty work for you, cool MS!). plugins

Notes: In order to test your app in the Windows Phone Emulator your machine should be able to run MS hyper V. 3 hyper v

Config Designer

The “Multi-Device Hybrid Apps” provides a manager for the configuration and plugins of your app, it’s really easy to install or uninstall a plugin via the Config Designer. It’s worth nothing that the Config Designer is just modifing the config.xml file of your application. Finally after a millennium installing all the requirements,  you’re ready to at least launch the sample application.

  1. Open VS 2013
  2. Create a New Project
  3. Choose the “Multi-Device Hybrid Apps” template from the JavaScript or TypeScript templates (same template, different “language”)
    js or ts
    I had trouble installing joyent node.js though
  4. After the solution is created your Solution Explorer should look like this:
    2014-06-17_151224
  5. By default Apache Cordova will serve index.html as the first page or “view” when the app is started up. Feel free to modify this HTML page so you can feel that we did something 😛
    sample
  6. Next Build your App
  7. Pressing F5 will launch a chrome browser with Apache Ripple simulator, with this simulator you’ll be able to see how you app will be “rendered” in a variety of devices like Nexus 4, Nokia N8, iPhone 3g, iPhone 4g, iPhone 5 and even ipads and other tablets, this is a nice feature that will help you to speed up your development, also maybe it will be useful for regression testing with tools like selenium. Although the ability to see how the apps will be “rendered” across multiple devices in the simulator is really useful, there’s a big need for a debugger, this will be covered in another section.

Debugging with the Apache Ripple simulator

It’s possible to debug apps with the Ripple simulator, for this version of the Multiple-Device hybrid Apps plugin you can debug out of the box:

Let’s try it quickly:

  1. Go to Visual Studio
  2. Open the file index.js
  3. add the following function:
        function demoFunction() {
    
            var randomObject = {
                hello: "World"
            };
    
            console.log(randomObject);
    
        };
    
    

    After adding the function just bellow the “onResume” function, add a breakpoint in the console.log line.

  4. At the end of the “onDeviceReady” function add the following call:
         // TODO: Cordova has been loaded. Perform any initialization that requires Cordova here.
         demoFunction();
    
  5. Press F5 in Visual Studio and lets see what happen.

debug

As you can see, we can inspect the value of the plain JavaScript object “randomObject” using the Visual Studio debugger, this will be very useful for quick debugging with the Simulator.

On the JavaScript Console VS Output this will look like this:

2014-06-17_172850

Debugging on Device Emulators

Note on support for debuggin on emulators

Debugging with Visual Studio Debugging tools:

  • Android 4.4 devices
  • Windows 8.0 (Store)

JavaScript Console Output in Visual Studio (not the browser console, if you try to open the browser developers tools, the simulator will close the window):

  • Android 4.4 devices
  • Android 4.4 devices
  • Windows 8.0 (Store)

The content of this two lists means that is not possible to Launch or debug with the iOS Emulator from Windows, which is something to expect, fortunately Apache Ripple Simulator can help us a lot and when it’s time to test and debug something on the Emulator, it is suppose to be possible via remote debugging, we’re going to try it at the end here.

Android 4.4

It’s easy to Launch the Android emulator, if you have a configured Device all you have to do is change the Debugger target in Visual Studio to “Android Emulator”.

emulator

More info about the AVD Configuration with the AVD Manager here.

The current release make the promise of debugging, but I were not able to do it, it may be a problem with my AVD emulator configuration, Although the promise of showing the console.log results on the Visual Studio Output window was delivered:

emulator android

As you can see the Visual Studio JavaScript Console Output displays what was passed to the console.log, but the application did not stop on the breakpoint : (

Using the iOS Simulator (you need a mac for this)

First you will need to set up the “vs-mda-remote”.

Open your console and install the vs-mda-remote (via node.js npm):

    npm install vs-mda-remote
For full instructions about how to install "vs-mda-remote" in your mac you can follow the instructions on the following StackOverflow question Visual Studio Cordova iOS build server setup

Once that you have installed the “vs-mda-remote” in your mac, you will have to create a folder for the builds (on the mac), that folder will be a parameter for the execution of the vs-mda-remote

vs-mda-remote --buildDir [YOUR_FOLDER] --allowsEmulate=true

In my case the folder was inside the Documents folder, so my full command was:

vs-mda-remote --buildDir /Users/robalarcon/Documents/remote-build/ --allowsEmulate=true

Screen Shot 2014-06-17 at 9.53.50 PM

 

To test that everything is working, open safari and go to localhost:3000, you should have served a page like the following:

Screen Shot 2014-06-17 at 10.01.39 PM

 

Configuring Your Remote Build Server in Visual Studio
You have the mac waiting for something, is ready for business, now it’s turn to configure Visual Studio for that business.

 

  1. Get the ip address of your mac, open a terminal and type ifconfig
  2. In Visual Studio navigate to TOOLS > Options > Multi-Device Hybrid Apps > General. And set the Host variable with the ip address of your mac, and the Port variable to 3000.
  3. Set Enable remote iOS processing to True 2014-06-17_220905

We’re ready to go, in my case, I just select “simulator – iphone” to debug, and the console on the mac start printing tons of messages and the it said: ** BUILD SUCCEEDED ** 😀

Screen Shot 2014-06-17 at 10.25.03 PM

Be careful with typos i.e. when I setup the “vs-mda” on the mac, I typed allowEmulate=true without the in allows, and it didn’t throw an error, it just start with allowsEmulate option as False, and We don’t want that.

Note: if you don’t see the Simulator – iPhone as an option to debug, it’s because you have to choose iOS as platform at the DropDown component at the right.

2014-06-17_221057

Troubleshooting

* Problems with third party software

I had trouble installing joyent node.js, after installing all the third party software Visual Studio told me that it was a problem installing it, it was because I had previously installed an older version of node.js, if this happen to you, just install again node.js (the version that you previously had), and then install the latest version.

node-problem

 

I also had problems with Apache ant, when I tried to build the sample App, the compiler throw an error telling that  the system environment variable was not well configured,

2014-06-17_154513

Because I didn’t want to spend more time with this problems I just manually installed Apache Ant, and set my environment variable (variable value is the folder that contains the ANT bin and lib folder).

2014-06-17_154653

 

Also you’ll probably need to add the following line to the system path:

%ANT_HOME%\bin

 

* Problems when trying to create a New Project

I spent an hour trying to find a workaround for an error when I was trying to create a new Project, the following error appear every time I tried to create a project:

visual studio the path you have entered contains a space. Please select a location without a space when creating a mMulti-device Hybrid App.

visual studio the path you have entered contains a space. Please select a location without a space when creating a mMulti-device Hybrid App.

I could not found a fix for the problem, it’s not included in the Multi-Device Hybrid Apps Known Issues, but I found a workaround, every time I was trying to create a project was in the default location Visual Studio Projects folder, I changed that location for a custom folder under “my documents” and it let me create a project. Following for this issue at StackOverflow.

 

* This AVD’s configuration is missing a kernel file!

If you try to debug an app with the Android emulator an the output shows that ERROR.

That means that you don’t have an Android device configured, you should configure one using the AVD Manager, you should have the AVD Manager already installed, so just look for it and configure an Android 4.4 device.

2014-06-17_192622

 

 

Conclusion

As always there’s cons and pros with “Multi-Device Hybrid Apps”

The big CON was the setup, it took me hours of downloading, installing and troubleshooting the requirements, that was really expensive and stressful, definitevely MS have to work with the installation of the plugin, at least in my case, it was really painful.

There’s a couple of big PROS at least for me, once everything is installed is really easy to play around with this stuff, the ready to go Apache Ripple Debugging is hot, really hot, and the iOS Remote Emulation on the mac was surprisingly easy to install and run.

At the end, is Apache Cordova/PhoneGap, if you’re familiar with Cordova/PG and with Visual Studio you’ll love this plugin and it may speed up your development workflow with all the available tools, I have a good impression on my first hands on Multi-Device Hybrid Apps, and the best of all is that because Apache Cordova Code is just HTML, CSS and JavaScript, every developer on a team can choose their own IDE and development workflow without a problem.

 

Resources:

 

This “tuturial” is over,

— rob

Advertisements

iOS Development for PhoneGap Windows Developers using PhoneGap Build

PhoneGap (Apache Cordova) is great. If you’re already familiar with web technologies (HTML, CSS and JavaScript) you can easily start coding web apps that will be embeded on a mobile native app that can be installed in a mobile device (iOS, android, windows phone, blackberry, etc).

But one thing that is a little confusing at first is deploying for iOS devices when you’re a windows developer. In the following tutorial we’re going to follow a series of steps to deploy our app to a iOS device using PhoneGap Build.

Note: this tutorial is targeted for PhoneGap developers using windows or linux, testing primarily in Android. But this tuturial should work for PhoneGap developers using mac too, actually for this tutorial we’re going to need a mac to borrow at least.

Requirements

[ ] a Mac to borrow (should be e an Intel-based Mac)
[ ] an iOS Device for testing (could be an iPod Touch, iPad or iPhone)
[ ] an Apple ID
[ ] Subscription to the App Developer program
[ ] A mac software called “Keychain Access” if the mac that you took borrowed don’t have it, you can install “XCode” and it will install it automatically.
[ ] A phonegap App running in windows with android, to make the initial set-up you can follow Charles Chen post: Step by Step Android Development with Cordova and IntelliJ, I highly recommend you this tutorial, it’s easy to follow, and it does not have a lot of text like this one.
[ ] A phonegap account (to have access to the remote build app).

Get an Apple ID

Create an apple ID (this is free, and you need one to enroll to the iOS Developer program):
You can get one at: https://appleid.apple.com/cgi-bin/WebObjects/MyAppleId.woa/wa/createAppleId

Get an Apple Developer program account (iOS Dev Enrollment)

You are going to be asked to enroll as an individual or as a company, choose whatever accommodate to you:

https://developer.apple.com/programs/start/standard/

Activate your Apple Developer Program

Once you have both your apple ID and iOS Dev Enrollment, you have to activate your apple developer account, bellow are summarized the necessary steps:

  1. Once you have both your apple ID and iOS Dev Enrollment, you will need to sign in for Apple IOS Dev program enrollment.
  2. You will need to fill a form (divided in five steps) to Activate your program.
  3. Submit your billing information
  4. Select a program
  5. Review
  6. You must agree to the TOS License.
  7. And finally you can activate your Developer program.

Download & Install XCode in the Mac

There are some options to install xCode, the easiest way to install it is by downloading it from the app store.

Alternatively you can download it from:
https://developer.apple.com/downloads/index.action

Building the iOS Package on PhoneGap Build

PhoneGap build is very easy to use, once you have the code for your app, you just need to zip your “www” folder, and upload it to PhoneGap, then the app will build the app for all the selected devices, it’s really straightforward, except for iOS; In order to build an iOS package, phonegap needs a “phonegap iOS key” (I can’t find an official name for this key).

What is a PhoneGap iOS key?
Is a key that PhoneGap Build need to create a package for an iOS device (apk file).

Creating a PhoneGap iOS key

To create this key, phonegap needs two things:
a) an iOS Developer certificate (p12) file
b) an iOS Device Provisioning Profile

a) Getting the iOS Developer certificate (p12) file:
1- Login into the iOS Developer Center
Go to https://daw.apple.com/cgi-bin/WebObjects/DSAuthWeb.woa/wa/login?&appIdKey=891bd3417a7776362562d2197f89480a8547b108fd934911bcbea0110d07f757&path=%2F%2Fdevcenter%2Fios%2Findex.action

the login should look like this:
iOS dev program login

2- Go to the “Certificates, Identifiers & Profiles Section”
The link for this section is bellow the upper right corner of the iOS Dev Center Home page.

Screen Shot 2013-12-13 at 12.55.32 PM

3- Click the “Certificates”Folder:
Screen Shot 2013-12-13 at 12.57.09 PM

4- Click on the “+” (plus) sign button bellow the righ top corner:
Screen Shot 2013-12-13 at 12.58.40 PM

5- Set your certificate as “iOS App Development”under the Development Section and click on the continue button at the bottom

Screen Shot 2013-12-13 at 5.22.11 PM

6- Create a CSR file

  1. Open the “Keychain Access” program (for not mac users, you can open almost any mac programs by writing the program name in spotlight, to open spotlight just press the “command” key and the spacebar).
  2. Request a Certificate from a Certificate Authority, Within the Keychain Access drop down menu, select Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority, (be sure to select “Request a…”);  It should prompt the following screen:

Screen Shot 2013-12-13 at 5.23.34 PM

You should set your Email, a common name for your certificate, left the “CA Email Addresss”and set the      “Request is” field as “Saved to disk”, and press the “Continue” button.

Now back to the Apple Dev Center press the continue button:

7- Upload the CSR file (the certificate) that we created in step 6, and press Generate

Screen Shot 2013-12-13 at 5.27.39 PM

You should see an screen like the following, click on the “Download your Certificate”, and press “Done”

Screen Shot 2013-12-17 at 11.24.27 PM

Then locate your certificate (it should be in the Downloads folder by default), the name of my file for this tutorial is “ios_development-2.cer”, double click that file and you will open the “Keychain Access” program again;

To locate the certificate after open the “Keychain Access”: filter by “login”under “keychain”and, “My Certificates” under “Categories”, you should see your certificate with the alert “this certificate is not yet valid”.

We are going to export this certificate right clicking the certificate and selecting the “Export: ‘iPhone Developer’  ” option

Screen Shot 2013-12-13 at 6.17.36 PM

It will prompt for credentials for this key (be sure to save this password, because phonegap will ask for it once a month if you want to build)

Screen Shot 2013-12-13 at 5.31.04 PM

Then the app will prompt for the Mac User Password, set the password, and then go to your File System to locate the generated Personal Information Exchange File (.p12)

Register the Development Device to the Apple Dev Center

Under the Devices Section, click on the “+” (add) button bellow the right top corner

Screen Shot 2013-12-17 at 11.37.48 PM

To register a Dev Device you will need to named and the Device UDID:

To get the Device UDID you can connect the device into the computer, open iTunes, go to the iOS Device properties and copy the UDID from there:

image003

Copy that UDID and set it into the Device Registration Form, name your device and click continue, and then click “Register”

Screen Shot 2013-12-13 at 5.33.38 PM

Create an App ID

You are going to need you App ID in order to create a Provisioning Profile, you can add this App ID under the “Identifiers” Section, you have to set the “App ID Description”, and then set the “App ID Suffix”, set this suffix as an “Explicit App ID” If you have a plan to incorporate your app with services like In-App Purchase, Data Protection, etc, or want a provisioning profile unique to a single app, you must register an explicit App ID for your app, or you can select a Wildcard App ID, this allows you to use a single App ID to match multiple apps, and then click continue, As a last step for the App ID Generation, just confirm your values.

Getting the The Provisioning profile

The next step is getting the Provisioning profile, go to the “Provisioning Profiles” section, and then click the “+” button at the right top corner (almost the same procedure as the last steps)

Screen Shot 2013-12-17 at 11.48.09 PM

Set the device as an “iOS App Development” Profile and press continue

Screen Shot 2013-12-13 at 5.36.18 PM

In the next screen select an Apple ID (the one that we created in the last step)

Screen Shot 2013-12-17 at 11.49.20 PM

In the next screen select your Certificate and press continue (the one that we created before)

In the Next step you have to select the device for the current Provisioning Profile and then Click on the “Continue” button (the one that we add in the devices section)

Screen Shot 2013-12-17 at 11.50.14 PM

In the following screen, name the profile and click on “Generate”

Screen Shot 2013-12-17 at 11.51.06 PM

In the following screen you can Download the Profile and then click “Done”

Happy note: take a 5 minutes break, the boring part is done, next steps would be more enjoyable

Remote Build  with PhoneGap Build

Login into PhoneGap Build, the first thing that you’re going to see is the following image, press the “upload a zip file” button

Screen Shot 2013-12-13 at 6.01.31 PM

Then select and upload the zip file that contains your “www” folder, usually you’re going to submit a file named “www.zip”.

Once the app is uploaded press the “Ready to Build” button.

Screen Shot 2013-12-13 at 6.06.20 PM

You’ll noticie something unusual, all the platforms performed the build correctly except for iOS, the reason why is because PhoneGap Build needs the iOS key, we’re going to create that key with the provisioning profile and certificate that we previously created.

Screen Shot 2013-12-13 at 6.07.31 PM

Add the PhoneGap Build iOS Key

Under the iOS build section, open the Dropdownlist and select the “add a key” option.

Screen Shot 2013-12-13 at 6.10.23 PM

Set a title for this specific Build Key, choose the previously generated Key and Provisioning Profile and click the “submit key” button.

Screen Shot 2013-12-13 at 6.45.20 PM

Phonegap will try to generate a new build automatically, but it will fail, that’s because the key is locked by default, you have to press the yellow button with a lock, and insert the CERTIFICATE password.

Screen Shot 2013-12-13 at 6.45.50 PM

Submit the password (remember that once a month you will need to resubmit this password),

Screen Shot 2013-12-13 at 6.46.13 PM

Rebuild the app and you will have your “ipa” file ready to install in the selected device for the Submitted Provisioning Profile.

Screen Shot 2013-12-13 at 6.59.44 PM

Install the “ipa” build in the iOS device

  1. Download the “ipa” file from the phonegap build
  2. Double Click the “ipa” file, itunes should open this file and it will add the app to your itunes, or it will ask to replace the app if it is a new build.
  3. Connect the Development Provisioned iOS Device
  4. On iTunes navigate to your device, it should appear below the search input in the right corner as a button.
  5. Under the device options go to the “Apps” tab, your app should appear there under the “Apps” List, click the “install” button for the selected app to install in this device, and the “install” button should change to “will isntall”

Screen Shot 2013-12-17 at 11.54.26 PM

The last step is to just press the “Apply” button in the right bottom corner, and your application will be installed in your development device ready to be tested.

Resources

wow, that was a really long and boring post, the good stuff in PhoneGap is programming, so this time the boring stuff was on me : ), this post was a little difficult, so if you’re following this step by step guide and something fails, please be free to contact me, and I’ll try to edit the post (probably I forgot to add an step)