> Add to home screen
I found that many iPhone and iPad users don’t know that they can add their favorite web sites to the Home Screen and interact with them like standard native applications. This script helps them to discover this great feature and suggests the steps needed to add your web app to the dashboard.
Name: Add to Home screen
Last code update: 2013.01.18 – v2.0.5
Device compatibility: iPhone/Ipod touch >=3.1.1, iPad >=3.2.
QR Code opens demo page.
If this script saved your day and you wish to support future developments you may consider sending some funds via PayPal or Flattr.
The default message looks like this:
The code is compatible with iPhone/iPod touch, iPhone4 and iPad. On older devices the “add” icon is a “+” while on iOS 4.2 it has been replaced with . The script detects the OS version and displays the appropriate icon.
The message appears after 2 seconds (customizable) from page load, and is destroyed after 15 seconds (also customizable). The balloon enters and exits the screen with a quick configurable animation: drop from top, bubble from bottom or fade in/out.
The balloon can be dismissed any time by tapping the small “x” icon.
The script also checks the user’s locale and shows the message in an appropriate language. So far the following languages are supported:
- Chinese (Traditional and Simplified)
Please help me localize the script in more languages.
Locale can be forced, so you can use only English if so desired.
All you need to do for the magic to happen is to add the following inside your page
That’s it. The code checks the user’s device, OS version, standalone compatibility, etc. If the user is eligible, the screen will be gladden with the cheerful balloon.
You can customize the script behaviors by setting the
addToHomeConfig global variable *before* the
add2home.js script is included into the page. Let me stress on this. The variable must be globally accessible and must be defined before the script is included inside the page.
Here’s a simple example:
The popup appears with a bubble effect and is dismissed with a drop animation. It stays on screen for 10 seconds, it is shown only once every 2 minutes, it shows the
apple-touch-icon, and changes the default text with a custom one. This is the end result:
The script automatically starts on page load. You can prevent this behavior by passing the
autostart:false option. You can later show the balloon calling the
addToHome.show() public method.
You can also override all the compatibility checks and always show the popup by calling
addToHome.show(true). (Not suggested!).
V2.0 adds the
returningVisitor option. This is a very important feature that I highly encourage you to use (ie: set it to
true). What it does is to show the message to returning visitors only. The first time a user accesses your site the message is not shown. If the user comes back within a 28 days timeframe, the message is finally presented.
I believe this is very important for usability. When I end up on a new site I just want to look around and there is a very small chance that I will really come back to that site again. But if I come back a second time there’s a good chance that I’ll return a third and a forth.
Showing the message the very first time a user visits your site could be self-defeating and may just irritate her.
More power to the user
If the user intentionally closes the balloon, it won’t show up again for all the duration of that session. This feature overrides all your configurations, even if you set the balloon to show up every single time, if the user taps the close button the message won’t be shown until the browser is closed and reopened.
All the Options
addToHomeConfig object is used to configure the balloon. The options are:
- autostart: should the balloon be automatically initiated? Default: true.
- returningVisitor: show the message to returning visitors only. Set this to
trueand the message won’t be shown the first time an user visits your site. Default: false.
- animationIn: the animation the balloon appears with. Can be:
fade. Default: drop.
- animationOut: the animation the balloon exits with. Can be:
fade. Default: fade.
- startDelay: milliseconds to wait before showing the message. Default: 2000
- lifespan: milliseconds to wait before hiding the message. Default: 20000
- bottomOffset: distance in pixels from the bottom (iPhone) or the top (iPad). Default: 14
- expire: minutes before displaying the message again. If you don’t want to show the message at each and every page load, you can set a timeframe in minutes. The message will be shown only one time inside that timeframe. Default: 0 (=always show).
- message: Define a custom message to display OR set a fixed locale. If you don’t like the default message we have chosen for you, you can add your own. You can also force a language by passing the respective locale (eg: ‘en_us’ will always display the English message). Default: ” (=script decides).
- touchIcon: if set to
true, the script checks for
link rel="apple-touch-icon"in the page
HEADand displays the application icon next to the message. Default: false.
- arrow: shows the little arrow pointing the bottom bar “add” icon. For custom designs you may want to disable it (ie: set it to
false). Default: true.
Have a look at the many examples to see how the config works.
You can programmatically open the balloon by calling the
You can programmatically close the balloon by calling the
During development you may also need to reset the local and session storages. You can do so by calling the
Change the balloon appearance
Of course you are free to design the balloon in any way you want. Just change the
add2home.css file to your likings.
IMPORTANT: UTF-8 forever!
The script contains the “Add to home” message in many languages. To handle English together with Japanese or Hebrew the script has been encoded in UTF-8 (the standard nowadays).
For this reason it is crucial that the JS file is served as UTF-8. That should be default on recent webservers but you can force it by adding the following to your .htaccess:
AddDefaultCharset utf-8 AddCharset utf-8 .html .css .js .xml .json .rss
If you don’t want to convert all your site to UTF-8 you can serve just this script with the proper charset, like so:
<Files "add2home.js"> AddDefaultCharset utf-8 </Files>
(Not tested but should work)
If you can’t modify the .htaccess file, you may want to remove all languages but English from the script.
Web app capable
To prevent the balloon from appearing once the app has been added to the home screen, remember to add the
apple-mobile-web-app-capable meta to your page head:
<meta name="apple-mobile-web-app-capable" content="yes">
If your app is not “web app capable”
If you are not willing to add the web-app-capable tag, you can still prevent the balloon from showing up, but there’s no golden rule here. The easiest way is to check for a special url hash. Have a look at the
hash-trick example to get an idea, of course this technique modifies the URL the user is going to bookmark (eg: cubiq.org/#ATHS) and it may interfere with other frameworks that use hash-change event. So use it with caution.
The code is and always be MIT licensed, special thanks to all those who helped translating the script!