In this technical dive, I am covering the steps the Capitol Call development team took to migrate from Telerik App Builder to Ionic Pro. This migraton was performed on Windows with Visual Studio 2015 using Ionic 1 (in late February 2018).
The updated Capitol Call app was launched in to the iOS app store on 3/16/18.
1. Sign Up for Ionic Pro and Create your Project
A pretty obvious first step - sign up at https://ionicframework.com/. Walk through the wizard to create your first project.
2. Install Ionic (and Cordova)
npm install -g cordova ionic
Run if you didn’t have have cordova or ionic CLI previously installed. As an AppBuilder user - these weren’t required, so you may need to install them still.
3. Setup Ionic Pro Connected App
ionic start [App Name] --type ionic1 --pro-id [ID]
Run from parent folder. You pretty much must run in GitBash. This is because on your first run, SSH is needed to create SSH keys - and apparently this is only properly configured on the PATH when using GitBash.
After the first run using GitBash and creating your SSH keys, you can use another console (like the standard or Developer console). Unfortunately if you are migrating from AppBuilder, you are now entering a CLI world - no nice menu options any more - so get ready for typing.
The Ionic CLI presentation is a bit messed up when run in GitBash (for selecting options, entering responses), but is manageable.
Respond to each question as appropriate. Set up your SSH keys as required.
4. Run Ionic Serve to Verify your Starter Application
ionic serve -c --lab
Use Ionic Lab for a better visual experience. Run from newly created folder.
5. Open as Website in Visual Studio
Now you may ask, why didn’t I use TACO (tools for Apache Cordova) and create a Cordova project type? The short answer - I’ve found that a pain to work with in the past and I didn’t see the need in this case since I am going to primarily use Ionic Dev App and Ionic Pro cloud build. I also have a pretty good familiarly with the details of directly configuring the config.xml and plugin management.
Also, since other future users of my team likely won’t be on Visual Studio, I didn’t want to establish tooling requirements that forced its use.
To test Ionic serve, make a simple change to the CSS and verify the change is reflected on the Ionic Lab view in your browser:
Now make it blue.
Wait? What gives? If your experience was like mine - Ionic serve crashed after each file change. So let’s fix that.
6. Fix Ionic Serve Crash
Check out this article on the forum describing the issue.
The take away, perform these steps to replace the ws module with a newer version.
In globally installed Ionic package:
- Navigate to: %AppData%\npm\node_modules (or whereever you global node installation is)
- Remove folder: ./node_modules/ws
- Run npm install firstname.lastname@example.org
Now rerun ionic serve and verify that that changes do not crash the process.
Note: if you are using Ionic 3+, this is supposed to be addressed, but for migrators this is something I had to do myself.
Another note: You'll need to do these same steps each time you update the Ionic npm package (like when installing new CLI versions).
7. Try Ionic Dev App
The dev app is great for testing your Ionic code on a device. It doesn’t really work with plugins (despite the promises of supporting the most common - at least in my experience), especially when you use custom plugins (like I am). It is still a good tool for testing a lot of JS functionality, but doesn’t replace Development or Ad Hoc builds.
A nice thing - it is already packaged as part of ionic serve. If it isn’t already running, re run:
ionic serve -c --lab
Open the Dev app and if you are on the same wifi network you should see your app and be able to open it.
However, if you’re like me - that also did not work. As a web developer that works across many clients, I had already used the default ionic serve port of 8100 for another web application I had hosted via IIS on my machine and 8100 wasn’t open on Windows firewall. So let’s try another port:
ionic serve -c --lab --port 8101
(make sure to open on your firewall as well)
Unfortunately, still nothing on the dev app. Turns out, the app only searches on 8100. But there is an option to manually enter an IP and port on the hamburger menu.
Enter your internal IP address and port 8101 and hopefully the Dev app should find your ionic served app.
Now that we are set up. Try making changes in Visual Studio and notice how the app instantly updates on the phone. For reving UX experiences that don’t require plugin usages - this is very powerful.
Now, one annoying thing - the Dev App doesn’t remember or keep a history of manually entered addresses. Which means you have to enter it repeatedly. In the end, the manual option is pretty much useless because of this. Ultimately, I moved the existing web application I had off of port 8100, opened 8100 on Windows Firewall, use Ionic serve on its default port, and the discovery on the Dev App is much better.
8. Fix Task Runner Explorer
It is probable that you are using SASS in your application (or at least we are), and so I wanted to configure the default SASS watch in the gulpfile.js to execute via the Task Runner Explorer (and do so automatically when the project was opened).
However, the task runner explorer failed to find the gulp tasks, giving the following error in the Output window:
Node Sass could not find a binding for your current environment: [Discovered Environment]
This article helped me resolve this issue:
Follow the solution to change the tools path order in your Tool Preferences. (Go to: Tools > Options > Projects and Solutions > External Web Tools).
After this change I was able to see the Gulp tasks and configure the watch to run on project open:
Also if you are doing this, make sure to update the index.html to reference the ionic.app.css file as indicated commented block of html at the top file and remove the .css references
9. Prepare to Run a Ionic Pro Cloud Build
Now that we have a shell application, lets try the cloud build tools.
First, let’s update the package.json and config.xml to have the correct name/id values to match your existing application. As this is a migration, you should have your existing IDs you can plug in. I updated the package name to be the same as the Apple/Android App IDs and the config.xml id to be this value. The name in the config.xml will be what is displayed on the phone (unless you all have a short attribute for the display name). Also update the author and description for good measure.
Second, let’s fix a Windows Git access issue you’ll encounter when you run your cloud build. We’ll do this now to save time (though if you didn’t do this - you may encounter an EACCESS error when you actually ran the build).
git update-index --chmod=+x hooks/after_prepare/010_add_platform_class.js
Third, let’s commit this all to Ionic so they can build it. Use the git command line to push this to Ionic.
git add . git commit -m “commit message” git push ionic master
Also, if you are like me, you are used to using Visual Studio Team Services and committing via command line is painful. Unfortunately, this is going to be the new normal. While Ionic’s Git is not meant to replace your main source control - Visual Studio is also not great at having 2 active source providers for the same code - so I haven’t really found a way to use both VSTS and Ionic’s Git via the VS interface (though perhaps this is improved in VS 2017).
10. Configure your Build Credentials
Since we are migrating from AppBuilder, we can fortunately just export our developer / distribution certificate along with our private key from the AppBuilder Options:
(This is also assuming you are using the AppBuilder extension)
Also download your matching provision profile from your Apple Developer account:
Now upload these to a new Security Profile on your Ionic Pro dashboard:
This option is under Settings > Certificates.
Now, let’s start the build. Select the Code tab and find the commit. Click Package.
Select the build type and security profile (in my case I am using Development builds initially).
Click Package Build.
If everything runs correctly (hopefully you remembered the EACCESS fix mentioned above), the run should be successful:
11. Install your app on your phone
First, download your built ipa file:
Now… well… do something? I’m sure your typical Cordova developer might now know how to sideload this IPA file on to a device - or maybe not - given they might be building in xCode and install it directly. But as an AppBuilder developer, we were used to just QRing at this point (or having it directly load on the device). I think this is the biggest glaring functional issue with Ionic Pro’s cloud build tools - this is a bit of a dead end.
My solution: create my own QR-based installer. It’s a bit kludgey, but seems to work okay for me after a few days of using this approach:
- Install Cloudberry Drive (Yes this will cost you $30).
- Hook this up to an AWS S3 Bucket you manage.
- Save the IPA there.
- Create a manifest.plist in the same folder pointing to this file (see attached sample).
- Create a QR code for the following URL:
- itms-services://?action=download-manifest&url=https://s3.amazonaws.com/[your bucket path]/manifest.plist
- Use an online QR code creation service if you like.
- Save this image to the same folder or someplace you can access it easily.
- Scan the QR code on your phone, and the app should install.
Now, obviously you don’t want to do all these steps each time, so what I ended up doing was creating 2 manifests (one for dev and one for ad hoc - with appropriate settings for each).
Each time, I save the IPA to the Cloudberry drive, and then change the path in the manifest to point to the latest build (which includes the commit sha in the name). You could presumably save the IPA with the same filename each time as well - skipping the update to the manifest - but I wanted to avoid caching issues.
The benefit of this approach is that the QR code is the same each time (because the manifest URL is always the same), so you can always rescan the same image (or if its in your QR code scanner history, just re-click on it).
Update: After this original write-up was compiled, through usage, I determined that it wasn't necessary to change the target file in the manifest each time - and that if you overwrote the file stored in S3 on each new version, that this would still work fine (and not have any cache-busting issues). As such, I ended up not using Cloudberry Drive, and just used Cloudberry Explorer (which is free) to easily upload the replacement file after each build. This would require that I renamed the file when downloading it from Ionic Pro to a common name each time (ie just removing the commit SHA).
12. Copy Application Files
Delete everything in the www folder of your newly created web site project. You may want to retain the manifest.json and service-worker.js files if you plan to use these features and your previous project didn’t contain them.
Copy all files from your AppBuilder project (with the exception of Plugins, App_Resources, .abignore, cordova.js) to the www folder of your new project.
You may want to consider upgrading your ionic library reference during this transition - if you weren’t on the latest ionic 1 version.
In your new project, if you were using a build.js file (or similar that provided support for different js files for debug and release) in your index.html, update this to your debug settings file:
If you upgrade your Ionic version, make sure to update any references as needed.
If you had explicit app bootstrapping on device ready, update to use html-based app initialization:
These last 2 changes are needed because when using the Ionic Pro simulation tools, there is no cordova reference and thus no device ready or cordova global object.
13. Reinstall Plugins
ionic cordova plugin add [plugin id]
If you had any plugins that you installed from a local zip file (ie these would show in your Plugins AppBuilder folder), you will need to upload these to a Git Repo and install via this URL. Ionic Pro doesn’t seem to support installing plugins that aren’t available for download.
For instance, I had some customizations I made to Telerik’s Push Notificaiton Plugin. This had to be uploaded to GitHub and installed using that URL:
ionic cordova plugin add https://github.com/CapitolCall/PushNotification.git (Use GitBash for GitHub based plugin installs)
14. Set up your Icons and Splash Resources
Copy a 1024 x 1024 icon.png file in to the resources folder and a 2732 x 2732 splash.png file. Follow the instructions in the readme.md to create your icons / splash resources.
Either add a platform to generate the resources:
ionic cordova platform add ios
Or generate them directly:
ionic cordova resources
15. Update config.xml as needed
Update your config.xml as needed - copying settings from your original project.
16. Ensure iPhoneX support
If you hadn’t already completed this change, make sure your viewport meta tag also has the following property:
The remaining requirements for adding iPhoneX support are already part of the latest Ionic.
17. Commit and try Ionic Pro Package
Verify app build and app functionality. Fixing any issues that come up.
18. Ionic Pro plugin
cordova plugin add cordova-plugin-ionic --save
--variable APP_ID="[Your App ID]"
Note: If you reference the legacy ng-cordova.js (as I was at the time), rename this file such that it doesn’t end cordova.js. There is a bug in the plugin such it is too greedy when replacing the actual cordova.js and overwrites both files. A fix would look like: