Matteo Spinelli's

• Get the Script
• Screencast
• Live Demo
• GitHub

Project info

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.

Support development

If this script saved your day and you wish to support future developments you may consider sending some funds via PayPal or Flattr.

Overview

The script places a floating balloon inviting the user to add your application to the home screen. Version 2 of the script takes advantage of iOS5 native fixed elements positioning and gracefully degrades to a javascript only version on iOS4.

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:

• Catalan
• Chinese (Traditional and Simplified)
• Danish
• Dutch
• English
• Finnish
• French
• German
• Greek
• Hebrew
• Hungarian
• Italian
• Japanese
• Korean
• Norwegian
• Polish
• Portuguese
• Russian
• Spanish
• Swedish
• Thai
• Turkish

Please help me localize the script in more languages.

Locale can be forced, so you can use only English if so desired.

Standard usage

All you need to do for the magic to happen is to add the following inside your page HEAD:

<link rel="stylesheet" href="path/to/add2home.css">
<script type="application/javascript" src="path/to/add2home.js"></script>

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.

Advanced features

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:

<script type="text/javascript">
var addToHomeConfig = {
	animationIn: 'bubble',
	animationOut: 'drop',
	lifespan:10000,
	expire:2,
	touchIcon:true,
	message:'This is a custom message. Your device is an <strong>%device</strong>. The action icon is `%icon`.'
};
</script>
<script type="application/javascript" src="js/add2home.js"></script>

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:

Autostart

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!).

Returning visitors

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

The 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 true and 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: drop, bubble and fade. Default: drop.
• animationOut: the animation the balloon exits with. Can be: drop, bubble and 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 HEAD and 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.

Public methods

You can programmatically open the balloon by calling the addToHome.show() function.

You can programmatically close the balloon by calling the addToHome.close() function.

During development you may also need to reset the local and session storages. You can do so by calling the addToHome.reset() function.

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!