It has been a long standing ambition of mine to create an app that I could run on my iPhone. This weekend I finally realized that ambition – in what turned out to be a surprisingly simple fashion. Using various tutorials, tips from colleagues and the Ionic 2 framework, I created a progressive web app (pure HTML 5) that I can add to the iOS launchpad as what to all intents and purposes feels like a native app.
Note: I have no experience with mobile app development – only with web application development with HTML5 and JavaScript [and some server side Node.js JavaScript experience]. With only that knowledge under my belt – it turned out quite simple to create the progressive web app using Ionic 2. Below, I describe the steps I went through, along with references to the resources that helped me get going. The article contains the following sections:
- Prepare the development environment
- Generate scaffold Ionic 2 application
- Prepare app for stand alone usage
- Deploy the web app [ to a web server]
- Configure app on iPhone
- [stand alone app on Chrome]
Prepare the development environment
These steps are generic preparation – across multiple Ionic applications. Note: I am working on Windows 7. The steps are the same or very similar on other operating systems (and versions)
Install NPM – the Node Package Manager
when you install Node.js, npm is installed as part of it – see https://docs.npmjs.com/getting-started/installing-node)
Install Ionic (incl v2)
On the command line, after installing npm,
npm install -g ionic@beta
Add Cordova
npm install -g cordova
Add platform browser
ionic platform add browser
Generate a scaffold Ionic 2 application
Ionic 2 makes it very easy to jumpstart a mobile [web] application. It can generate the project with scaffold files based on a selected template. This generated application can be run – without any changes.
Create Ionic project
based on a template, using ionic start projectname tutorial|tabs|maps|sidemenu|blank|complex-list –v2 –ts:
ionic start steepr tabs --v2 --ts
This directory structure is created:
Run project locally
ionic serve
The application opens in the default browser:
Prepare app for stand-alone usage
Web applications that are capable of being used in ‘stand alone’ mode can be identified as such – and characterized – using a manifest – based on the W3C specification for such manifests: see http://html5doctor.com/web-manifest-specification].
A subdirectory /imgs is added with two icons in it – a white and a black edition of the Steepr thumbnail:
The manifest.json file is added in the same directory as index.html.
In this file, the name of the application is defined, the icon, the stand alone capability and the start_url. These properties can be used by the browser to present the app as stand alone
{ "name": "Steepr", "short_name": "Steepr App", "scope": "./", "icons": [{ "src": "imgs/SteeprLogoBlack.jpg", "sizes": "1280x1280" }], "background_color": "#bababa", "display": "standalone", "start_url": "./", "theme_color": "#303F9F" }
Note: support for the Web App manifest is still growing. Safari seems not to use any elements in the file, Google Chrome seems most willing to interpret the file.
A link to the file is added inside index.html. A link is added to one of the icons in index.html – this will produce the icon on the browser tab – formerly known as the fav icon.
Safari does not recognize the manifest.json file at all. In order to have Safari on iOS handle this web app as a stand alone app, we need to add two specific meta-tags to index.html:
<head> <meta charset="UTF-8"> <title>Ionic 2 - Steepr V1.8</title> <meta name="theme-color" content="#303F9F"> <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, user-scalable=no"> <meta name="format-detection" content="telephone=no"> <meta name="msapplication-tap-highlight" content="no"> <link rel="manifest" href="manifest.json"> <link rel="icon" href="imgs/SteeprLogoBlack.jpg"> <meta name="application-name" content="Steepr"> <link ios-href="build/css/app.ios.css" rel="stylesheet"> <link md-href="build/css/app.md.css" rel="stylesheet"> <link wp-href="build/css/app.wp.css" rel="stylesheet"> </head>
The tag apple-mobile-web-app-capable is crucial: it means the difference between the app being started in the context of the Safari browser or as a stand alone native-app like experience. The tag apple-touch-icon-precomposed defines the icon that iOS will use as basis for the round icon on the launch pad. See this document for all Apple/Safari specific tags regarding (progressive) web apps: https://developer.apple.com/library/safari/documentation/AppleApplications/Reference/SafariHTMLRef/Articles/MetaTags.html
Make some edits to the scaffold files
Just to add a personal touch.
Build Ionic application for platform browser
ionic build browser
The application is built for the browser platform. The result is found in the platforms\browser directory under the app root directory. The www folder contains the build result – in this case that folder is Steepr\platforms\browser\www.
The contents of this www directory can be deployed to a web server to be served to browsers -especially those running on an iPhone or iPad.
Deploy the Progressive Web App
Deploy application to web server – in my case the Oracle Application Container Cloud Service (a Node.js container). This simply means that the browser platform specific www directory is made available on a web server that devices can reach. Note however that the application should be served over https (and not plain http).
On the iPhone
Get out my iPhone. I open the web application in the browser:
I click on the Share icon:
Select option Add to Home Screen.
The Add to Home dialog opens. Set the name of the link (icon) on the launchpad:
The icon is added to the launchpad – and the web application can be opened just like any app by tapping on the icon:
Once the app opens in this way – the browser UI elements are hidden and the app is presented full screen – just like a regular native app.
Google Chrome App
Google Chrome – also on desktop PC – has the concept of apps – see: https://developer.chrome.com/apps/about_apps. The web app developed in this article can be added as app to the local Chrome [desktop] App collection – and be launched as stand alone application, outside the browser context. These are the steps:
Open the web application in the Chrome browser.
Select the menu item More Tools | Add to Desktop
In the popup – the icon and application name defined in the manifest.json file are prepopulated.
Now, the Steepr web app is added to the set of Chrome Apps.
It can be opened by double clicking – and it will open as a standalone application, outside the Chrome context:
Resources
Introducing Progressive Web Apps: https://addyosmani.com/blog/getting-started-with-progressive-web-apps/
Tutorial Getting Started with Ionic 2: http://ionicframework.com/docs/v2/getting-started/tutorial/
Alternative tutorial for creating progressive web application with Ionic 2 [against GitHub API] – https://scotch.io/tutorials/build-a-mobile-app-with-angular-2-and-ionic-2
And a tutorial for your first Ionic 2 application [against IMDB movie database] – http://www.gajotres.net/ionic-2-tutorial-lets-create-our-first-application/
Installable web apps (and manifest.json) https://dev.opera.com/articles/installable-web-apps/ and http://html5doctor.com/web-manifest-specification/#appname
Udacity course on Progressive Web Apps: https://www.udacity.com/course/intro-to-progressive-web-apps–ud811
Apple iOS Developer Library – Safari Web Content Guide
– Configuring Web Applications (for app like experience on mobile devices): https://developer.apple.com/library/ios/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html
– Supported [Apple specific] meta-tags: https://developer.apple.com/library/safari/documentation/AppleApplications/Reference/SafariHTMLRef/Articles/MetaTags.html
Google Chrome – custom Chrome Web App [through] Short Cuts – http://www.howtogeek.com/169220/how-to-create-custom-chrome-web-app-shortcuts-for-your-favorite-websites/
thanks for the great tutorial.it was helpful. when i try build/serve the meta tags apple-mobile-web-app-capable and icon are getting removed form index.html. do you have any idea?
Does safari caches pwa apps for offline mode ? You have any link of app which I can test if it does so ?
Exactly what I was looking for.. thanks for taking time writing this. Very useful.
Good to hear! You are most welcome.