• Posted on: Jan 23, 2011
  • Tag:
  • Reactions: 687

> Add to home screen

Add to home

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.


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!

/Share the joy

/Reactions

    • Author: TABlackmore
    • Posted on: 2011/01/23
    • At: 22:30

    Again some nice work from the webapp master.

    Reply
    • Author: Joop
    • Posted on: 2011/01/24
    • At: 11:30

    Very nice, Matteo. I tried it, but the close button gives an ‘A’ instead of an ‘x’. Any idea where to change this?
    Thank you.

    Reply
    • this is extremely weird. have you changed the file encoding? Anyway it’s on line 115.

      Reply
      • Author: lng
      • Posted on: 2011/03/07
      • At: 21:05

      Same problem. There is a A instead of a x. I changed it to iso-8859-1 before and now change back it to utf-8, but same.

      Reply
    • the file is not probably sent as UTF8 by the server

      Reply
      • Author: Kyle
      • Posted on: 2011/04/04
      • At: 23:41

      I’m having the same problem. and im unsure what should be on line 115. could you help me out a little

      Thanks,

      Reply
      • Author: Nate
      • Posted on: 2011/05/04
      • At: 04:13

      I had the same issue(I was actually using javascript files served by PHP, so it was likely an encoding issue), but I was able to avert the issue by simply replacing the x character with the unicode escape (\u00D7).

      Reply
      • Author: Beining
      • Posted on: 2011/05/22
      • At: 20:28

      Hi!
      The same occurs for me. I see that Nate found a solution, but where in the javascript can I change the x character with the unicode escape (\u00D7)? Its not on line 115 (as far as I can tell).

      I have added script on http://portada.no/butikk/index.html

      ps. Brilliant script btw!

      Reply
      • Please download the latest version. should fix your problem.

      • Author: Beining
      • Posted on: 2011/06/24
      • At: 21:58

      Thanks Matteo!
      Updated my site to utf-8 and the new script and now it works!
      Hurray! :)

      Reply
    • Author: Chris L
    • Posted on: 2011/01/24
    • At: 17:28

    I’ve seen several sites using a script like this, and sometimes it gets activated when I’m viewing the page inside a third-party app (Twitter, Instapaper, etc.) So of course it’s pointing to a button that doesn’t exist. I wonder if there is a solution for that.

    Reply
    • Author: Joop
    • Posted on: 2011/01/25
    • At: 09:48

    Thank you, Matteo. My file encoding was not set to utf-8.

    Reply
    • Author: Matthias
    • Posted on: 2011/01/25
    • At: 11:27

    One of the nicest “Add to home screen” messages I’ve seen. Thanks for sharing.

    Reply
    • Author: Rob
    • Posted on: 2011/01/26
    • At: 10:38

    Phenomenal! Really great code, just left a tip, thanks again!

    Reply
    • Author: Mark
    • Posted on: 2011/01/26
    • At: 17:53

    Wow great very nice.

    The localization is great.

    Would be great if it would be possible to localize a whole webapp with a XML file. I found this:

    http://www.samuelgarneau.com/lab/lang/

    But i do not know how to implement it so that the language detection choose the right language.

    Maybe that would be something for our “webapp master”

    Thanks

    Reply
    • Author: exliontamer
    • Posted on: 2011/01/28
    • At: 03:28

    hurray for Matteo, as his cube continues to spin, can’t to see what iScroll4 brings

    Reply
    • Author: Allen
    • Posted on: 2011/02/01
    • At: 16:29

    Excellent work! Thanks so much!

    Reply
  • I’m not much of a mobile developer, but from what I can see this effect looks money. I’ve also really enjoyed your blog. You should write about Web Dev more since you obviously have the touch.

    Reply
    • Author: Jon
    • Posted on: 2011/02/04
    • At: 19:48

    I’m in awe. Thank you.

    Reply
    • Author: heine
    • Posted on: 2011/02/07
    • At: 21:38

    That’s awesome!!! Thank you very much. Do you guys know something like this for Android phones?

    Reply
  • This is a great and very helpful addition to a website’s general user interaction — there’s just one little thing: Is there any chance to detect whether the web app was started from the home screen to then prevent the message to show up?

    Because after a user saved the website to his home screen it might become a bit annoying to stil see the message at every visit.

    Many thanks for your great effort and any further development.

    Reply
    • fullscreen mode is already detected. no message is displayed if in fullscreen mode (and apple-mobile-web-app-capable meta is active of course).

      Reply
    • Author: Jon
    • Posted on: 2011/02/11
    • At: 11:21

    I have this working fine on a couple of sites, but can’t seem to get it working with jQTouch – is this something you are aware of? Do I need to do anything differently? Many thanks.

    Reply
      • Author: Jon
      • Posted on: 2011/02/11
      • At: 11:37

      Bit more info…debugging tells me that all the required functions are called, even calls the start of the drop animation, just nothing being displayed. Seems jQTouch prevents the div from showing?? Not sure. Can anybody shed any light on this?

      Reply
    • maybe you need to higher the z-index? otherwise there must be some overlapping styles between my script and jqtouch.

      Reply
    • Author: Jon
    • Posted on: 2011/02/11
    • At: 12:32

    Thanks for reply. I added:

    div.style.zIndex=”999″;

    But no difference. I’ll check through for style conflicts as well – if I find anything I’ll let you know!

    Reply
      • Author: Jon
      • Posted on: 2011/02/11
      • At: 12:58

      No joy I’m afraid. Can’t see why it’s not displaying, zindex is set very high in css in any case, and no style conflicts from what I can see. Must be to do with jqtouch.js or a maybe a funny version of jquery.js ? Anyway, I’ll keep trying…

      Reply
    • Author: Jon
    • Posted on: 2011/02/11
    • At: 14:41

    Well, I got it working. With jQTouch, I couldn’t find a way to have the div append to the body as it was always rying to do so before the page load, due to the way jqt works.

    Anyway, I changed :

    document.body.appendChild(div);

    To:

    document.documentElement.appendChild(div);

    And it works fine! So looks like a workaround for those wishing to use this with jQTouch.

    Reply
    • thanks for sharing!

      Reply
        • Author: Pingpocket
        • Posted on: 2012/11/10
        • At: 17:10

        Thanks a lot Matteo for this really good script.
        Thanks Jon for the jQTouch fix.

      • Author: Gaia
      • Posted on: 2011/03/09
      • At: 10:26

      Where i have to change this string? in my jquery.js file? on my php document? can you post you entire code please? Help me :-))

      Reply
    • in the add2home.js script I presume. Search document.body.appendChild(div); and replace.

      Reply
      • Author: Keahi
      • Posted on: 2011/03/12
      • At: 12:26

      Thanks! This got it to work on iuI as well.

      Reply
    • Author: spataro
    • Posted on: 2011/02/24
    • At: 19:27

    Hey, good solution. Just to report you that on ipad – atomic browser, works emulating iphone, but as ipad doesn’t work.

    Using safari no problems.

    bye

    Reply
    • Author: Arvid
    • Posted on: 2011/03/06
    • At: 01:48

    Great work, i’m using this on my new webapp and it works flawless!

    Reply
    • Author: LekeFly
    • Posted on: 2011/03/10
    • At: 03:02

    Thanks alot. Anyway to have the bubble always appear in all browsers? ( easy to firebug and so on.. )

    Reply
    • Author: Always21
    • Posted on: 2011/03/10
    • At: 09:11

    a.w.e.s.o.m.e
    I’m very appreciated for your sharing!
    Thousands of thanks.. = )

    Reply
    • Author: DidmoDev
    • Posted on: 2011/03/15
    • At: 12:28

    This is a brilliant piece of code!
    I showed the results to my boss and he got seven kinds of excited and wants me to update the production code immediately.

    Reply
    • Author: Chris
    • Posted on: 2011/03/17
    • At: 14:07

    This is great. Added it to one of my projects!

    My first web app and it works great.

    Do you know why once I have added it to my homescreen it loads fine and I get the homepage, but when I click a link within my website it opens up in Safari?

    Do you know why it does this?

    Reply
    • Author: Monecchi
    • Posted on: 2011/03/21
    • At: 12:05

    On iPhone 4 it works great, but what happens to iPod Touch 4? :( I’ve testeted it on both devices and only iPhone 4 shows it.

    Reply
    • Author: Monecchi
    • Posted on: 2011/03/21
    • At: 19:32

    Well, Maybe that’s because I’ve implemented it on a dashcode web application ready project and something is messing up the code or even I’ve messed it up myself, I’ll double check it.

    Thanks for the info.

    Reply
    • Author: Monecchi
    • Posted on: 2011/03/21
    • At: 19:39

    Actually for me it is not showing up on the iPod Touch 4, even if I access the Demo link from the device it doesn’t work at all. Would it be because I’ve got it jailbroken? I mean this script checks the iOS version to show the correct icon etc. doesn’t it?

    Any help is welcome.

    Thanks in advance.

    Reply
    • can you post your:

      navigator.appVersion

      and

      navigator.platform

      Probably jailbroken devices use a non-default string.

      Thanks

      Reply
    • Author: Petteri
    • Posted on: 2011/03/29
    • At: 12:08

    Here´s a Finnish translation (there´s lot´s of iOS web-app productions going on in Finland right now):

    Asenna tämä web-ohjelma työpöydällesi: Paina [ ] -kuvaketta ja valitse “Lisää kotivalikkoon”.

    Reply
    • Thanks! I’ll add Finnish asap.

      Reply
    • Where should I place the %device name in your translation? (I guess the share icon is the [ ])

      Reply
    • Author: DidmoDev
    • Posted on: 2011/03/30
    • At: 14:58

    Does anyone else using this on the iPhone have a problem with the latest version of the i-nigma barcode reader?

    They’ve started opening the links in their own micro-browser, and I get a big fat NSURLErrorDomain error – 999 alert box over the loaded page, and the javascript execution breaks so the add2home bubble is never shown.

    Been trying in vain to catch and suppress that error…

    Reply
    • Author: Robert
    • Posted on: 2011/04/03
    • At: 11:17

    THANK YOU ! Another nice UI & very useful script. Strangely, the css-inline icon for the home screen button (the share icon, for iOS >=4.2) does not show up in my app on the iphone (https://grouptodo.com/) It does not show up in the XCode iphone/pad simulator either for me. Just shows a blank space there.

    I know it must be something I am doing wrong (since your demo works) but I cannot figure out what it is – can someone see it ?

    Reply
    • maybe an encoding error?

      Reply
      • Author: Robert
      • Posted on: 2011/04/06
      • At: 00:49

      Ah silly mistake on my side. Nothing to do with your code (css minifier was eating the base64)

      Reply
    • Author: Tinker Marz
    • Posted on: 2011/04/05
    • At: 07:30

    Does the script check if the website is already installed at the home screen? I ask, because the message is shown to me, even if I start the web app _from_ the home screen.

    Reply
    • Do you have a jailbroken iphone? If so please post your

      alert(navigator.appVersion)

      and

      alert(navigator.platform)

      thanks!

      Reply
    • Author: Macro Yau
    • Posted on: 2011/04/14
    • At: 14:07

    Nice work! I’m a developer from Hong Kong and I’ve translated the Traditional Chinese and Simplified Chinese message for you:

    Traditional Chinese (likely to be zh_TW): 您可以將此應用程式安裝到您的 %device 上。請按 %icon 然後點選加入主畫面螢幕
    Simplified Chinese (likely to be zh_CN): 您可以将此应用程式安装到您的 %device 上。请按 %icon 然后点选添加至主屏幕

    Keep up the good work.

    Reply
    • cool, thanks! I’ll update the script asap

      Reply
    • Author: di
    • Posted on: 2011/04/16
    • At: 08:17

    i love you man

    Reply
  • You did a great job there, thanks for the script! (Now by default in all my mobile websites).

    Reply
    • Author: BStewart
    • Posted on: 2011/05/06
    • At: 03:28

    Is there a way to programmatically open the balloon in a button’s onclick event?

    Reply
    • not without modifications to the code

      Reply
    • Author: ardin
    • Posted on: 2011/05/09
    • At: 00:03

    Anyone know if there’s a way to get this to work with a wordpress/wptouch site? I’ve tried adding the code to the actual wordpress header, and the wptouch head file, but to no avail.

    Reply
    • Author: cykane
    • Posted on: 2011/05/10
    • At: 09:40

    Sweet Feature, really good work!

    Greetz

    Reply
    • Author: EllSHEEN
    • Posted on: 2011/05/12
    • At: 10:14

    Is there anyway to stop the message coming up after someone has already ‘installed the web app’?

    Reply
    • it shouldn’t come up if the user added the app to the homescreen. If it does, it’s a bug and I’d need more info

      Reply
    • Author: Ardin
    • Posted on: 2011/05/14
    • At: 01:01

    Yeah, still comes up on mine after having been added to homescreen, running iOS 4.3.3 on an iPhone 4 from a wordpress site with wptouch for the mobile interface.

    Reply
    • Author: Steve
    • Posted on: 2011/05/16
    • At: 10:13

    Thank you for this nice bit of code, I’m using it on a mobile site I’ve made for the iPhone.

    Very nice ! Wish I could do stuff like that :-)

    Reply
    • Author: Donavan
    • Posted on: 2011/05/16
    • At: 18:15

    Thanx, this is a really nice ‘function’ for my webapp. But I have 1 problem: My apple-touch-icon won’t show in advanced mode :(

    Reply
    • Author: Tom McKearney
    • Posted on: 2011/05/18
    • At: 21:56

    This seems nice, but it keeps asking the question over and over. How do you tell when to stop asking?

    Reply
    • expire:1440
      asks it once per day.
      expire:10080
      only once per week.

      quote: “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).”

      Reply
    • Author: Dave
    • Posted on: 2011/05/19
    • At: 03:34

    Can’t get the icon to show.

    http://mobilewebsolutions.us/bywave/add.htm

    Any suggestions? Other than that, this is a sweeeet function. Very nice.

    Reply
    • Please update to the latest version. Also it is crucial that the JS file is served as UTF8. 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 UTF8 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 working with .htaccess is not possible, you may want to remove all languages but English from the script.

      Reply
      • Author: Dave
      • Posted on: 2011/05/21
      • At: 01:21

      I can’t. The download is .gz. I’d need a zip. The only version I can use is whatever you have setup for the demo. Can you update that to the latest version?

      Reply
    • you can get it from github… anyway I’ve updated the demo

      Reply
  • Hi
    I’m a newbie and really just want to create a basic mobile webkit site
    I’ve created this test subject to see If I’m any good but now want to add this to my site (Home Screen Bubble)
    Can anyone help ?
    http://82.45.130.37/atozcouriers/ftp/rb/kjh/001/testindex.html
    HTML File @-http://www.2shared.com/document/XdlY_yPp/index1.html?(Password 21)
    If any one could help that would be great
    Thanks keirjohnharry

    Reply
    • Author: bram
    • Posted on: 2011/05/24
    • At: 08:57

    Hi there,

    First of all, you make some cool stuff!
    What I noticed is that when you save the webpage on your homepage and you open it again, the website is an web app. How cool is that! But when you click on a link in that web app, you get redirected to Safari, so that’s kinda weird though.

    Reply
    • Author: bram
    • Posted on: 2011/05/24
    • At: 09:30

    Could you implent query.cookie.js (http://plugins.jquery.com/node/1386/release), so when somebody clicks on the ‘x’ (or ‘don’t show anymore’ link), the popup won’t show anymore when you refresh the website.

    Reply
    • the script uses localstorage that should be more stable than cookies. If you set the expire to 525600 you won’t see the message again for one year.

      Reply
  • Can anyone help me with my above issue ?
    I don’t even know how to put this into my website
    Please Help

    Reply

/Leave a reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>