Add to home screen

Add To Homescreen (ATH) is a javascript widget that opens an overlaying message inviting the user to add the web site/application to the home screen. This was born mainly to support web-app-capable applications but extended to a more general purpose use case.

Support Development

Add To Homescreen is a free, open source javascript software. It is released under the MIT License which basically grants you complete freedom in usage for open source and commercial applications.

That being said the only way for me to subtract hours from my day work and keep implementing this script is through donations. If you find this widget useful and wish to support future development, please consider a donation.


The script opens an always-on-top message inviting the user to add the application to the home screen. This is currently supported on iOS and Mobile Chrome. While other devices have the ability to bookmark any website to the home screen, only iOS and Mobile Chrome have a straightforward way to do it. ATH would technically also work on Windows Phone (which has the equivalent Pin to Start option), but I’m not currently able to test it on that device. WinPhone support might be added in a future release if there will be enough interest.

ATH by default looks something like this


But appearance is customizable with plain old CSS.

The script is compatible with iOS 6+ and Chrome 31+. It would be possible to add iOS5 (and older) support, but considering the iOS7 penetration I decided to support the latest two releases only. If there’s really interest in older versions I might reintroduce <iOS5 support or you could use the previous version of ATH (which supports iOS3 and up).


The message changed in v3 so unfortunately all the languages supported in v2 are not available anymore. If you wish to help please send more translations!

Basic Usage

v3 API changed drastically (sorry about that) and it’s not a drop in replacement for v2. The good news is that v3 is aware of user sessions saved on previous ATH versions, so if the users have already seen the message, it won’t be displayed again.

The easiest way to use ATH is to link the script into your document HEAD and call the addToHomescreen() function as soon as possible. Eg:

<title>Add To Home</title>
<link rel="stylesheet" type="text/css" href="../../style/addtohomescreen.css">
<script src="../../src/addtohomescreen.js"></script>

That’s all you need. ATH automatically hooks to the onload event, checks device compatibility, detects if the app is already in full screen mode and eventually pops up the message.

It is not strictly needed to place the script in the document HEAD (you can also place it at the end of your BODY), but ATH makes a series of checks that are better done sooner than later.


ATH accepts one option parameter to customize the script behavior.

To change the start up delay for example you could use the startDelay option.

   startDelay: 5

This would delay 5 seconds before showing the message.

Below the most common options.

  • modal: prevents further actions on the website until the message is closed.
  • mandatory: the website is not accessible until the user adds the application to the homescreen. This is useful mainly for web-app-capable applications that need full screen viewing to be accessed (eg: games).
  • skipFirstVisit: setting this to true prevents the message to appear the first time the user visits your website. It is highly recommended to enable this option!
  • startDelay: seconds to wait from page load before showing the message. Default: 1.
  • lifespan: seconds to wait before automatically close the message. Default: 15 (set to 0 to disable automatic removal).
  • displayPace: minutes before the message is shown again. By default it’s set to 1440, meaning that we will be showing the message only once per day.
  • maxDisplayCount: absolute maxium number of times the call out will be shown. (0 = no limit).
  • icon: display the touch icon in the pop up message. Default: true
  • message: you can provide your custom message if you don’t like the default.
  • onShow: custom function executed when the message is shown.
  • onAdd: custom function executed when the application is added to the homescreen. Please note that this is a guesstimate (see below).
  • detectHomescreen: ATH tries to detect the homescreen. Supported values are: false, true (=’hash’), ‘hash’, ‘queryString’, ‘smartURL’ (see below).
  • autostart: the message is not shown automatically and you have to trigger it programmatically.

Detect the homescreen

There’s no native event we could hook to to know when a user actually adds the page to the homescreen. That’s also the reason why this script has become so complicated despite the apparent simple task it has to accomplish.

ATH development started when Apple introduced the apple-mobile-web-app-capable meta tag and stand alone mode with it. When the webapp is in stand alone mode the window.navigator.standalone property is set to true and that’s the only 100% safe way to know if the app has been added to the homescreen… With some caveats (of course).

// set a web app capable website
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="mobile-web-app-capable" content="yes">

Standalone mode is meant for web applications, not “standard” web sites. The webapp has to be designed with standalone mode in mind, for example links inside your fullscreen app will open in a new browser window hence your app navigation has to be handled with JS.

Also, as of this writing Chrome –despite support for mobile-web-app-capable— doesn’t fill the window.navigator.standalone property, making it an unreliable way to detect if the app has been added.

So, how can we detect if the app has been actually added to the home screen? ATH tries its best to help you in this hard task and the followings are your options.

  • Show the callout only once per user. This is the best, safest and most polite solution of all. Set the maxDisplayCount to 1 and the user will be presented with the nasty callout only one time, smartly circumventing the problem.
  • Build a standalone application. When possible try to use apple-mobile-web-app-capable.
  • Add a special token in the URL and have the user bookmark the tokenized address. ATH supports hash, query string or smart url tokens. Continue reading for details.

I strongly suggest to go with the first option and show the callout only once. That’s the safest solution, but if you want to be more aggressive you can take the “token” route.

First of all you have to choose where to place the token. ATH offers three options:

  • hash:
  • query string:
  • smart url:

As soon as the page is loaded ATH adds the token to the page URL (no worries, no reload will happen as we use history.replaceState). If the user adds the page to the homescreen the actual URL that will be saved contains the token. If the page already contains the token before ATH could add it, it means that (most likely) the page has been added to the homescreen.

Bear in mind that this is a guesstimate, there are some exceptions but the good news is that it should be pretty rare to have false positive, ie: it should never happen to see the popup after the app has been added. Instead it may happen to have ATH think that the app has been added even if it hasn’t.

Be careful when using the detectHomescreen option since it may interfere with your application especially if you already use #hash or history.replaceState for your navigation.

Optimal configuration

Do not annoy your users with frequent callouts the suggested setup is to show the message only once, the second time the user visits your website.

   skipFirstVisit: true,
   maxDisplayCount: 1

The above config skips the first time the user comes to your site, so she has time to look around freely. The next time she will be greeted by the cheerful balloon and from that moment on she won’t be bothered again.

Debug mode

ATH v3 also introduces debug mode. By setting debug: true some of the preliminary checks are skipped and the message is shown on desktop browsers and unsupported devices as well.

You also have the addToHomescreen.removeSession() function in your tool belt, which clears the current session. This is very useful when testing various options and the callout seems not to be willing to show up again. This is common because ATH is very conservative, to avoid showing the message by mistake it tries to show it the less as possible.

Open the pop up programmatically

Of course you can bypass the automatic triggering and open the call out programmatically. To do so you have to set the autostart: false option.

var addtohome = addToHomescreen({
   autostart: false

addToHomescreen() it’s a kind of singleton and returns the instance to the real AddToHomescreen class. From there you have access to the show() method. Note that no checks are performed to verify if the DOM is ready, if you show the message programmatically that’s up to you.

show() also supports one boolean option. If you pass true the callout is shown no matter what overriding most of the preliminary tests.

localStorage variable name

The user session is stored in a localStorage variable called org.cubiq.addtohome by default. localStorage is domain based, so if you have multiple applications on the same domain ATH can’t understand which one you actually added to the homescreen.

You can have multiple instances of ATH on the same domain by setting a different appID for each installation. Eg:

   appID: 'org.cubiq.myCoolApp'

IMPORTANT: once set do not change the appID! If you change the appID all users will see the callout again regardless if they already added the application to the home screen or not. Only exception is for standalone applications. They would keep working correctly anyway.


From iOS6 you have a handy meta tag called apple-mobile-web-app-title that holds the name that will be displayed on the homescreen, otherwise the page title will be used. Since the app name is limited to 11 characters you may want to take advantage of this feature.

799 thoughts on “Add to home screen”

  1. 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.

    1. 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.

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


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

    4. 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

      ps. Brilliant script btw!

  2. 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.

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

  4. 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:

    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”


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

  6. 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.

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

  8. 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.

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

  9. 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.

    1. 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?

  10. Thanks for reply. I added:”999″;

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

    1. 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…

  11. 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 :




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

    1. 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 :-))

  12. 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.


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

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

  15. 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.

  16. 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?

  17. 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.

  18. 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.

  19. 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.

  20. 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”.

  21. 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…

  22. 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 ( 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 ?

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

  23. 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.

  24. 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.

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

  26. 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.

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

  28. 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.

  29. 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 🙂

  30. 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 🙁

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

    1. expire:1440
      asks it once per day.
      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).”

    1. 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

      (Not tested but should work)

      If working with .htaccess is not possible, you may want to remove all languages but English from the script.

    2. 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?

  32. 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.

    1. 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.

  33. i used this in a webapp (duh…) and i really liked it,
    i’ve put you on my credits page (1 out of 3 pages) so you’ll get visitors from me as well =D

  34. Do you know of any way to get this working on Android? I’m working on a cross-platform web app… By the way, EXCELLENT SCRIPT! Thanks a lot man. It works flawlessly on my jQueryMobile site for iPhone and iPad (haven’t tested iPod, but I assume it’s the exact same). And it seems to be the only script of its kind as of 6/8/11.

    1. technically it might work on android, but as far as I know it’s not possible to “install” a webapp on android from the browser itself.

  35. This script works excellent on a couple sites I’m working on.

    I’ve modified the code a bit so instead of launching the load event on window.load, I launch it on a button press (on a help button instead)

    Basically only had to comment out the event listeners and make the method public.

    But it only seems to run once. If I press the button again it goes through the motions but doesn’t seem to show anything.

    Any ideas?

    1. Nevermind.
      I realized the element was being removed in transitionEnd.
      As soon as I commented that out, I can make it appear as many times as I like.

    2. Hey Mark, could you post the lines you updated? I’m trying to do the same thing but I don’t know where exactly to tweak.

      Thanks in advance!

  36. Very cool script. Thank You

    Has anyone had an issue with ASP pages and the script? I tested the example and it works great under .html but when I change the extension to .asp I get the error. I changed this because most of my pages on my site are .asp

    Active Server Pages error ‘ASP 0138’
    Nested Script Block

    A script block cannot be placed inside another script block.

    1. The code still did not work. A friend of mine said he has it working on an ASP page. I will check it out and post the results if needed. Thanks!

  37. Great script!

    is ti possible to replace the word iPod with the word iTouch when it displays %device

  38. This is awesome! Had it working great, think it still is but I must have worn out my number of uses, definitely not more than 100, maybe 5-10? But iterations:100 is still set, is that not what I think it is or did I miss something (not a js person, really)? Thanks!

  39. @matteo

    i kinda figured thats where it would be… i dont know enough about javascript to do an if statement on the $device variable
    to display iTouch instead of iPod would you offer paid support to implement that change? if so how much?



  40. also how do you do the video screencast of your iphone – thats cool!


  41. Great stuff!! It wasn’t working for me on a JQtouch webapp until I changed the following code in the add2home.js file:

    // take this existing line out:

    // and add the following with ‘home’
    // changed to whatever the first screen’s div ID is:

    I’m guessing there may be a better way to do this… but this worked for me so I thought it may help others

    thanks again Cubiq – GREAT work!!

    1. Thank you so much for this, Gaucho!! You really saved me. It wasn’t working and I was tearing my hair out until I found your post. Saved me so much time!!

    2. Hit the same issue with jQuery mobile (RC1). Made the hack as above and it works great.

  42. Ciao
    ho visto che sei italiano, una domanda: il tuo script mi sembra che non sia compatibile con jQuery Mobile, è vero o sbaglio io qualche cosa?

  43. how can I modify the code to only show the bubble message on the home page? I’ve tried adding

    if ($(‘body’).hasClass(‘front’)) {
    if (‘standalone’ in navigator && !navigator.standalone && (/iphone|ipod|ipad/gi).test(navigator.platform) && (/Safari/i).test(navigator.appVersion)) {
    var addToHomeConfig = {
    animationIn:’fade’, // Animation In
    animationOut:’fade’, // Animation Out
    lifespan:10000, // The popup lives 10 seconds
    expire:0, // The popup is shown only once every 2 minutes


    and also tried

    if (‘standalone’ in navigator && !navigator.standalone && (/iphone|ipod|ipad/gi).test(navigator.platform) && (/Safari/i).test(navigator.appVersion) && ($(‘body’).hasClass(‘front’)) {
    var addToHomeConfig = {
    animationIn:’fade’, // Animation In
    animationOut:’fade’, // Animation Out
    lifespan:10000, // The popup lives 10 seconds
    expire:0, // The popup is shown only once every 2 minutes


    Neither worked. I also tried to use a PHP code if statement for front page, but that stops the popup from displaying too.

    Thanks so much for any help!!

  44. Is there a way to tell whether or not they have already done this? I don’t want to annoy the crap out of users who have already added it.


    1. if they already added the app to the homescreen, they probably access it from the homescreen and if your app is in full screen mode the message is not shown.

  45. Thanks so much for all your time on this!

    Another issue I’m having is when the Safari Mobile address (header) bar gets hidden.

    It appears the calculation of the popup position gets calculated before the address bar is hidden. So, the address bar is visible for a moment, and then when it’s hidden the popup ends up 50 pixels or so above the Safari toolbar footer. It doesn’t seem to be a problem in the demo because the Safari address bar isn’t hidden.

    Any ideas on a way to fix this?

    Thanks for any help!

    Also, great blog post on iOS5 and fixed positioning…

      1. Thanks for the response Matteo.

        I have actually added a full screen splash div behind the popup in the js file and I’m using both as a startup/splash page for users in Mobile Safari. Anyway, I removed the fade and startDelay so that the splash screen starts right away. Both fade after 10 seconds, or when the close button is clicked.

        In order to get the popup to display at bottom of screen after Safari address bar is hidden, I have also tried to use the bottom offset to push the popup down with a negative value, but a few times the popup ended up below the Safari footer.

        Thanks again for any help.

  46. Have you tested this in conjunction with your iScroll script? I seem to be doing everything right (files load properly, and addToHomeClose is available), but I can’t seem to get it to show up. I’ve tried doing what Gaucho recommends above (replacing document.body.appendChild(div) with document.all.main.appendChild(div)) but it doesn’t seem to help. (I’m using iScroll on #main, with an inner element of #event-list).

    Any ideas?

  47. I am not able to get the touchicon beside the message in the bubble. I have done the following:

    touchicon: true;

    I have added the following lines in my head tag:

    link rel=”apple-touch-icon” href=”../apple-touch-icon.png” type=”image/png”/
    link rel=”apple-touch-icon-precomposed” href=”../apple-touch-icon-precomposed.png”/
    link rel=”apple-touch-icon” sizes=”72×72″ href=”../apple-touch-icon-72×72.png” /
    link rel=”apple-touch-icon” sizes=”114×114″ href=”../apple-touch-icon-114×114.png” /

    but still I am not able to get the touchicon image in the bubble.

    Any ideas please??

    Thanks a lot in advance. 🙂

      1. I am working in mobile. I need to create a user control and only then it will work. I didnt know this before and though there was a mistake in script. My mistake. Works now perfectly.

        Great script though!

        One more thing. This bubble shows up even after user adds to home screen. Can the script be updated in such a way that, once user adds to home screen, the bubble should not show up.

        I dont know how feasible it is. But just wanted to know.


      2. Maybe visitor still uses Safari to see the bubble. If in Safari we can not detect if already added to home screen, the only solution will be cookie. Correct me if I am wrong.

    1. Report means… do you want a screencast or ..?

      What do you want the report to contain?

      Sorry for such dumb question, but I m new to development. 🙂


      1. Its I tested it using Iphone 3G. I made a change to the options.expire to 0. I tested it with option.expire to 1, but still, in all cases, the bubble shows up even after adding to home screen.

  48. Is it possible to add a different message for users who are viewing through a Twitter app / QR reader app WebUIView so I can tell them “open this in Safari to add to homescreen” or something?

  49. It seems like, taht the “Add to home screen” Bubble will not resize for iphone users. It shows up very small. is there an option to change it, that it shows up in fit of iphone screen?


  50. Just wanted to compliment you on how professional this looks. Also is there a maximum value for the ‘expire’ option? I was wanting to set it so it reminds users every week.

  51. love this! – thanks, want to use it but have a small problem. when i use

    meta name=”viewport” content=”width=device-width, initial-scale=1.0, user-scalable=0, minimum-scale=1.0, maximum-scale=1.0″

    it scales up current site (posterous) weirdly so i have taken this line out, problem is the box is smaller and location arrow is wrong on the top now (ipod one is fine) – is there a simply way to adjust the arrow on the top for the ipad?

    i’m new to mobility sites but can hack things together ok. 😉

  52. One more question. I’m having trouble getting my custom webclip icon to show up. Is this because add2home.js controls this?

  53. hii this is nice feature…
    but ther is one problem i include it still showing balloon

  54. hiiiiiiiii i include meta tag for prevent the balloon to appear but its not working….

  55. I can’t run this web app in fullscreen mode because I need the back button to be available. If the app isnt running full screen, is it impossible to detect that the page has been added to the home screen? Thanks for your help, love the plugin.

    1. YouTube does this somehow, and I read that you can use a get http request to get the context root? This is all over my head, but would you know how to make this work?

  56. Didnt worked for me 🙁

    I changed the code for jqtouch like some suggestions here, but no way to make it work. Neither iPad, iPhone, nothing 🙁

  57. The script works perfectly, just one thing , I added my Homepage to the Home screen and once I revisit the Homepage I see the pop-up again, my site already has the meta tag :


    is there something else I need to do in order for the pop-up to not display if the shortcut is already added to the homescreen?

  58. Hi,
    It’s awesome!
    I was looking for something like this!!
    I donated you right now.

    Thanks a lot!

  59. Wicked cool code. Awesome. Is there a way to pre-create a “button” on the website that would be used for the button that gets placed on the iPhone, etc.? That is I would like to create a button graphic to be used as the icon for the “app launch” on the iPhone so it would be automatically used instead of what is generated…

  60. Hi Matteo. I absolutely love your script, buddy–thanks a million. It looks great on my blank test pages. The problem is I can’t get it to work on my full iOS web page, which utilizes iUI. iUI uses its own javascript code. My question is: Do you know of any way to make both iUI and Add to Home Screen work harmoniously? If you’re not familiar with iUI, do you have any tips with regards to how I may run multiple javascripts without conflict? Thanks.

    1. Nevermind. I solved the problem. I changed some code (From: document.body.appendChild(div); To: document.documentElement.appendChild(div);), and now it works flawlessly! I’ll be donating later today. Thanks again!

  61. Thank you, you saved me a lot of time. Your page was the first interesting one on Google and 15 minutes later I had it working on my webapp.

    1. it works for me. Maybe a temporary server error?

      UPDATE: the second time you load the page the icon doesn’t appear. That’s really weird, I cannot replicate on my server. Can you try to use relative paths instead of absolute ones?

      1. Hi Matteo, thanks for checking! Actually I used relative path at first but when the next day the icon disappeared I started investigating and changed to absolute path – same thing. It does the same thing on my local dev server and remote “production” one. Just changed path back to relative one on my local dev server – doesn’t work. Really strange. Any thoughts?

  62. Is there anyway to add a link to the pop up for going out to another page. I would like to use this pop up for directing people to another page so they can download my iPhone and Android apps.

  63. You write “iPhone does not support fixed positioned elements, so the message has to be relocated on each page scroll.”.
    On the site which uses a similar balloon, you can perfectly scroll the background while the balloon stays fixed. Maybe check how they do it.

    Nice work anyhow.

  64. hi, i have some question about script… in JS i’m new… so, i will discribe my problem…
    I have imported this script in my ASP.NET project, when i trying to compile and run my project, Visual Studio throws me an error –
    can you help me solve this error?

  65. Ciao Matteo,
    Everything is going well, I have put my webapp on Ipad, when click on created icon my website start in fullscreen, but when I try to click a link inside my site Ipad switch to browser and not stay in app! Why? Have you already find a solution for this strange behaviour? Thanks in advance! Luca

    1. you need to rewrite your links…
      i did in that case

      function navigator_Go(url) {
          window.location.assign(url); // This technique is almost exactly the same as a full [a] page refresh, but it prevents Mobile Safari from jumping out of full-screen mode

      right url

      ((HyperLink)sender).NavigateUrl = "javascript:navigator_Go('" + Request.ApplicationPath + "page.aspx" + "');"; //for Iphone
  66. the script works perfectly on ipad only in the portrait mode, but when I rotate the ipad or run the app on the landscape mode, the balloon shifts to the right of the icon, and it does not stand exactly below the icon, is there anyway to solve this problem?

      1. i have iPad 1 with IOS 4.3.5 version, the problem even exists when I run your simple example in the ipad simulator window, that’s why i don’t think it’s my app or ipad problem.

      2. the problem is solved! I just didn’t copy the Meta tag in your html page for keeping the page scale at 1.0, so it changed the page scale whenever i rotated the ipad, and therefore the balloon relocated in wrong spot.
        Thank you for the script

  67. Hi,

    I’m trying to dynamically include your script from within another javascript by injecting the script element into the document head. At the time I include the script, the load and domready events have already fired. I cannot get your script to work, because in this scenario the ready() and loaded() functions will never be called.

    Any ideas?

  68. Great script, have working fine, but is it possible to alter the default text that appears prior to saving link, or is it only available from the page Title meta?

  69. Thanks for the great scripts and detailed instructions – you’re site is a goldmine for a start-up’s shoe string budget! Donation sent, site bookmarked and knowledge paid forward to others!

  70. Fantastic piece of code! Very easy to install and set up.

    Thanks for sharing.

    1. iv been struggling to get this script working on any of my sites. can you help?

  71. Can I load this script not on page load, but on button click? If it is posible, can you write short explatation? Thanks. 🙂

  72. if a web page is added once to home page and the same page is loaded on safari will it show the addtohome window or not?

  73. Most annoying script ever. How do you turn it off? I’m not going to fill my home screen up with web links. This script should be banned as it is invasive and extremely annoying.

    Not Impresed!

  74. Wow, I just put it on and added a quick call to our database to track users. I’ve have had over 100 this morning click the add to home screen button. Amazing results. Thank you!

  75. Is there any method to force the user to do the “Add to Home Screen” process? For example to dim the content of the webpage with content?

  76. Great script, it does not seem to work on iOS 5 though. Any thoughts on how to make it work?

    1. I’m suddenly not able to turn bookmarks into web apps on my ipad with ios5. I do the same “add to home screen” on the same sites I’ve already done it with and now they all open in Safari. The ones I bookmarked before still open in a web app. Is there some setting on the ipad that’s preventing this from happening? It’s not working on my iphone either.

  77. Excellent script, any tips on getting it to work in a sencha touch “afterrender” listener?


  78. You mention: ” there’s no way to know if an user actually added the page to the homescreen.”

    Can you not use HTML5 local Web storage for this. I feel users will get a bit sick of this bubble appearing every few minutes even though they have added an icon to their home screen.

  79. Firstly, Thanks for all your hard work! I am new to programming and just trying to learn. I have the script running in a web app I’m working on but I can’t get the animation to appear just the text. Can you explain where you put the icons and the path to change to get them to appear for a complete beginner please?

    Thanks again

    1. Just worked it out! Only problem I am getting is on an iPad and iPhone 4 it adds the “add to home screen” icon instead of the app icon. On my 3gs running ios5 it works fine, any ideas please?

  80. Works really fine on Iphone.
    But what is with Android devices?
    Do you have a similar solution which also works with Android phones?

  81. Hi. Matteo.

    This is what i’v been looking for. However are you able to explain step by step the steps. Iv downloaded the plugin. Intending on putting it on a wordpress theme running a mobile friendly version already.

    Where should i place the plugin? what part of the folder?
    Where should i edit the code?

  82. Can you add a cookie when the close button is clicked, preventing the popup for ever showing again (until cookies are deleted)?

  83. I’ve noticed that when you add the bookmark to your homescreen, it puts a glassy overlay on top of the icon. Can this be avoided?


    1. Hi man,

      Yes you can:

      “In case you realized you don’t like the pre-defined rounded corner plus glossy effect at all, you will have to rename your file (or link rel) accordingly, replacing apple-touch-icon with apple-touch-icon-precomposed. In this way your icon will be rendered as you conceived it, with no further modification.”

      So here is the code:

  84. Really cool script. Added it to our bank’s mobile pages and all folks were impressed. Good job.

    If you’d find a chance to extend it to Android it would be even greater!

  85. Great Script!
    Another shout for Android support.

    BTW How do you add a web app to the Android screen? I can’t see an easy way to do it.

      1. I too am very interested in the Android version. Thanks so much for this script!!

  86. I LOVE this script! I wanted to set it to just show on the home page. I looked through the responses here but the fix looked like it was from an earlier version or did not have an answer. If I set “expire” to “1” it won’t load the script again, even after, say 5 min. I’m kinda new so I am probably missing something elementary, Watson. Any thoughts? Thanks for your work!

  87. Does this work with iScroll? I downloaded it and tried, nothing happend, but an alert(); after everything was loaded appeared.

  88. What could I possibly be missing? Checked all paths, running with iOS 5.01 and won’t work on both an iPhone 4 and iPad 2. Added javascript alerts to the .js file and they pop so I know it’s finding it, but no page displays. Page also uses the iUi framework. Could they perhaps be conflicting?? What about 5.01 iOS? Is that tested? Is the UTF-8 thing required? Can I add that as a META tag to the page instead?
    Sorry so many questions but I’m trying to debug this.

      1. bodyElement did not work. Finally got it to drop now but only by commenting out all the iUi code. There definitely is a conflict and I don’t know how to create a workaround.

      2. Have narrowed it down to a specific CSS setting in the iUi code. Any idea why this conflicts with “Add To home”?

        body > *:not(.toolbar) {
        display: none;
        position: absolute;
        margin: 0;
        padding: 0;
        left: 0;
        top: 45px;
        width: 100%;
        height: auto;
        min-height: 415px;
        -webkit-transition-duration: 300ms;
        -webkit-transition-property: -webkit-transform;
        -webkit-transform: translateX(0%);

      3. I’ve got the same problem. Trying to implement with iui and the ‘body > *.not(toolbar)’ css breaks it.
        That section is fundamental to how iui works, so it’s impossible to change it. It’s how iui hides the different pages and transitions to them.

        I’m also using iscroll, but this doesn’t seem to be a problem.

        Would be forever grateful if there’s a fix for this!

        Cheers, Tony.

  89. Solved it!

    Add the class ‘toolbar’ to the add to home javascript and it works. Still some small css issues, but essentially it works.

    This is the line in addtohome.js, add the bold bit:

    div.className = (isIPad ? ‘ipad’ : ‘iphone’) + (touchIcon ? ‘ wide’ : ”)+ ‘ toolbar’;


      1. Hey, just try to use our thing: add “display: block !important;” to the #addToHomeScreen and I now have the add to home screen showing 🙂 sweet ! But it extends on all the height of the page…. So not the best fix.. If anyone have ideas. I am trying to fix it too

  90. Hi,
    I have a problem;
    When opening the front page via the icon on the home screen, all links on this site is opening in a new safari window. That is annoying, not possible to use back button..
    Any solution?

    You can test it here:

  91. Following up to post on 11/23… hoping ‘Tony’ can explain exactly which line to put display: in CSS to solve the problem with iUi framework conflict. I got it to work but the text spilled out of the bottom of the balloon so still broken. – Thanks in advance.

  92. Hi,

    The fact that the current version can’t be included dynamically makes it impossible for me to use it. You announced a 2.0 version 2 months ago. I do know you are probably doing this in your spare time and this script is a free giveaway. Is there still a chance 2.0 will be out anytime soon?


  93. Great script ! Thank you !
    I will use it for my next wep app 🙂

    I have only one question : is it possible de change the url shortcut ?

    Adress of my web app : with your script
    Adress when the user click on the shortcut :

    Thank you for your help.

  94. So cool! I’m running iOS 5 and the height of the box extends all the way to the top of the page. I can’t figure out how to fix that. Any ideas? Thanks so much!!!

  95. Hey, I’ve been using this AWESOME script on a clients site for a while, but I am just now getting around to worrying about the size of the box. I know I can change it in the CSS but is there a way I can just resize the balloon to fit the screen (proportionally appropriate)? Right now, when you load it is so small you can hardly read it, is there a way I can resize it without changing every width/height size in the CSS?

    1. I would also like to know how to do this….it would be a great option to add.

      Any suggestions?

  96. Hello,

    first of all: really nice job!

    Now, I’ve got a problem: I’ve got this script working finally but it shows an “Approve” mark when this Add to homescreen script comes up.

    I’ve not tested it yet in the english text but i’ll translate:
    Install this web app on your %devic(APPROVE MARK)e
    so basically:
    Install this web app on your iPhon(APPROVE MARK)e

    I don’t have any idea how to fix it.


  97. Love als the script! Good work!
    I have a problem such as Ken. Only in this case with jQTouch framework. The script works great without jQTouch code so also in this case there’s something conflicting.
    Any solution? Thanks in advance.

  98. This script is really nice and easy to use, thanks. You say above that there’s no way to tell if a user has added the app to their home screen yet the FT app somehow knows.

    If you visit the app in safari it says “You’ve added the FT Web App to your homescreen but are not using it. Launch the FT Web App from your homescreen to get the best out of it’s features and content.”

    Any idea how they can do that?

  99. Great work Matteo!

    I was able to implement it without much trouble at all. I did notice, that once I added the code, the accented characters are not being interpreted correctly. I’m trying to debug it now.

    Thank you for sharing!!!

  100. Works perfektly! Is there a way to enlarge the close icon?? Have tried in the css, but that doesn’t make the icon bigger..

  101. Is it possible to send notification messages to standalone iPhone web apps?

    Thank you

  102. Hie,

    Thanks so much for this very good script.

    Also, I have a problem to implement it correctly.

    When I use it alone in a page without effect js and css, everything is right.

    But in my iphone page, it does’nt. Do you have an idea please ?

    Thanks, Olivier

    1. Hie

      I think the problem is coming from IUI in my page. Is there someone with an idea ?
      Thanks so much for this excellent work.

  103. This is a great plugin for my site! I am having just one issue. Once it is launched on the homescreen and you hit any link it launches again in safari.
    Am I missing something or doing something wrong?

    Other than that it is great!

    1. @CHAE: You also have to add this to the head of your website:

      Then Web App will not start again in safari

      1. Tobias,

        Thanks for the reply, I have added this to the header of my site template but still opens up a new Safari window.
        Also, is there any way I can customize the add 2 homepage text? It is pulling the title text from my website, and it does not start with my company name.


  104. I found this code, but where do I install this?
    (function(a,b,c){if(c in b&&b[c]){var d,e=a.location,f=/^(a|html)$/i;a.addEventListener(“click”,function(a){;while(!f.test(d.nodeName))d=d.parentNode;”href”in d&&(d.href.indexOf(“http”)||~d.href.indexOf(,e.href=d.href)},!1)}})(document,window.navigator,”standalone”)

  105. im usually too lazy to write comments but this is an awesome script/idea 🙂

  106. Hi there !
    Great script. But it doesn’t seem to work for me. I built my app with iUI and experience the same problem Mr.Olivier (above) seems to. Whatever I try, I can’t seem to get it to work. Do you have any information about your script together with iUi ? Cheers and thanks,


    1. Hie, I fixed the problem with IUI.
      Place a display:table in addscreen css wire. Reset with margin:0 and padding:0 +++
      Very good source.

  107. It’s probably something really simple but i am a newbie and can’t figure it out. the message drops down from the top but it shows the text only…no bubble, no touch icon…what is the problem?

  108. I am using this script. It works fine but popup baloon is coming everytime even if i have added to home screen. Please give me the solution ASAP.

    Thank you.

    1. Hmm, “Please give me the solution ASAP?” I think you should say “Thanks for giving me a great solution”. Very rude demanding that someone should give you something for free, when you already got most of it for free?

      Anyways, Matteo, thank you for a great script, I am looking at a cookie based solution but it is not easy.

  109. Polish translation:

    pl_pl: ‘Aby zainstalować tę aplikacje na %device: naciśnij %icon a następnie Dodaj jako ikonę

  110. I’ve added the basic script to my mobile site, but I just dont get the popup. Can anyone suggest what I’m doing wrong?

  111. All my visitors/users are Danes, so I would like to present the message in Danish.
    However, if the visitor has an iPhone with English as the device language, then then instruction should still be “Add to Home Screen” (with the rest in Danish). Is that possible?

  112. Hi Matteo, thanks for this fine script. It’s up to the point, simply perfect.
    You suggest to use “one of the many include/require/load javascript libraries” for conditionally including the script. I tested this with yesnope.js, but the async loading leads to problems with the initialization.

  113. Hey, awesome script, works like a charm.
    One question though: to hide the URL bar, I did this:
    body onload="window.scrollTo(0, 1);"
    So now when I show the bubble it’s 40px too high, but when I move the page it “jumps” down to its correct position. Any idea on how to solve this?

    1. Also, the X-Button doesn’t seem to work for me (unless I’m doing something wrong).

      var addToHomeConfig = {autostart:false,

    2. I can change it if I edit this line: = options.bottomOffset + 'px';
      to = (options.bottomOffset - 60) + 'px';
      But as soon as I scroll or pinch, it “jumps” down. Any idea how I could catch these 60 pixels?

      1. Hey there,
        I am having the same problem, have you manage to fix it?

  114. I’m having the same issue as Phil (above)

    Most mobile suites like to hide the address bar these days. Taking this into account would make this awesome. I hope there is a fix for this.

  115. One possible solution I can think of is to scroll the page via javascript just before showing the bubble, but I’ve been trying to do that unsuccessfully so far.
    A different approach (not the smartest one, most likely) would be to check if the page’s been scrolled manually (e.g. with jquery’s .scroll()-event) and then remove the “-60” from the code. I’ll give that a try.

  116. Having trouble adding this to a WordPress-powered JQM site. Anyone know how to include this properly? (I’ve tried adding to header.php using wp_enqueue_script to no avail).


    1. Im adding my custom.js to the headtag, then within it I have the code that calls the add2home bubble.

      It is not possible to only show this bubble at the JQM home indexpage, it will be displayed on all subpages too.

      You must define the variables before the section that uses document.write to add the script URL’s, and because of this you can not use the pagecreate events to activate this script and have it showing only on JQM home page.

      Best regards Victor

  117. Really great piece of code, thank you very much! I can’t wait ’till you add Android support – Will be so awesome!

  118. Dang – I wish you hadn’t published this. Espn mobile site added it and now I get that annoying ballon each time…

  119. How do I apply this to icons on my site. my teacher asked me to add the code that would add a link to an icon so that when you add it to the home screen it makes the icon on the devices
    im not sure what the link is that I need to add to my icon.

  120. when the dom is ready, i have a error message : unable to load the local ressources in add2home.js in line 17. how can i fix it ?
    thank for all

  121. Hey,

    Is there a way to customize the homescreen icon that will appear on the user’s device after they save it to homescreen?


    BTW Amazing script. Love it.

  122. Okay, I got a problem. I put this code in the index.php, just before thr tag.

    var addToHomeConfig = {
    animationIn: ‘bubble’,
    animationOut: ‘drop’,
    message:’Install this web app on your %device: tab `%icon` and then Add to Home Screen.’

    Also, I uploaded through the FTP the “apple-touch-icon.png” (57×57) to the root. Also to the root I installed the folder (next to the folder “css”) “js” and put the “add2home.css” and the “add2home.js”.

    The message comes up, but the bubble is transparent, the apple-touch-icon is missing and the %icon won’t show up. Also when manually installing the web app, the apple-touch-icon doesn’t get shown…

    Who can see the mistake? I thank everyone that can help.

  123. I’m having an issue getting the close button to work. I’ve tried it using your live demo on my iPhone and iPad and when I touch the “x” nothing happens. Any ideas? Thanks!

  124. Android, Android, Andoird!

    And a merge into the querymobile-environment, maybe they have some energy in realizing for even more mobile-browser 🙂

    Thanks very much anyway. 🙂

    1. Android doesn’t have a full screen mode actually. The script itself already works on Android but the procedure to add a bookmark to the homescreen is not straight forward as it is on iDevices

  125. Has anyone got this working using WPtouch Pro for WordPress? I tried adding the code to the header.php file of the theme being used but it’s not working at all. I put all the files in the root of the site and used the following:

    var addToHomeConfig = {
    animationIn: ‘bubble’,
    animationOut: ‘drop’,
    message:’AB Playbill. Your device is an %device. The action icon is `%icon`.’,

    if (‘standalone’ in navigator && !navigator.standalone && (/iphone|ipod|ipad/gi).test(navigator.platform) && (/Safari/i).test(navigator.appVersion)) {

    1. I should learn how to use this properly. Here is my code:

      var addToHomeConfig = {
      animationIn: 'bubble',
      animationOut: 'drop',
      message:'AB Playbill. Your device is an %device. The action icon is `%icon`.',

      if ('standalone' in navigator && !navigator.standalone && (/iphone|ipod|ipad/gi).test(navigator.platform) && (/Safari/i).test(navigator.appVersion)) {

  126. My comment didn’t appear first time sorry if this is a reposts

    Is there a way to dim the background during the 10 or so seconds the add2homescreen popup is displayed


  127. Very nice work, thanks!

    Just wanted to add that it’s not always necessary to mess with the .htaccess file to set the character encoding.

    Most of the time (maybe always?) it’s enough to add


    to the script tag.

  128. Works great, thanks. One problem, it the bubble reappears after I add it to my home screen. Any thoughts? I have tried the hash trick and

    Neither have works,


  129. After drinking 1 cup of yerba daily for 20 yrs, suddenly it seemed to go right through me, even with the small amount of milk I put in it.

  130. What a great script! Best way to make people aware of installing webapp! I would like to contribute with czech translation. “cs_cz: ‘Pro instalaci aplikace na Váš %device, stiskněte %icon a v nabídce Přidat na plochu.'” I’m not sure if this is literal translation, but its user-friendly czech sentence.

    1. Damn! I made this with correct utf-8 codes, but i didn’t think that it will write corectly with diacritics right on the page. PLS find the correct UTF codes

      1. Matteo,

        I’m using godaddy linux hosting. I’m trying to make this work but for some reason it looks like it’s not recognizing the CSS because it drops in as a text that says

        Install this web app on your iPhone: tap and then Add to Home Screen. x’

        But not the normal bubble that iPhone 4S shows.

        I followed all the instructions but for some reason I still cannot get anything but text dropping down. Sorry if this seems like a dumb question but I’m a bit of a newbie at all of this and just trying to learn.


  131. I’m using godaddy linux hosting. I’m trying to make this work but for some reason it looks like it’s not recognizing the CSS because it drops in as a text item rather than a bubble.

    I put he css file in the same folder as the .js file and it still didn’t work so I then put the css file in the main directory and that still didn’t work. Sorry if this seems like a dumb question but I’m a bit of a newbie at all of this and just trying to learn.


  132. Hello Matteo,
    Thank you for this handy and versatile script. It did save my day and I tried to make a small donation, but it was not clear how to donate in US dollars. I admit I am clueless about euros. Please advise.

    1. Never mind, as you know PayPal took care of the conversion with no problem.

      Thanks again for a very well done script.

  133. Here’s a fix for a problem I ran into on jQuery Mobile 1.0.1 using the “touchOverflowEnabled: true” option. When set to true, the “add to home” bubble would drop down too low (below Safari toolbar). I was using touchOverflowEnabled for fixed toolbar support, but jQuery Mobile 1.1 deprecates touchOverflowEnabled in favor of real fixed toolbars so soon will be a non-issue.

  134. Perfect script, thank you! Just one serious problem: If private browsing is activated in Safari, the javascript returns an error as the client state cannot be stored in client database (I guess). Maybe this should be investigated in, to not display the ballon if private mode in browser is enabled. I could reproduce the problem on ipad2 and iphone4s.

    1. Do you like to address this issue? – Any feedback would be much appreciated. Thank you.

  135. Great script and easy to use. I removed the website sizing code because both the iPhone and iPad resize to suit their screens

    Other than that the script is great, just what I was looking for.
    Thankyou for a great script I use this on both my & sites

  136. Great script and easy to use. I use it on both my .com and .mobi sites.

    I removed the meta name=”view” from the coding because bith the iPad and iPhone resize to suit.

    Thanks for some nice coding

  137. I’m having an issue where after I’ve installed the web icon, then I return, it prompts me to re-install. I would prefer to never show the “add to home screen” once the the icon has been installed.

    I have added the following to the header

    but I’m still getting ask to install the icon.

    help is greatly appreciated. Fantastic script by the way.

  138. If the app hides the url bar then positioning ends up being wrong. For example if the following code is used.

    setTimeout(function() { window.scrollTo(0, 1) }, 0);

      1. Thanks for the code, very useful! Do you have any further information on how to solve the minor issue with hiding the address bar? I’m pretty new to .js so any guidance is much appreciated

      2. Set the autoload to false. Then add an onload event and place the function inside a 1000ms timeout:

        function loaded() {
          setTimeout(function () {
          }, 1000);
  139. I was using the earlier version with success. HOWEVER, when using v2.0 I notice this problem:
    — the icon (add to home screen- the box with arrow) does not show in the bubble.
    Feel free to look at my site.

  140. Never mind! It suddenly started working after I burned some incense. Phew!
    Thanks for the nice script.

  141. Is there any way to adjust the display frequency of the bubble with something other than minutes? Could you display it, say, every 15 (or X number of) page loads?

  142. I have added a ‘add to home screen’ code to my standard website (its not optimised for an iphone) to show message about downloading my iphone app. There is no need to do an iphone optimised site (for my website) but I do like the idea of them seeing this baloon offering to download the app from the store.

    The problem is that it shows tiny and practically impossible to see. Is there any way to make it full size and not reflect on the size of my page?

    1. add the following to your header.php and the files in the js folder.

      <link rel="stylesheet" href="/js/add2home.css" type="text/css" media="screen" />

    2. I cannot seem to get it to work in wordpress, I have tried it with a few different themes, but it won’t work. I have copied the css and js files into their own directory, within the theme, but still no joy.

      Am I doing something wrong.

      1. never mind, I got it to work eventually. had to use
        <link rel="stylesheet" type="text/css" href="/js/add2home.css”>

        <script type="text/javascript" src="/js/add2home.js”>

      2. <link rel="stylesheet" type="text/css" href="/js/add2home.css”>
        <script type="text/javascript" src="/js/add2home.js”>

      3. looks like comments is stripping the php out,

        <script type="application/javascript" src="/js/add2home.js" charset="utf-8">

  143. Great work!… but… the message keeps showing for every page of the site even after added to the home screen… does that happen only to me? Am I doing something wrong here?

    1. Only load the script if the page is not in webapp mode, then it will not load at all when the page is started from homescreen. Example of javascript:
      if ((“standalone” in window.navigator) && !window.navigator.standalone){
      document.write(‘var addToHomeConfig = {‘);
      document.write(‘ animationIn: “bubble”,’);
      document.write(‘ animationOut: “drop”,’);
      document.write(‘ lifespan:10000,’);
      document.write(‘ expire:7200,’);
      document.write(‘ touchIcon:true,’);
      document.write(‘ returningVisitor:true,’);

  144. I just want to simply use a PNG file to drop down. Nothing else. What code should I use for that?

  145. Love the script dude.

    I just wanna know if theres an iPad update coming, even tho I’m using an old iPad (1st gen) the popup seems a bit off. It’s right on the edge of the screen when using both iPhone 114×114 Retina icon and standard iPad 58×58 icon. It looks awesome on the iPhone but looks awful on the iPad.

    Will this be fixed in the next update or do I need to find a workaround?

    Many Thanks!

  146. What is the best way to determine whether the balloon is currently displayed?

    I want to use addToHome.close() to make sure the balloon is hidden when the user takes certain actions. But it seems that if the balloon is not displayed, calling addToHome.close() generates an error.

    TypeError: Cannot call method ‘querySelector’ of undefined”

    I assume it’s just because close() should only be called on an open balloon. Or am I perhaps doing something else wrong?

    That question aside, this plugin is working great for me.

  147. Hi there,

    this is a great script!!!
    Works perfect!
    I’ll let it run for a while and than donate a bit – for sure!

    Greetings, KH

  148. Wonderfull script. Very easy to integrate and very ‘powerful’ too. Thanks. Because of this it’s a pleasure to show a little financial support.

  149. Hi, I am going to sounds like an amateur here, but where do I need to install the script – ie. I get where to insert the code in the page, but do I need to also upload the javascript file onto the host server and if so where should I put it? And how should I nominate the path in the code?

    1. the naming it’s up to you. if –for instance– you upload the script to your server under the addtohome directory, then link to the files like so:
      <link rel="stylesheet" href="/addtohome/add2home.css">
      <script type="application/javascript" src="/addtohome/add2home.js"></script>

      1. ok, thanks.
        The script file downloads as a zip file. Do I need to extract all the files from the zip file first before uploading it to the server? Also, do all the files in the zip file need to be uploaded or if not, which is the file to upload?

  150. Hi there and thanks for this great script.
    Is there a possibility to open such a little box when loading which opens a or .html as popup and closing as well?

  151. Doesn’t resize properly on iPhone. Very small hard to read. Is there a fix for this? iOS5 problem maybe?

  152. I would like it more if it would display on the whole Screen..
    Like a “big” Message.

    If you have a big site, it’s just very little.

    Can you help me?

  153. There seems to be a problem with localStorage.setItem, i think it’s a security problem, maybe only iOS5, so it’s preventing the X (close), returnungvisitor and expire functionality to work correctly.

    1. could you please test my online demo and verify if that dialog is actually too small? I suspect people having trouble with balloon size don’t use initial-scale:1

  154. Hi, good morning…

    This script is awesome, all settings tested and working perfect, but I have a little issue, after “add to home screen”, all my links open a new safari tab, this is my deb site:

    Any ideas????

    Thanks a lot…


    1. full-screen for just the home page and browser-bar windows thereafter is just the way iOS web apps are formatted

  155. Hey. I can implement this ( ADD TO HOME SCREEN) module into my mobile jomla website ..? If I can how do I do? .. I have tried a little back and forth but no luck .. I’m far from good at making websites. So I hope there’s someone who can help me … thanks in advance

  156. Hi

    On my iphone the website is too big and needs to be resized to fit the screen but the buble is the perfect size.

    We did have it working the opposite way where the website was resized to fit the screen but the bubble was too small, then we added the following code and it went the opposite way as stated above. Can you suggest a fix. FYI great feature.

    My website link:

    <meta http-equiv="Content-Type" content="; charset=” />

    1. Hi – I took out this line of code and the website is resized to fit the screen but the bubble is too small. Any suggestions would be very much appreciated.

      Website (in Construction)

      Line of code:

  157. Hi there, above all thanks a lot for you great script. However I am experiencing a little issue, the same as HomeroMx.

    Each page I open from the WebApp open in a new safari tab, any idea to stay in the full screen webapp ?

    Thanks in advance.

    1. Pretty sure that the full-screen feature for just the home page and browser-bar windows thereafter is just the way iOS web apps are formatted.

  158. Hi, in my iphone does not appears this option, i need customize ?

  159. Hello, I want to donate to you but I REFUSE TO USE PAYPAL. Oh well, your loss. Moneybookers is great, so are PayMate. Offer something other than PayFuck, eh, I mean, PayPal, and I’ll be glad to donate 20 bucks!

      1. sorry, but i’m not going to sign up to something just for one donation. i’ve shared on facebook and twitter. i love this script – it used to work for me i know, but i have no ios devices to test on now so i’m just going on faith it’s working on my sites. i’ve tried testing in safari with the ua set to iphone or ipad under the developer menu but it doesn’t show. hope it’s working!

  160. Is there no option to say: “once a user dismisses the bubble I don’t want to show it again” ?

  161. Great script Matteo. Works perfectly so far. Any idea on when Android support will be added? Days? Weeks? Months? no pressure haha keep up the good work!

  162. First of all, great script! I use it on multiple sites and works like a charm.
    However, I’ve added it on a new site of mine and the bubble keeps returning, even though I ‘install the webapp’. Any idea what could be wrong?

    Here’s the code (same for all my sites):
    var addToHomeConfig = {
    touchIcon: true


  163. does this work in safari when under developer settings the ua is set to an iphone or ipad? i’m trying to test like this and it just won’t work.

  164. I cannot get this to work on my wordpress powered blog. I have unzipped and uploaded as is to the plugins folder and added the following in header:

  165. It wouldnt let me post the code so where it says path too I have used /wp-content/plugins/cubiq-add-to-homescreen-508e479/style/add2home.css AND /wp-content/plugins/cubiq-add-to-homescreen-508e479/src/add2home.js

  166. Hi

    Thank you for the great script.

    I’m having a similar problem to Chris.
    I have set apple-mobile-web-app-capable to yes, but, even after adding my site to my homescreen, I still get the bubble appearing on every page. I hav ethe code below in my . Am I doing something wrong?



      1. Hi Matteo

        I can’t post a link to my client site as I’d get into bother 🙂

        I did however upload your examples to a test server, which seems to be doing exactly the same thing on my iPhone 4:

        When I add the link to the homescreen and then open Safari again and refresh the page, the bubble pops up again.

        I did just update iOS to 5.1.1 (9B206). Could that be anything to do with it? Or am I missing something here?

        Many thanks


      2. Thnaks for looking Matteo.

        I just tested it on my partners iphone 4. I load the page, no bubble appears. I close the browser and re-open it, refresh the page and the bubble appears as expected. I then add the page to the homescreen. I then re-load safari and refresh the page and the bubble appears again.

        I’m out of options.

        Thanks again.

      3. Hi Matteo

        Sorry, should have said, I get the same results with and without the cache being cleared. I’m clearing the cache fully under settings.

        I just tried your link on my iPhone4 and iPad2 (both with latest update):
        and get the same result again. The bubble popus up after the link has been added to the homescreen.

        I only have access to 2 iphones and an iPad2 I’m afraid.

        Driving me potty.

        Many thanks for your help


        1. I totally need to see a video of this 🙂 Really I cannot replicate on any of my devices. Please remember to completely kill the browser (remove it from background) before clearing the cache. Even better try to reboot your iphone.


  167. Doh, wouldn’t let me post my code either, but I set the web app to enabled etc. Should I add that before or after the call to the js and css?



  168. I have the tool embedded on a page where there is also an iframe that loads google mapps.

    Somehow it’s using the url of the iframe rather than the url of the page itself as bookmark link…..any ideas why? thx 🙂

  169. We are using iPad. When we open our web site in Safari we have ‘Add to Home’ pop up. If we Add it to Home we get an icon on the iPad screen. If we close that session and again open it in Safari we again get ‘Add to Home’ pop up. How can we avoid that. We checked the same functionality for other site e.g. espn. For that site the ‘Add to Home’ pop up does not come back once it is added to screen on iPad. Is there any way to find out that whether this site is already added on the screen of the iPad?

    1. you can make an educated guess, but it’s not bulletproof. On ESPN they probably set a cookie if you come from the URL that shows the balloon (instead of simply

      1. Hi Matteo. Thank you for reply. One more question, if we are able to add web app on the screen of iPad (with the help of javascript), then there should be a way to find which web apps are present on the iPad screen. Is there such kind of javascript/jquery to find out web apps on iPad screen.
        Thanks in advance.

      2. Hi Matteo, did not find reply button below your latest comment. So asking my question here. When we click ‘Add’ button from pop up to add app on iPad screen at that time which event/function is called? Can we handle/update that event/function? Please let me know as we require it urgently.
        Thanks in advance.

  170. Hey, great script though it seems to have a problem with iOS 5.1.1 which causes the icon and splash screen to fail to load.

  171. Hi Matteo, first of all thanks for the nice script.

    We have a problem with the following:

    The bubble opens on every page, because we are using a cms. But this is ok.

    Now if you add a page to the home screen, the bubble will not appear on this particular page, but on every other page.

    It would be nice if the script only added one particular page to the home screen (the homepage) and does not appear on every page after that.

    Is this possible or do we have to only include the script on the homepage and not on the following pages?

    Thank you!

      1. Thanks for your answer, of course this JS just points to an iPhone feature, so the url cannot be changed. Your answer is the solution we are looking into right now.

  172. I love this script! I would like to customize it so there are different apple-touch-icons for each college. Is that possible? I’ve tried adding another icon called apple-touch-iconcc.png, editing css and js file but it always uses the standard apple-touch-icon.png. Ideas?

    1. maybe you have caching issues? Remember to place just 1 touch icon per page per device and add a “scrambler” to the image name to destroy cache (eg: apple-touch-icon.png?v123)

  173. «If the user intentionally closes the balloon, it won’t show up again for all the duration of that session.»

    How I can owerride this?

  174. If you want to go back to the first page when attempting to move to the next page on the last page you can place this in your onScrollEnd function.

    if (tmp) {
    this.currPageX = 0;
    this.scrollToPage(0, 0);
    tmp = false;


    if (this.x == this.maxScrollX && !tmp) {
    tmp = true;

  175. Thanks for this great script. Is there any way to prevent balloon from appearing from the website view (not from the webapp) if the app has already been added to the home screen?

    1. you can change the page hash when the user reach your site, if user bookmarks the hashed page you set a cookie which prevents the balloon to appear. Not 100% failsafe though

  176. I tried to install your brilliant add2home but I am not sure it is compatible with our website could you tell me if it is or not please?

  177. I need to check, in an URL following to the one where we ask the visitor to install icon, to check if it is accessed by the icon app.

    I mean… if user does not install shortcut, detect it, and redirect to a page saying something like “you need to install shortcut to access this site”.

    Is it supported somehow?

  178. Has anyone had a chance to test this on iOS 6?

    Are there any changes coming with mobile safari that will impact this?

      1. iOS6 has the share icons in a slightly different place in mobile safari. Beggars can’t be choosers, as the saying goes, but do you have any plans to update the script?

  179. Hey, this code is exactly what I need, but I’m having trouble setting it up. How do I install the javascript to a website hosted on Hostgator / WordPress? Thanks for the help, I’ll donate if I get a helpful answer.

  180. Thanks for the script, it’s perfect except for one issue – the balloon image overwrites my favicon so instead of using my favicon on the homescreen it uses your balloon image. How can I correct that? Many thanks!

    1. Sorry, missed the WEB APP CAPABLE section. Will implement that immediately. Thanks for thinking of everything!

  181. Awesome script! Thanks for creating this.

    I am having one issue with the iPhone 4/4s only in which the bubble displays in the middle of the page but and doesn’t lower until the user scrolls. As I said this just seems to be an issue on the 4/4s. Any idea why?

      1. Has anyone found a solution for this? I added code to remove the address bar:
        window.scrollTo(0, 0)
        And since then, it shows up in the middle of the screen.

      2. be sure to remove the address bar *before* the call to addtohomescreen. Or call the balloon programmatically after a few millisecond from page load

  182. Hi Guys,

    thank u for that beautiful script. Attention, i am new in coding.

    Please, i have a Problem with the touch icon, can anybody help me ?

    i changed the header like i should.

    but i want to change the icon as well, so i insert this line in the header.php:

    and put the icon on the servers.

    Now, so my hope, the bubble should show the icon !?

    Am i wrong ? Couse it doesn´t show up.

    Any help ?

    Thank u very much

  183. Your script will not run on iPhone 4S Safari browser with private browsing enabled on a jquery mobile site.

    It causes the whole page to never load and I get this error in the debug console:

    Javascript: Error
    QUOTA_EXCEEDED_ERR: DOM Exception 22: An attempt was made to add something to storage that exceeded the quota.

    I’m using the autostart:false setting and I’m running the script myself with

    I had to use a try catch around the so that it wouldn’t stop the website from loading. You should make note of this in your “AutoStart” section of this page.

    try {;
    } catch(e) {
    alert(“disable private browsing”);

    1. Indeed, private browsing prevents localStorage from working, so it throws the error. I would be nice if the script supported that… 🙂

  184. Two questions:

    1. Is there anyway to rename the “page title” that shows up when they click the add-to home screen button? That is have it pre-selected and filled in to something the webmaster specifies? My site defaults to something that is too long (> 11 characters).

    2. It seems as though the javascript recognizes that it has been installed on the homepage, but every sub-page will ask if you want to add this to the home screen (wordpress site).


    1. 1. it reflects the page title tag (can’t be changed)
      2. include the script only on the homepage (or set a cookie and show it only once)

  185. Hi, is there a way to link the touch icon to another homepage? So if you add it to your homescreen the icon should open for example the app store ore something else.

  186. I’m having a wicked frustrating time getting this to play nicely with my scrollbar hider code. It seems to display the balloon “too high” on my iPhone4. I adjusted the bottomOffset to -46 it works. But then looks horrible on iPad.


  187. Thanks for the script!

    How do you get this to work on non mobile devices (desktop)?

    I see you can bypass the compatibility checks by calling but this still doesn’t work if you’re on a desktop. I want to be able to see it on my desktop so I can tweak the CSS with dev tools.


  188. How to enable this on Safari only? What if visitor is using Chrome, Opera, Skyfire etc. on their iOS device?

  189. Doesn’t work if your home screen is “full”.
    That is, if you have 11 screens full of 4×4 apps.
    That is, if you have 176 apps.
    I have too many apps.

  190. Many thanks for the excellent script. Excellent touch for our site that we’ve just put live!

  191. super thanks for the great effort and amazing bubble prompt.

    i have a question in mind though it might out of the topic!

    is it possible to restrict adding to home screen function, for only the index page ?

    thanks again.

  192. Wow. This is go great, it really took my bands mobile site to the next level and it simply looks fantastic. Very easy to set up and add to your existing code. Thank you very much guys!

  193. Perfect. Works like Charm. Is there anything for Android browser? Thank You.

  194. Thank you so much, that was exactly what i was looking for, the scripts i download worked perfectly. You made it look so easy. Thanks again!

  195. As Ryan said, when you remove the address bar to make the viewport bigger, the balloon doesn’t go all the way down. When you switch to landscape and back to portrait, the balloon is at the bottom, where it’s supposed to be. Putting in a negative offset messes everything up so I don’t want to do that.

    Could you adapt your script to support this please?

  196. Its a great script. I have recently used this script but find some issues.

    Would you please help me out?

    When I test on iPhone and call the web app from the stored home-screen button then first page opens correctly, but then all following pages open again on the web-browser.

    how to close this box – nothing happens by clicking on the X

    How to add logo when web app will be stored on the homescreen : now there is a screenshot with the actual screen


  197. Where do we put it if we are using a wordpress site, hosted on wordpress. I have an index.php but I dont know where to add the js head code mentioned above since its not an html page.

  198. Hi Bro,

    Very nice script and thanx for providing it.

    Some guys, stole your code and is selling it at Warrior Forum. His add2home.php has this “/*!
    * Add to Homescreen v2.0.1 ~ Copyright (c) 2012 Matteo Spinelli,
    * Released under MIT license,

    Here is the sales page


    1. Actually, they didn’t “steal” the code and followed the licensing rights that they were given to the software.

      They had every right to modify and include the script in their software per the license agreement –

      1. go for it, that is all what the MIT license is about. you could make a small donation to the project if you are so inclined, or maybe contribute to the code with your modifications. You know, just to keep the good karma.

  199. Hi Matteo,

    Thanks for the brilliant script!

    One point which has come up numerous times in these comments, but has yet to be answered, is that of the ‘X’ (close) button. It does not (always) work.

    I say does not ‘always’, because the exact same code DOES work on my iPad 2, but does NOT work on my iPhone 4 OR new iPad (3rd gen). As I said, this issue has also been raised by a number of other users so it is not just me.

    I am afraid I cannot think why this would be, but I think it definitely needs some attention!

    Thanks in advance,


      1. I am using your source code as is. Are you saying it is working for you on retina devices?

        I cannot test it on the iPhone 4S, but I assume it would be the same as on my iPhone 4 and new iPad.

        (RE your suggestion, I tried assigning the trigger to part of the text but it also does nothing and that can’t be a sizing issue?)

      2. That’s strange! I will start from scratch again and report back 🙂

  200. “The MIT license this was released under permits use of this code in proprietary software such as this WordPress plugin.”

    You can’t have ‘proprietory software’ for a wordpress plugin. WordPress is GPL and all themes and plugins should follow the licence. While you can sell any plugin/theme you cannot stop anybody doing whatever they want with your plugin so that rules out ‘proprietory’ doesn’t it.

  201. Hi would you mind sharing which blog platform you’re working with? I’m going
    to start my own blog in the near future but I’m having a tough time choosing between BlogEngine/Wordpress/B2evolution and Drupal. The reason I ask is because your design and style seems different then most blogs and I’m
    looking for something unique.
    P.S My apologies for getting off-topic but I had to ask!

  202. Hi…my questions is ¿how I can detect if the icon exist in the home screen?

    I need to show the message “install the app in your…” only when the icon does not exist…

    thank you for your help… 😀

  203. So i can use this script for free on my Website? I only have to write ADD2HOME by Matteo Spinelli?! THX

  204. Hiya,
    Great piece of code, congrats!

    Is there a way of forcing the Add to home popup to appear before the DOM is fully loaded? As in immediately as the page opens up?

    I’m using it in conjunction with a preloader script for an offline web-app, and it would be great to have the prompt open up even while the preloader is running, and not wait for all of it to load up?

    I’ve tried adding in at various points, but that didn’t work as planned…

  205. Has everyone been able to successfully get the touchIcon to show up? Mine is just an empty box on my ipad no matter what I do.

  206. Really great script. Quick note about use with jQuery mobile – the strange mid-page floating bubble problem will occur (until you scroll when it then corrects itself) unless you make sure to define the following in your css:

    ui-page {height: 100% !important;}.

    1. And when I said

      ui-page {height: 100% !important;}

      what I really meant was

      div.ui-page {height: 100% !important;}

  207. Would be great if someone made this into a plugin… Would go mental in terms of popularity 🙂

  208. I would like to ask if I can provide two message of different locale to be shown base on the user setting. (en_us and zh)?

  209. I think that the problem with de X button is the private browsing in the device. I had it active and the X didn’t work. I modified the function close in the js file and put an alert there. The alert came up after the default 20 seconds… Just like if the call was blocking somehow.

    Then I decided to switch off private browsing and the alert appears just when I click the X button, and the balloon is closed. Maybe it fails to write whatever it’s described at ‘More power to the user’ when private browsing is active.

    Just my 2 cents.

  210. Hi, this is absolutely brilliant work done by you.Thanks a ton.I was wondering if it is possible to call the “arrow dropdown” once you touch the bubble.

  211. is there a way to easily increase the size of the icon and close button for the popup?

  212. The balloon is still loading even the user add it to the home screen. Is there a way that the script is detecting if the mobile device already add it to the home screen so it will not show again? Thanks.

      1. I’ve read the docs multiple times and I can’t find it either? How can we enable this because it’s really frustrating.. But very nice plugin! 🙂

      2. Curious if there was ever a solution for this, I’m having this problem of it showing up even though it’s been added to the homepage

      3. Sorry, the negation is unnecessary :). Below the better code (works for me):

        isStandalone = "standalone" in window.navigator && window.navigator.standalone,

      4. Sorry to hear that, for me the combination of adding proper meta to header and changing this line works. Maybe try testing on a fresh and simple project?

      5. This happened to me because I was manualy triggering the notification using the command. Unfortunately this action still opens the message even if a shortcut has been added.

        I worked around it by storing a flag in localstorage if the application is launche in standalone mode. If the flag is set, I am not calling the show command.

        Hope this helps.

  213. Grazie mille molto utile, ma il QR code non funziona ha un url sbagliato.

  214. Good morning, excuseme for my bad english but can’t use this script in my page. i don’t know why.
    maybe for i have joomla cms? the style add2home.css it’s copied in template.css and the script it’s copied in my index.php.

    i don’t understand why no show the ballon. thanks

  215. I need to change the background colour of the touch icon. It’s light grey now. Where can I do that in the CSS?

    I have a transparent icon with some white text and iOS automatically adds a black background when it creates the app icon for the home screen. I’d like this dialog to show the same icon.

  216. I found a problem with the script. Explorer 8 throws an ugly out of memory message.

    The message is “out of memory on row 7”.

    I know Explorer 8 is slowly dying but it’s still at 10% so I need to fix it. Can something be done to the script or can I hide the script from IE8 somehow?

    1. I found the problem. IE8 chokes on the CSS file, not the script. So I hide the CSS from IE with this:

      script here
      css file here

  217. Thanks for the great script. One question: where is the add-icon.png in the javascript or css? I want to modify that image, but I can not find it. Many thanks for any reply!

  218. Love the feature .Its a fitting answer from web apps to the native apps.

  219. Hi! I was using your script and until few days it worked perfectly.

    Now for testing whats wrong I opened your demo on my iphone4s and it works.

    Then after copying your original demo to my server it doesnt show up anymore. Do you have any clue where could the problem be?

    This is the link:

    1. Okay its working again (maybe some safari cache problem?)

      Thanks again on your script and here is the translation for Croatian language:

      hr_hr: 'Instaliraj ovu aplikaciju na svoj %device: klikni na %icon i odaberi Dodaj u početni zaslon.'

  220. Firstly id like to commend you on a great piece of code. Simple straight forward but still a great feature. However i have tried many times to implement this on my blog (tumblr) but with no success and i wanted to know if this was not possible to implement on my blog or if i was doing something wrong. I tried simply placing the code as well as inputting the code itself as javascript within my html and also tried manipulating it but with no success… Any help would be greatly appreciated.

    Thanks in advance.

  221. I am using this script in my jquerymobile app. I load all the pages in ajax and I need to show this balloon in specific url, lets say, but it shows when the page is loaded. how to prevent the balloon to load and show in specific url?

  222. Thanks for this! Your code is the best yet! I have a question regarding the configuration. Can I just change the settings in the add2home.js or do I need to follow your suggestion: “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.

    ALSO, is there a script for Android/Blackberry/other devices?

  223. I loved as much as you will receive carried out right here.
    The sketch is attractive, your authored subject matter stylish.
    nonetheless, you command get bought an nervousness over that you wish be delivering
    the following. unwell unquestionably come further formerly again since exactly the same nearly very often inside case you
    shield this increase.

  224. Hi, anyone modified this to work with Android devices? That would be superb, Thanks.

  225. At first I thought the bottomOffset setting was not working. Then I realized the script was assuming that the address bar was present. I have hidden the address bar by auto-scrolling, and that was bringing the balloon up towards the middle of the screen.

    I have addressed this by using bottomOffset: -60. Do you have a better suggestion? I am only testing this on an older iPhone 4s, and I am wondering if this number will be incorrect on retina devices.

  226. I tested this on iOS4 and 5 working fine but on iOS 6 when we create shortcut to screen and try to browse that site it open a black page and it keep try loading it….why so?
    I am having internal site

  227. Question. On the iphone5 when you add to home screen all that is fine. When I tap to open what was added to home screen. The height of what is being viewed is not going the full height of the screen. Any fixes for this.

  228. If you have multiple “apps” on the same website (website/app1, website/app2) the localstorage in the browser is the same. So after being prompted on loading the first app the user will not be prompted on the 2nd app as it appears he is “returning” too soon. Maybe should clear time in localstorage if app is added to home screen.

    1. there’s no golden solution to detect if the website has been added to the homescreen. You should detect that yourself based on your app and clear the localstorage accordingly

      1. No I am still looking for a fix. Anyone at all know of a fix for height issue on the iPhone 5. Thanks.

  229. This script rocks.

    I just have a question could someone teach me how to track the button or how to track if someone has installed the icon to their homescreen?

    I want to see how many people open the “homescreen icon”.

    Thanks a lot!

  230. in iOS6 I tried add to home screen button to add my wbsite shortcut but when I open using that shorcut it opens white page and aloader that keep loading ….

    Earlier versions of iOS it works fine..please help

  231. Thank you for this amazing script.

    I’ve tested it on my site with my iphone 4s IOS5 but when I test it on my wife’s iPhone 4s which had just been updated to IOS6 it doesn’t show up.

    Any ideas why?

  232. Scrap that last question…my Mrs had private browsing enabled on her iPhone!

  233. Its a great script but on my ipad mini the bottomOffset does not work properly, it works more like a top offset. Also, is there a way that the x position can be set a percentage rather than a fixed value as the baloon does not line up in the middle of the page when I rorate the ipad.

  234. Is there a way to disable add2home from showing up on iPad. I’m looking to only have it appear on iPhone/iPod.

  235. Thanks again for this

    I’m testing this on my iPhone 4s IOS5… If I add my site to my homescreen in landscape view & then access it from the homescreen icon in portrait view, my site shows as if still in landscape i.e. zoomed in.

    Whilst this is not a big problem, my site is mobile-optimised with a fixed view and as such does not support zooming in & out.

    Do you know of any way to fix this?

    Will donate $10 for a working solution.


  236. Hi,

    Many thanks indeed for the great script. Can I ask if it is possible to not use current URL for saving to home screen and use the home page URL instead?

    We are an ecommerce store and if the prompt appears outside of the home page, for example on a product, well that page could be deleted once sold out, rendering the shortcut useless.



    Always Riding

  237. Somehow, the close button in the corner of the bubble has no effect. I am testing this on an iPhone 5 and iPad 3, both iOS 6.

    Also the position of the iPad bubble seems a bit off. The arrow does not point towards the “sharing” button.

  238. Hi Matteo,
    The qrcode does not work. I downloaded the examples, and they do not work. I’m iOS6 / iPhone 4s. Can you confirm that the script is still up?

  239. Matteo, the problem that I mentioned first and that has been confirmed by Web Design Boulder seems to be based on the iOS version. It does work on iOS 5, but does not work on iOS 6. Could you look into this?
    Thank you!

      1. I do not think that matters. The demo on this site has the problem, too.

    1. I just tried it on 6.0.1 and (guess what) I can’t replicate the issue. If I click the X the popup closes correctly.

      It’s hard to debug if I can’t replicate the issue. Anyway, I’d put the close sensible area on the whole balloon. That should help.

  240. Is it possible to set custom logo as a short cut icon rather than a screenshot

  241. Is it possible to have returningvisitor do the opposite? So first time users see message, returning users do not see message?

  242. When I click the icon after adding it to the home screen it’s not opening the website inside the safari browser – not even in your demo. I don’t see any browser – just the page full screen. How can that be?

  243. Pop up says the app is called ‘settings’.
    Can we manually set the name of app for shortcut..

  244. This is awesome but it keeps showing up even though it’s already installed.

    Is there a fix for that? Please help.

  245. Is there a way to change the URL to the custom url scheme for my app before the user saves it on home screen?

  246. Is it possible to make this appear only for first time when a user come to your site.. So in other terms not to show the message to returning users?

  247. Hey great code! Thanks!

    Mine works, but when the bubble pops up, it is very very tiny. Only when I zoom in does it become larger and eventually the proper size. How can I fix this?

    Thanks so much!! Happy New Year!!

  248. Yeah man, I just did it, although I’m working out the kinks. What’s your host? You simply download the files (“Get The Script”), and upload the css and js files onto your host. It can be anywhere, like in some folder. Then add the above code to your header file, where you see other “<link"s and "rel"s. (header.php is located under wp-content, themes, your theme). Just add the two lines of code right below the other similar <link lines at or near the top. Then change the /path/to to match the path you uploaded the files to! And voila!

  249. The close button of the balloon doesn’t work in Safari’s private mode. Is there a work around for this problem? (iOS 6.0.1, iPad 4)

  250. Dear wordpress customers:

    from your ftp client (server)
    1. create a folder (ex. iphone)
    2. upload add2home.css and add2home.js in your folder
    3. go to appearance/editor
    4. search header.php and put the code

    and replace patch/to/ by your created folder.
    * if you have problems. put your complete url



    1. Ok, so I have a wordpress site. I went into my ftp and added a folder named iDevices into my wp-content folder. I then added your add2home.sss and add2home.js files into the folder. I then went to appearance/editor, header. php and entered the code:

      I then tried to open my website on iPad and iPhone, but there is absolutely no add to home screen button appearing. Is there another step that I’m missing?

  251. The script works pretty well on my HTML5 web app, except when I turn On the icon feature (I set the Config variable before the .js file, as instructed) it displays “null” instead of my icon. Any idea on what I did wrong or what the problem might be?

    Thanks a lot. It’s a wonderful script, by the way.

      1. Yes, I’m using the latest version, and have the icon normally referenced inside HEAD as:

        Still, I get a “null” message instead of the icon.

  252. there happened a Javascript error that “SECURITY_ERR:DOM Exception: An attempt was made to break through the security policy of the user agent”. I didn’t know what’s the matter, could you tell me why?

  253. Is there a way to make the “app” open up to a specific page?

    I want the app to always open on

    even if they saved the app from

    How can this be accomplished? Thanks in advance,


  254. Hey Matteo,

    Great plugin! The only problem i have is one which happens on just one iphone 4s. I have no idea why but on my other iphone 4s is does work.

    It’s the same problem multiple other have been experiencing with the close button. Mine simply does not close at all. Not even with the latest version where you made the whole bubble a close listener.

    I’m using Sencha Touch 2. Thanks!


  255. Is possible to check if the user added the shortcut on the home so not showing again the popup?

    And the last thing, if set expire= 60 it will show the popup again after 60 minutes right?

    Thank you

    1. Is possible to check if the user added the shortcut on the home so not showing again the popup?

    1. the script should be included only on the pages you want the popup to show up. if you can’t do it server side you could check window.localtion.href

      1. Hi Matteo, could you elaborate on the use of the window.localtion.href command to do this. I have WordPress sites and have placed the code in to the header.php file however I am getting the pop-up on every page and would like to just have it appear on the home screen or just appear the once when you visit the site no on every subsequent page clicked after landing. I tried adding the code however this does not appear to work in the WordPress environment. Thanks for you support and Awesome code! 🙂

  256. It seems like a great plugin except that I experience this strange behaviour.

    On my iphone or ipad it drops down and is only visible for like 50% of the opacity and then it dissapears again. I did use the example code from the download.
    Do you have any idea?

  257. hi, im jsut starting html and css.. but ive been using ipod touch for almost a year.. i found your tweak to be very useful… im fond of making html based shortcut for my apps / tools on my work.. ive got tons of tools, so i decided to create a html page and link all .exe files + my notes + spiel + email updates + notepad on a single page.. if its posible, you could make / teach me/us to create a shortcut for toggles on the settings app..

  258. Ok, so I have a wordpress site. I went into my ftp and added a folder named iDevices into my wp-content folder. I then added your add2home.sss and add2home.js files into the folder. I then went to appearance/editor, header. php and entered the code:
    I then tried to open my website on iPad and iPhone, but there is absolutely no add to home screen button appearing. Is there another step that I’m missing? Any help would be greatly appreciated!

  259. Thanks for the tutorial!!!
    Everything works great!
    So, you mentioned a different way of preventing the balloon from showing. I don’t have the “web app capability”, I include the script to the home page of my website. My problem is that I’m new in the matter and I don’t really know how to check for a special url hash. Could you please show me an example? or a different option?
    In advance,
    Thanks very much.

  260. Very nice but it seems like once I am using this if I add my web app to home screen and then open my web app from that home screen icon it no longer has the address bar in safari. Also in my page I added to homescreen I have redirects with rel=”external” and new instances of safari are then opened. Anyway to keep the default behavior when I added to home screen before using your plug in?

  261. Thank you so much for this script! I do have one problem though.. When I scan a QR code the link will not open directly in Safari, but inside the QR application – and then you don’t get this popup message..

    Is there a way to solve this?
    (I also tried scanning your QR code, but this is also opening inside the QR app, and there is no popup..)

  262. I had to change the event listener to touchstart – the click event did not work on my iphone or ipad to close the balloon.

    if ( options.closeButton ) balloon.addEventListener(‘touchstart’, clicked, false);

  263. Hello!

    This is an AWESOME article. Thanks!!!

    The only problem I have is that when I set touchIcon:true, it shows “null” in place of the icon.

    The head tag has

    Am I doing something wrong?

    1. You should ALWAYS set the icon size in the apple-touch-icon link tag. Eg:

      <link rel="apple-touch-icon" href="path/to/img.png" sizes="144x144" />

  264. I use Rapidweaver and have added the Standard Usage code to the head and the addtohome.css and add2home.js to my htdocs folder, but nothing happens, any idea what I am doing wrong?

  265. Hi,

    I miss something like a developer-Mode to test and style the bubble in desktop-browser. Something like Desktop=true as a parameter. Mayer there is a Otter solution i dont recognize!?

    Thanks for this Great Script.

    Gereinigt from Germany

      1. Thanks for the fast answer. Iam Looking forward for that Feature!
        By the Way i hate autocorrect 😉

  266. First of all as everybody else, I want to thank you and congratulate you for your great code.
    I added the meta code you provided above for “apple-mobile-web-app-capable” but it keeps showing the popup. Have you any suggestion ?

    Thanks a lot !

  267. Hi,

    This works great when I go directly to my mobile website URL. However when I visit my regular homepage URL and then is being forwarded to the mobile website url, then this script is not showing up.

    Any ideas?

  268. Thanks for the plugin!
    Is great, but I found that it doesn’t work when private browsing is on, I added this bit of code to bypass the sessionStorage part. It could explain why the last commenter’s 2 phones are different..
    function clicked () {
    var canstore = true;
    var testKey = ‘qeTest’, storage = window.sessionStorage;
    try {
    // Try and catch quota exceeded errors
    storage.setItem(testKey, ‘1’);
    } catch (error) {
    if (error.code === DOMException.QUOTA_EXCEEDED_ERR && storage.length === 0)
    //alert(‘Hello, private browser.’);
    canstore = true;
    else throw error;
    if (canstore = false){
    isSessionActive = true;
    sessionStorage.setItem(‘addToHomeSession’, ‘1’);

    That was taken from here:

    Thanks again

  269. Hi

    Do you have set instructions on how to add this or a tutorial? Is it suited for wordpress?

    Thank you

  270. After adding to home screen and then opening the status bar on the bottom is missing. Is there a possibility to publish this again?

  271. Hi , thank you for the great plugin.
    I had a small question:
    Can you somehow trace how many people added the app to their home screen?
    Track how many click throughout Google analitics or something?

    Thank you

  272. One more question:
    Opening the site from the installed home screen there is on iphone 5 devices free space at the top and the bottom. Is there a solution to show it over the whole screen?

  273. Very nice!! And working on the iPad but not on the iphone (4). Like many others I am not able to close the message box (tested it on the demo site, before installing on my own site)

    Can make a movie if you want to.

    For the rest; great work!

      1. Hi, the iphone is an iphone 4 with IOS 6.1 installed.

        The video of the iphone behaviour is on youtube:

        With an ipad I visited the same demo page and it works there:

        It’s the same some of the others are saying in previous comments. Doesn’t matter where you tab the message will not close. Doing this on the iPad it works like expected. If you need me to test anything just let me know.

      2. I’m having the same problem but restarting my iPhone did not fix it. I tap the Close Button but the balloon will not close.

        iPhone 4s
        iOS 6.1.3 (10B329)


      3. I tried the hard reboot. It didn’t work. I went to your demo and the Close Button does not work their either. The only things I changed in the script were the normally editable “settings”. I didn’t change any code outside of those.

        I can’t remember what line this was on but there is a event handler for the Close Button. Someone said to change it from ‘click’ to ‘touchstart’. That didn’t work either. I changed it back to ‘click’.

        I also removed the other script from the page to see if there was a conflict. The Close Button still didn’t work.

  274. “remember to add the apple-mobile-web-app-capable meta to your page head”

    How can I know when to add this tag?

  275. Will this script behave the same on the Blackberry or Android OS? If Not are there codes or modifications that will do the same thing?

  276. Ive installed the .js file, and the .css file into the site, added the script in my wordpress website and its not working, can someone post a tutorial on how it works in wordpress???

    1. I figured out, the script that i install on my header needs to have the path to where the url is at needs to be set. so it can find where the .css and .js file is at. and now that i did that it works great!

    1. Does this ath suppoprts iPAD chrome and android chrome?
      In my iPAD chrome , the message is not getting displayed.
      Let me know if I need to configure something?

  277. When I run my application on iphone 6 safari, it shows the message, but once it showed it will never display again until I clear safari cache from Settings. Can I force safari to always show this message?

  278. I have added add to home screen as you recommended but I can’t get it to work.
    My application is rails based . following is the code that I added to my index file, which is a haml file

    = stylesheet_link_tag 'addtohomescreen', media: 'all', 'data-turbolinks-track' => true
    = javascript_include_tag 'addtohomescreen', 'data-turbolinks-track' => true

  279. Hi there,
    Have you made a Windows Phone addition/version yet?

    Thanks – helped a lot,

  280. Has anyone tested this on Android recently? Or the Chrome browser using the Android emulation? Neither seem to work. Chrome browser’s iOS emulation is fine, but my Galaxy S5 and Chrome simulations of Android both produce nothing — no guides and no feedback in the console.

  281. can you help with I can’t get this plugin to work I try using the wordpress plugin and the script.

  282. When i try to open the pop up programmatically like this:

    var addtohome = addToHomescreen({
    autostart: false

    I get the following error: “Uncaught TypeError: Cannot read property ‘lastDisplayTime’ of undefined”

    Could you tell me what the problem could be ?

    1. HI
      I was just wondering if you sorted this out as I’m getting the same thing

    2. Hi , iam also getting the same error, have you figured this out?????

      1. You have to specify empty options:


        or, in your example:

        var addtohome = addToHomescreen({ autostart: false });{});

  283. Hi Thanks for good js, i am facing one issue not able to load the image icon in the popup can you help me how can i do this. also in js file i show its support the multi language but how is there any demo for that ??

  284. Great plugin, but missing checkbox “never show again” for user in tooltip.

  285. looks great
    1) doesnt seem to work for me on iOS7 and Chrome
    2) would also love to see a ‘dont show again’ option

  286. Hi, very useful, very attractive, so many thanks.
    I just create a copy to train myself with your code … and I have 2 problems : (
    1/ Going to the end (after creation of the icon on my Iphone screen), I close Safari, I tap on the new Icon … and my website appears without the navigation bar.
    I didn’t find the code to have it.
    2/ Trying my test page on my macbook pro and/or my Imac (, the bubble appears on these devices. What do I have to change just to have them on mobile phones?
    Thanks for your help, Francois.

    1. Hi François

      Did you find a solution for this issue? I see a few people asked this question. Not sure whether we missed something in the documentation or not.


    2. The apple-mobile-web-app-capable tag is what is causing the site to display without the status or address bars.

  287. Hi – great script. Got it working BUT I am finding that when I click the icon that has been added to homescreen, it doesn’t show any updates made on the mobile site it is linked to. Those updates do show when the site is accessed from an icon that was added to the Ho,eScreen without using this script.So, i am guessing that something in the script is stopping users seeing updates to the mobile site in real time.

  288. Great plugin.

    2 things though:
    * I’m building a Swedish site and in Sweden a lot of people have the browser language set to English so they get the English message even if its a Swedish site, it would be great if you could set a language parameter
    * The image in the notice is using the 60*60 logo instead of the biggest (144*144) so it looks kind of crappy

  289. Hi! I can only get the debug and or stock android versions to work on my Samsung Avant. It was released last year, 2014. I setup a page using the debug and it fails when I turn off displayPace but all other functions seem to be fine if I disable them.

    Also, If I were to run the site using the stock android version, how do I get it to no longer appear on revisits via the web app when saved to home?

  290. Hi
    I’ve set this up on my site and am tracking the User agent of the people that add the site to their homescreen via the onAdd function.
    The thing is I’m getting a lot of desktop browsers reporting that they have added the site to their homescreen, here are a couple of user agent examples

    Mozilla/5.0 (Macintosh; Intel Mac OS X 10_5_8) AppleWebKit/534.50.2 (KHTML, like Gecko) Version/5.0.6 Safari/533.22.3

    Mozilla/5.0 (Windows NT 6.1; WOW64; rv:42.0) Gecko/20100101 Firefox/42.0

    I’m concerned that these people are being bugged on their desktops, is that likely?

  291. add hello as you leave the main url of the web and not the other urls?
    and how I can change the title of the main web links and not others?

    I feel bad translation yet.

  292. Hi, my site is a joomla and I canot managed to put the files no local Right. Any tutorial or suggestion . Many thanks

  293. Last weekend Firefox launched its Browser for iOS.
    The add2home arrow points to the refresh-button.

    Since it is not possible to add webclips to the homescreen via firefox it would make sense to check if browser is firefox on ios then not to show the add2home box.

    Opera for iOS is showing it also and should be not displayed too.

    Chrome Browser for iOS is not showing the add2homebox..which is good.

  294. This isn’t working for me. It’s the second iPhone bubble JS I’ve tried today – the other only seems to only have Japanese and French translations in the Zip off github (which do load). So I tried this one, as it looked pretty straight forward. However it doesn’t load.

    I’m on IOS 9.2.1. on an iPhone6

    Anyone having similar issues?

  295. Hi! Will not be original and first of all I want to thank you for the script. My doughnut in the form of $$!

    Question on script: I need to block the page on a smartphone (the app is installed or not – no difference), what would the content be viewed via the web application. But the script that I use, works once: once locks the screen, second time not, and so on. In addition, such a script does not want to work on android. Here’s the script itself:

    mandatory: true,
    lifespan: 512000
    var addtohome = addToHomescreen({
    autostart: false

    The page with the script:

  296. The FIX for google Chrome: window.navigator.standalone issue. This was copied from so I cannot take credit.

    Recently Google has implemented the CSS conditional display-mode: standalone, so there are two possible ways to detect if an app is running standalone:

    Using CSS:

    @media all and (display-mode: standalone) {
    /* Here goes the CSS rules that will only apply if app is running standalone */

    Using both CSS and Javascript:

    function isRunningStandalone() {
    return (window.matchMedia(‘(display-mode: standalone)’).matches);

    if (isRunningStandalone()) {
    /* This code will be executed if app is running standalone */

  297. Hi,

    the Bower component with version 3.2.2 contains the correct .js file, but the .css file is still old without the ios9 support.

    1. Where i can download the correct js file and css file for support IOS 9?


      1. Hi, just use the current version on GitHub. You only get problems if you install it with bower and try to use the tagged 3.2.2 version.

  298. Hello Matteo, is there a way that I can use Addtohomescreen pop up on different pages? Particularly page people land on?

  299. made mine a button to show

    function showdownload(){
    mandatory: true,
    lifespan: 512500


    Save To HomeScreen

  300. Hi,

    Firstly thanks a lot for this valuable information. I want know to know that i am having a website. So i want when people will visit or open my website, my website should automatically get saved as a home page of that visitor browser. Is there any way or solutions. Please help me out. Thanks

  301. First of all thanks! It’s working great on all devices I’ve tried so far except on the iPhone 6. Does anyone have a solution or a workaround?


    1. Having the same issue. Perhaps this is due to ios9 compatibility problems? I get no console errors, and no add to homescreen notification on iphone6s.

      1. Update: managed to get it working by turning on logging and finding out why it wouldn’t display. It appears to have hit the lifetime max number of displays before it displayed once. I turned that limitation off and now it works. Thanks for the code library! That’s a big help.

  302. When calling show(true) there is a small delay that causes a little user confusion. Looks like that is due to show calling _delayedShow which is also used to show the dialog the first time using an appropriate delay.

    Would be good if show() could be told to show immediately – perhaps with an additional arg.

  303. works great but it wants to put it on the last screen of the phone instead of the home screen. Is there a way to force it to be on the home screen?

    1. I suspect that’s simply because you don’t have room on your first home page?

  304. Thank you so much for this! If you can provide some specific details on how to get it working with iOS 9.3, that would be great.

  305. I just donated 10 bucks if that helps you to update this very useful tool.
    Thanks and hope you find the time!

  306. Hey, is there any way to enforce that the “X” button is the only way to close the pop-up? Right now, clicking anywhere on the popup closes it. Thanks in advance!

  307. I am a bit confused, what does visit mean? If I am just going through the site or just refreshing, does that mean second visit?

    1. it’s any “hit” to the webpage. it doesn’t take into account sessions

  308. Hi there,

    first of all a big big thank you for developing this script.
    I added this to a site and it works fine everywhere: Android/Chrome, an old iPod touch/Safari, an iPad/Safari and even in debug mode on every desktop browser – except iPhone. Neither in iPhone 6 nor in v5 or v4 there is any appearance of the overlay.

    I loaded the newest version from GitHub, but no change – maybe you have still an idea wht’s wrong?

    Thank you and best wishes,

    1. Well, I found out what was wrong: all iPhones I tested this private mode was activated. If you deactivate private mode, the script works perfectly 🙂

  309. Anyone able to help with google analytics event tracking? I’d like to measure if a user got “add to home screen dialog”, that is all.

  310. I’m on an iphone 5 with iOS 9.3.2 and when I loaded the live demo link

    it worked fine and the add to homescreen icon/message was displayed. However, when I reloaded the page, could not get the icon/message to display again. Tried a few more times but the icon/message was only displayed once. Is the icon/message supposed to reload/display each time you reload the page or is it only supposed to display once?

    Also copied the demos/simple/index.html code and customized it on our domain as follows:

    maxDisplayCount: 10

    When I loaded the page, it would not even display the icon/message. Changed it to “maxDisplayCount: 0” (as the default for index.html), but same thing – could never get the icon/message to display.

    I feel like I’m doing something wrong but cannot figure out why the install icon/message never displays again.

    1. David, you need to change the number “1” below to the maximum number of times you want to display the icon in the same device:

      skipFirstVisit: true,
      maxDisplayCount: 1 (INCREASE THIS NUMBER)

      1. Also, change:
        skipFirstVisit: true

        skipFirstVisit: False

        to display the icon since the first time.

  311. Hi. Thank for your script.
    But I have a question. I added this script to my site and it work fine on iOS. However on other mobile device (exam Android) I get the message (only text non-styled). In Chrome emulator I can’t reproduce this, only on real devices.

    1. Oh, sorry… Script works great. The problem is only my own error…
      But I have another question:) Can I running it only for iOS, not Android?

  312. Hi Matteo,
    I noticed there is a difference between the .js and .min.js files. In the .js file the ios message for nl_nl starts with ‘Om deze webapp aan je startscherm toe te voegen’. In the .min.js file this message starts with ‘Om deze webapp op je telefoon te installeren’. The .min.js file should probably be regenerated?

  313. Hey Matteo

    Thanks a lot for this. I have a question is there anyway to make it so that the bookmark saves a different link. I’m not a master JS guy so it maybe a silly question.


  314. Hello,

    My users don’t ever go thru the HOME page, instead they are directed to specific pages on my website that they want to look at. Where do I need to place each of the scripts so that they will run when someone links directly to an internal page on my website?

    Thanks for the help,


  315. When I poen the site in mobile, the pop up appeers in some overlay over the screen, so I don’t see any content until the popup time is over. What can I do to fix it? I want the popup to apeer over the cotent of the page.

  316. This part of the code is incorrect:

    // try to get the highest resolution application icon
    if ( !this.applicationIcon ) {
    this.applicationIcon = document.querySelector(‘head link[rel^=apple-touch-icon][sizes=”192×192″],head link[rel^=apple-touch-icon][sizes=”152×152″],head link[rel^=apple-touch-icon][sizes=”120×120″],head link[rel^=apple-touch-icon][sizes=”76×76″],head link[rel^=apple-touch-icon][sizes=”60×60″],head link[rel^=apple-touch-icon]’);

    This will obtain the first node in the DOM that matches ANY of the listed selectors, instead of attempting the listed selectors in order. Thus, there is no guarantee that the highest-resolution icon will be selected. This could resolve this issue:

    // try to get the highest resolution application icon
    if ( !this.applicationIcon ) {
    this.applicationIcon = document.querySelector(‘head link[rel^=apple-touch-icon][sizes=”192×192″]’);
    if ( !this.applicationIcon ) {
    this.applicationIcon = document.querySelector(‘head link[rel^=apple-touch-icon][sizes=”152×152″]’);
    if ( !this.applicationIcon ) {
    this.applicationIcon = document.querySelector(‘head link[rel^=apple-touch-icon][sizes=”120×120″]’);
    if ( !this.applicationIcon ) {
    this.applicationIcon = document.querySelector(‘head link[rel^=apple-touch-icon][sizes=”76×76″]’);
    if ( !this.applicationIcon ) {
    this.applicationIcon = document.querySelector(‘head link[rel^=apple-touch-icon][sizes=”60×60″]’);
    if ( !this.applicationIcon ) {
    this.applicationIcon = document.querySelector(‘head link[rel^=apple-touch-icon]’);

  317. I looked through the source but had a hard time finding out all the animation types. From the comments I saw:
    – animationIn: ‘bubble’
    – animationIn: ‘drop’

    Are there others? What’s the full list?

  318. Hello Matteo! Great script!!

    Could you give me one usage example of message custom option?
    message: ‘some text message here’;
    How can I change specific language and OS message? (without changing the defaults)
    Example: Customizing the message for iOS (portuguese) and another for Android (portuguese)


  319. Really struggling to get this working for some reason! I’ve copied the src, style and imgs folders into my home folder along with the ‘simple’ demo index.html. I’ve altered the references in the index.html so they point to the right places, but can’t get it to work on my iPhone 6S. The live demo link at the top of this page works fine. Can anyone suggest what I might be missing?

  320. Once the pop up has been dismissed by clicking the “X”, will it still show again after 1440 minutes?

  321. Hi guys,

    our website is a WordPress website, i’ve placed the ATH folder somewhere and call the .js function in the header file with giving the full path of the files. the ATH didn’t work.
    wondering where to locate the .js file? how to pass the .js and .css path in the header file? (I mean a full path like public_html/wp-content/themes/jupiter/ATH/style/addtohomescreen.css or not)

    thanks for your help

  322. Is there a way to customize the URL that is added on the home screen. I would like to set it to the home page. However, when I use this to add the icon, the default URL shown is the page on which the user is.

  323. HI could you please provide the demo / sample code for the language display based on the language setting ?

    The reason why i need is because I did switched my phone language to chinese but still display in english.

    1. Does it support Bahasa Malaysia language ? May i know the code of it ?

  324. i have 2 different pages within the same site that i would like to have this run on, each page having its own settings and session cookie. so that either page can be independently placed on the homescreen. How do i have seperate session instances of this within the same site?

    1. nevermind, i found the answer. looked right past it so many times.

  325. Hi, thanks for your work.
    On debug mode, both debug:’ ios’; or debug: ‘android’ on Chrome all work correctly. But when testing on devices, I’m not seeing the icon on ios devices.
    I use such meta.
    meta(name=’apple-mobile-web-app-capable’, content=’yes’)
    meta(name=’mobile-web-app-capable’, content=’yes’)
    meta(name=’apple-mobile-web-app-title’, content=’Add to Home’)
    link(rel=’shortcut icon’, sizes=’16×16′, href=’../images/ath-app-icon.svg’)
    link(rel=’shortcut icon’, sizes=’196×196′, href=’../images/ath-app-icon.svg’)
    link(rel=’apple-touch-icon-precomposed’, href=’../images/ath-app-icon.svg’)

    How do I not see the icon on the ios? Thanks.

  326. Also, when O testing on mobile and emulator, only one time ATH appears, and after reload not working.

  327. Hi! i need show the message every time, except is already in the homescreen. How i can do it?

  328. Hi Matteo,
    First of all – thanks for a great script!

    Is there any issues regarding SSL and ATH?
    If I enable https the message doesn’t show up. On regular http it works out of the box

    1. Hello Matteo,

      What a great script but unfortunately, I must use https and .. like Preben, over http everything is working fine but nothing happens through https .. any idea/comments about this issue ?

      Thank you really much in advance !

  329. Hi,

    I have followed the mention steps


    ath.defaults = {
    appID: ‘org.cubiq.addtohome’, // local storage name (no need to change)
    fontSize: 15, // base font size, used to properly resize the popup based on viewport scale factor
    debug: false, // override browser checks
    logging: false, // log reasons for showing or not showing to js console; defaults to true when debug is true
    modal: false, // prevent further actions until the message is closed
    mandatory: true, // you can’t proceed if you don’t add the app to the homescreen
    autostart: true, // show the message automatically
    skipFirstVisit: false, // show only to returning visitors (ie: skip the first time you visit)
    startDelay: 10, // display the message after that many seconds from page load
    lifespan: 15, // life of the message in seconds
    displayPace: 0, // minutes before the message is shown again (0: display every time, default 24 hours)
    maxDisplayCount: 0, // absolute maximum number of times the message will be shown to the user (0: no limit)
    icon: true, // add touch icon to the message
    message: ‘ADD TO HOME SCREEN’, // the message can be customized
    validLocation: [], // list of pages where the message will be shown (array of regexes)
    onInit: true, // executed on instance creation
    onShow: null, // executed when the message is shown
    onRemove: null, // executed when the message is removed
    onAdd: null, // when the application is launched the first time from the homescreen (guesstimate)
    onPrivate: null, // executed if user is in private mode
    privateModeOverride: false, // show the message even in private mode (very rude)
    detectHomescreen: ‘’ // try to detect if the site has been added to the homescreen (false | true | ‘hash’ | ‘queryString’ | ‘smartURL’)

    but unable to get the pop up for add to home screen
    please suggest
    Thanks in advance

  330. Hi, is there any way to specify that the “X” button is the only way to close the pop-up?
    Right now, clicking anywhere on the popup closes it. Thanks everyone!

  331. For those who implement this Javascript widget and don’t see anything happening on their website, try: F12 in Google Chrome > “Console” tab

    If you see the error “Cannot read property ‘appendChild’ of null” try to load the script before the closing BODY tag instead of loading it earlier:


    (the problem being that the script is running before some elements are available)

  332. Hey Matteo, first of all thank you for your work, love the improvements, hopefully I will be able to help and solve some doubts at the same time, first of all I found this piece of code on stack overflow:

    isInWebAppiOS = (window.navigator.standalone == true);
    isInWebAppChrome = (window.matchMedia(‘(display-mode: standalone)’).matches);

    This immediately jumped at me cause I remembered reading on this post that your script has some issues when trying to detect if the app in running as a web app in Android, I did some testing (OnePlus One running Android 7.1 and other Android phones from my friends) and it worked every time.

    Second, in Mexico the language code for spanish in Safari is ‘es_xl’ and ‘es_419’ on Android/Chrome and the translation included in ‘es_es’ also fits perfectly for this region.

    Now the issue I’m having, I don’t know if it’s related to this but the X to close the notice still shows up in Android even when you set the mandatory option to true.

    Thanks once again

  333. Thank you for this!

    I was wondering how to change the icon that appears once you get to the “Add to Home” screen on iOS. Any ideas?

      1. really how did you do it.

        My Activities
        <link rel="stylesheet" type="text/css" href="assets/bootstrap/css/addtohomescreen.css”>
        <link rel="stylesheet" type="text/css" href="assets/bootstrap/css/bootstrap.min.css”>
        <link rel="stylesheet" type="text/css" href="assets/fullcalendar/fullcalendar.css” >
        <link rel="stylesheet" type="text/css" href="assets/fullcalendar/fullcalendar.print.css” media=”print”>
        <link rel="stylesheet" type="text/css" href="”>
        <script type="text/javascript" src="assets/bootstrap/js/jquery.js”>
        <script type="text/javascript" src="assets/fullcalendar/lib/moment.min.js”>
        <script type="text/javascript" src="assets/bootstrap/js/bootstrap.min.js”>
        <script type="text/javascript" src="assets/bootstrap/js/fullcalendar_init.js”>
        <script type="text/javascript" src="assets/fullcalendar/fullcalendar.min.js”>
        <script type="text/javascript" src="”>
        <script type="text/javascript" src="assets/bootstrap/js/music_custom.js”>
        <script type="text/javascript" src="assets/bootstrap/js/addtohomescreen.js”>

        <link rel="shortcut icon" sizes="16×16" href="assets/imgs/icon-16×16.png”>
        <link rel="shortcut icon" sizes="196×196" href="assets/imgs/icon-196×196.png”>
        <link rel="apple-touch-icon-precomposed" href="assets/imgs/icon-152×152.png”>

        1. don’t mind the code when i tried the code it wont work how did you manage it.

  334. Hi Matteo

    I’m not entirely sure where I’m going wrong but I can’t seem to get this working on either an Android device or an iPhone. I’ve tried placing the script before the closing body tag but it has no effect – I see nothing. I don’t even get any console errors. I’ve got Android 5 on a Nexus 7 and 10.3.2 on iOS – both using Chrome

    I can’t even get the demos to work right now! 🙂 so clearly it’s just me being an idiot but I can’t work out where I’m being one.

    Can anyone point me to an instance of where it’s working so I can look at the source and see where I’m going wrong

    1. fixed it myself – it was conflicting with other JavaScripts on the page. Needed relocating

  335. For some reason I’m having problems with it showing up for me.
    Here’s my code

    Untitled Document


    you’re on the right page

    Just wondering if you could help

  336. Hi there
    great job.

    However, it seems that the language is not detected correctly.
    It is always set to English in spite of the different (Spanish or Italian) language of the browser.
    How can we fix this?

  337. Hi Matteo

    Following Language Part works for SwissGerman. It’s missing in your code 😉

    de_ch: {
    ios: ‘Um diese Web-App zum Home-Bildschirm hinzuzufügen, tippen Sie auf %icon und dann Zum Home-Bildschirm.’,
    android: ‘Um diese Web-App zum Home-Bildschirm hinzuzufügen, öffnen Sie das Menü und tippen dann auf Zum Startbildschirm hinzufügen. Wenn Ihr Gerät eine Menütaste hat, lässt sich das Browsermenü über diese öffnen. Ansonsten tippen Sie auf %icon.’

    thanks and greetings

  338. Hi,
    Thanks for this script.

    When user clicks on ‘Add to Home’ screen option, short cut icon is created in the mobile device with the icon given in the following link tag. I want to have dynamic icon for the short cut created in the mobile device. Is this possible?

    In the ATH popup I have the image given in the following link tag.


  339. Great script Matteo!

    It would be really cool if the shortcut could be added with a button instead (or even activate the pop up), similar to the standard “Download on the App Store” and “Get it on Google Play” buttons. This way it could always be visible on the website even if its not being viewed on a phone, so that the user knows its “available” as a web app/home screen icon. I don’t think many people know websites can be added to their home screen like an app. I realize this wouldn’t “install” the website on a desktop computer (unless there’s an alternative add to Desktop function), but neither does the App Store and Google Play buttons – yet they are very effective as promoting the apps.

    Is there a way to perform this action with a link/button? If so, do you know how?

  340. Hi,
    I have added the plugin in my site. There is no problem while add to home screen in safari. It works fine. But, when i open the added home screen icon and start the work, if i click any button that should be worked as a javascript function, instead of that, every action that i click on my page refresh the whole page. For example, if i click on “notification” icon, this also refresh the whole page. How to prevent this?

Comments are closed.